Directory Services

DsUnquoteRdnValue

The DsUnquoteRdnValue function is a client call that converts a quoted RDN value back to an unquoted RDN value. Since the RDN was originally put into quotes because it contained characters that could be misinterpreted when it was embedded within a distinguished name (DN), the unquoted RDN value should not be submitted as part of a DN to the directory service using various APIs such as LDAP.

DWORD DsUnquoteRdnValue(
  DWORD cQuotedRdnValueLength,
  LPCTCH psQuotedRdnValue,
  DWORD* pcUnquotedRdnValueLength,
  LPTCH psUnquotedRdnValue
);

Parameters

cQuotedRdnValueLength

[in] The number of characters in the psQuotedRdnValue string.

psQuotedRdnValue

[in] The RDN value that may be quoted and escaped.

pcUnquotedRdnValueLength

[in, out] The input value for this argument is the maximum length of psUnquotedRdnValue, in chars

The output value for this argument includes the following flags:

Value	Meaning
ERROR_SUCCESS	This is returned if the number of characters match the string used in psUnquotedRdnValue.
ERROR_BUFFER_OVERFLOW	This is returned if the number of characters do not match the string used in psUnquotedRdnValue.

psUnquotedRdnValue

[out] The converted, unquoted RDN value.

Return Values

The following list contains the possible values that are returned for the DsUnquoteRdnValue function:

Return Code	Description
ERROR_SUCCESS	If successful, the psUnquotedRdnValue argument contains the unquoted and unescaped version of psQuotedRdnValue. The pcUnquotedRdnValueLength parameter contains the length of the character string.
ERROR_BUFFER_OVERFLOW	Indicates an inconsistency between the length of the character string given in psUnquotedRdnValueLength and the number of characters in the output for psUnquotedRdnValue.
ERROR_INVALID_PARAMETER	Indicates that there is an invalid parameter.
ERROR_NOT_ENOUGH_MEMORY	Indicates that there is an allocation error.

Remarks

When psQuotedRdnValue is quoted:

The leading and trailing quotes are removed.
Whitespace before the first quote is discarded.
Whitespace trailing the last quote is discarded.
Escapes are removed and the character following the escape is kept.

The following actions are taken when psQuotedRdnValue is unquoted:

The leading whitespace is discarded.
The trailing whitespace is kept.
Escaped non-special characters return an error.
Unescaped special characters return an error.
RDN values beginning with # (ignoring leading whitespace) are treated as a BER value that has previously been converted to a string, and converted accordingly.
Escaped hex digits (\89) are converted into a binary byte (0x89).
Escapes are removed from escaped special characters.

The following actions are always taken:

Escaped special characters are unescaped.
The input and output RDN values are not NULL terminated.

Requirements

Client: Included in Windows XP and Windows 2000 Professional.
Server: Included in Windows Server 2003 and Windows 2000 Server.
Redistributable: Requires Active Directory Client Extension on Windows NT 4.0 SP6a and Windows 95/98/Me.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000/XP.
Header: Declared in Ntdsapi.h.
Library: Use Ntdsapi.lib.

DsUnquoteRdnValue

Parameters

Return Values

Remarks

Requirements

See Also