DsGetRdnW

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.

DWORD WINAPI DsGetRdnW(
  LPCWCH* ppDN,
  DWORD* pcDN,
  LPCWCH* ppKey,
  DWORD* pcKey,
  LPCWCH* ppVal,
  DWORD* pcVal
);

Parameters

ppDN

[in, out] 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".

pcDN

[in, out] 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.

ppKey

[out] 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.

pcKey

[out] 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.

ppVal

[out] 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.

pcVal

[out] 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 Values

Example Code [C++]

The following code example demonstrates how to use the DsGetRdnW function to print all of the relative distinguished names in a distinguished name string.

#include <windows.h>
#include <stdio.h>
#include <ntdsapi.h>
#include <atlbase.h>

// Get the rootDSE.
HRESULT hr;
CComPtr<IADs> spRoot;
hr = ADsOpenObject(L"LDAP://rootDSE",
			NULL,
			NULL,
			ADS_SECURE_AUTHENTICATION,
			IID_IADs,
			(void**)&spRoot);

if(SUCCEEDED(hr))
{
	CComVariant svar;

	// Get the DN of the domain the local machine is in.
	hr = spRoot->Get(CComBSTR(L"defaultNamingContext"), &svar);
	if(SUCCEEDED(hr))
	{
		LPCWCH pwszDN;
		LPCWCH pwszKey;
		LPCWCH pwszVal;
		DWORD dwDNLen;
		DWORD dwKeyLen;
		DWORD dwValLen;

		pwszDN = svar.bstrVal;
		dwDNLen = wcslen(pwszDN);

		while(ERROR_SUCCESS == DsGetRdnW(   &pwszDN, 
											&dwDNLen,
											&pwszKey,
											&dwKeyLen,
											&pwszVal,
											&dwValLen))
		{
			if(0 == dwKeyLen || 0 == dwValLen)
			{
				// An error occurred. Attempt to retrieve the next RDN.
				continue;
		}
		
			LPWSTR pwszTemp = new WCHAR[max(dwKeyLen, dwValLen) + 1];

			if(NULL != pwszTemp)
			{
				// Copy the key.
				wcsncpy(pwszTemp, pwszKey, dwKeyLen);
				// Null-terminate the string.
				pwszTemp[dwKeyLen] = 0;
				// Print the key.
				wprintf(pwszTemp);
			
				wprintf(L":");

				// Copy the value.
				wcsncpy(pwszTemp, pwszVal, dwValLen);
				// Null-terminate the string.
				pwszTemp[dwValLen] = 0;
				// Print the value.
				wprintf(pwszTemp);

				wprintf(L"\n");

				delete pwszTemp;
		}

			// Exit the loop when the end of the DN has been reached.
			if(0 == dwDNLen)
			{
				break;
		}
	}
}

	spRoot.Release();
}

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.
Header: Declared in Ntdsapi.h.
Library: Use Ntdsapi.lib.

See Also

Domain Controller and Replication Management Functions