DsGetRdnW function (dsparse.h)

The DsGetRdnW function retrieves the key and value of the first relative distinguished name and a pointer to the next relative distinguished name from a distinguished name string.

Syntax

DSPARSE DWORD DsGetRdnW(
  [in, out] LPCWCH *ppDN,
  [in, out] DWORD  *pcDN,
  [out]     LPCWCH *ppKey,
  [out]     DWORD  *pcKey,
  [out]     LPCWCH *ppVal,
  [out]     DWORD  *pcVal
);

Parameters

[in, out] ppDN

Address of a Unicode string pointer that, on entry, contains the distinguished name string to be parsed. The length of this string is specified in the pcDN parameter. If the function succeeds, this parameter is adjusted to point to the remainder of the distinguished name exclusive of current relative distinguished name. For example, if this parameter points to the string "dc=corp,dc=fabrikam,dc=com", after the function is complete this parameter points to the string ",dc=fabrikam,dc=com".

[in, out] pcDN

Pointer to a DWORD value that, on entry, contains the number of characters in the ppDN string. If the function succeeds, this parameter receives the number of characters in the remainder of the distinguished name. These values do not include the null-terminated character.

[out] ppKey

Pointer to a LPCWCH value that, if the function succeeds, receives a pointer to the key in the relative distinguished name string. This pointer is within the ppDN string and is not null-terminated. The pcKey parameter receives the number of characters in the key. This parameter is undefined if pcKey receives zero.

[out] pcKey

Pointer to a DWORD value that, if the function succeeds, receives the number of characters in the key string represented by the ppKey parameter. If this parameter receives zero, ppKey is undefined.

[out] ppVal

Pointer to a LPCWCH value that, if the function is successful, receives a pointer to the value in the relative distinguished name string. This pointer is within the ppDN string and is not null-terminated. The pcVal parameter receives the number of characters in the value. This parameter is undefined if pcVal receives zero.

[out] pcVal

Pointer to a DWORD value that, if the function succeeds, receives the number of characters in the value string represented by the ppVal parameter. If this parameter receives zero, ppVal is undefined.

Return value

Returns ERROR_SUCCESS if successful or a Win32 error code otherwise. Possible error codes include the following values.

Requirements

Requirement	Value
Minimum supported client	Windows Vista
Minimum supported server	Windows Server 2008
Target Platform	Windows
Header	dsparse.h (include Ntdsapi.h)
Library	Ntdsapi.lib
DLL	Ntdsapi.dll

See also

Domain Controller and Replication Management Functions