Export (0) Print
Expand All

DsUnquoteRdnValue function

The DsUnquoteRdnValue function is a client call that converts a quoted RDN value back to an unquoted RDN value. Because 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.

Syntax


DWORD DsUnquoteRdnValue(
  _In_     DWORD cQuotedRdnValueLength,
  _In_     LPCTCH psQuotedRdnValue,
  _Inout_  DWORD *pcUnquotedRdnValueLength,
  _Out_    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, in characters, of psQuotedRdnValue.

The output value for this argument includes the following flags.

ValueMeaning
ERROR_SUCCESS

This is returned if the number of characters match the string used in psQuotedRdnValue.

ERROR_BUFFER_OVERFLOW

This is returned if the number of characters do not match the string used in psQuotedRdnValue.

 

psUnquotedRdnValue [out]

The converted, unquoted RDN value.

Return value

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

Return codeDescription
ERROR_SUCCESS

If successful, the psQuotedRdnValue 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 pcUnquotedRdnValueLength and the number of characters in the output for psQuotedRdnValue.

ERROR_INVALID_PARAMETER

Indicates an invalid parameter.

ERROR_NOT_ENOUGH_MEMORY

Indicates an allocation error.

 

Remarks

When psQuotedRdnValue is quoted:

  • The leading and trailing quotes are removed.
  • White space before the first quote is discarded.
  • White space 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 white space is discarded.
  • The trailing white space is kept.
  • Escaped non-special characters return an error.
  • Unescaped special characters return an error.
  • RDN values beginning with # (ignoring leading white space) are handled 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 values.

Requirements

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Dsparse.h (include Ntdsapi.h)

Library

Ntdsapi.lib

DLL

Ntdsapi.dll

Unicode and ANSI names

DsUnquoteRdnValueW (Unicode) and DsUnquoteRdnValueA (ANSI)

See also

DsQuoteRdnValue
Domain Controller and Replication Management Functions

 

 

Show:
© 2014 Microsoft