DsGetDcNextA function (dsgetdc.h)

The DsGetDcNext function retrieves the next domain controller in a domain controller enumeration operation.

Syntax

DSGETDCAPI DWORD DsGetDcNextA(
  [in]            HANDLE           GetDcContextHandle,
  [out, optional] PULONG           SockAddressCount,
  [out, optional] LPSOCKET_ADDRESS *SockAddresses,
  [out, optional] LPSTR            *DnsHostName
);

Parameters

[in] GetDcContextHandle

Contains the domain controller enumeration context handle provided by the DsGetDcOpen function.

[out, optional] SockAddressCount

Pointer to a ULONG value that receives the number of elements in the SockAddresses array. If this parameter is NULL, socket addresses are not retrieved.

[out, optional] SockAddresses

Pointer to an array of SOCKET_ADDRESS structures that receives the socket address data for the domain controller. SockAddressCount receives the number of elements in this array.

All returned addresses will be of type AF_INET or AF_INET6. The sin_port member contains the port from the server record. A port of 0 indicates no port is available from DNS.

The caller must free this memory when it is no longer required by calling LocalFree.

This parameter is ignored if SockAddressCount is NULL.

[out, optional] DnsHostName

Pointer to a string pointer that receives the DNS name of the domain controller. This parameter receives NULL if no host name is known. The caller must free this memory when it is no longer required by calling NetApiBufferFree.

Return value

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

Remarks

To reset the enumeration, close the current enumeration by calling DsGetDcClose and then reopen the enumeration by calling DsGetDcOpen again.

The DC returned by DsGetDcNext will not be a Read-only DC (RODC) because those DCs only register site-specific and CName records, and both DsGetDcNext and DsGetDcOpen look for DNS SRV records.

The following procedure shows how to get a complete DC list from a computer running Windows Server 2008.

To obtain a complete list of domain controllers

  1. Use DsGetDcName to get a domain controller name.
  2. Use DsBind to connect to that domain controller.
  3. Call DsGetDomainControllerInfo with InfoLevel 3 (DS_DOMAIN_CONTROLLER_INFO_3) to get the complete list, including RODCs.

Note

The dsgetdc.h header defines DsGetDcNext as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

Requirement Value
Minimum supported client Windows Vista
Minimum supported server Windows Server 2008
Target Platform Windows
Header dsgetdc.h
Library Netapi32.lib
DLL Netapi32.dll

See also

Directory Service Functions

DsGetDcClose

DsGetDcOpen

Enumerating Domain Controllers

LocalFree

NetApiBufferFree

SOCKET_ADDRESS