Export (0) Print
Expand All

DsGetRdnW function

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


DWORD WINAPI DsGetRdnW(
  _Inout_  LPCWCH *ppDN,
  _Inout_  DWORD *pcDN,
  _Out_    LPCWCH *ppKey,
  _Out_    DWORD *pcKey,
  _Out_    LPCWCH *ppVal,
  _Out_    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 value

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

Return codeDescription
ERROR_DS_NAME_UNPARSEABLE

The distinguished name in the ppDN parameter cannot be parsed.

ERROR_INVALID_PARAMETER

One or more parameters are invalid.

 

Examples

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_s(pwszTemp, pwszKey, dwKeyLen);
                // Null-terminate the string.
                pwszTemp[dwKeyLen] = 0;
                // Print the key.
                wprintf(pwszTemp);
                
                wprintf(L":");

                // Copy the value.
                wcsncpy_s(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

Minimum supported client

Windows Vista

Minimum supported server

Windows Server 2003

Header

Dsparse.h (include Ntdsapi.h)

Library

Ntdsapi.lib

DLL

Ntdsapi.dll

See also

Domain Controller and Replication Management Functions

 

 

Show:
© 2014 Microsoft