Export (0) Print
Expand All
This topic has not yet been rated - Rate this topic

DsGetDcNext function

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

Syntax


DWORD WINAPI DsGetDcNext(
  _In_       HANDLE GetDcContextHandle,
  _Out_opt_  PULONG SockAddressCount,
  _Out_opt_  LPSOCKET_ADDRESS *SockAddresses,
  _Out_opt_  LPTSTR *DnsHostName
);

Parameters

GetDcContextHandle [in]

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

SockAddressCount [out, optional]

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.

SockAddresses [out, optional]

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.

DnsHostName [out, optional]

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.

Return codeDescription
ERROR_NO_MORE_ITEMS

The end of the enumeration has been reached.

ERROR_FILEMARK_DETECTED

The DS_NOTIFY_AFTER_SITE_RECORDS flag was specified in the OptionFlags parameter in DsGetDcOpen and the last of the site-specific domain controllers has been enumerated. DsGetDcNext will then retrieve all of the domain controllers in the domain, including the site-specific domain controllers already enumerated.

 

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.

ms675984.wedge(en-us,VS.85).gifTo 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.

Requirements

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Dsgetdc.h

Library

Netapi32.lib

DLL

Netapi32.dll

Unicode and ANSI names

DsGetDcNextW (Unicode) and DsGetDcNextA (ANSI)

See also

DsGetDcOpen
DsGetDcClose
SOCKET_ADDRESS
LocalFree
NetApiBufferFree
Enumerating Domain Controllers
Directory Service Functions

 

 

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft. All rights reserved.