Directory Services

DsGetDomainControllerInfo

The DsGetDomainControllerInfo function retrieves data about the domain controllers in a domain.

DWORD DsGetDomainControllerInfo(
  HANDLE hDs,
  LPTSTR DomainName,
  DWORD InfoLevel,
  DWORD* pcOut,
  VOID** ppInfo
);

Parameters

hDs
[in] Contains the bind handle to the directory service. This handle is returned by a call to the DsBind or DsBindWithCred functions.
DomainName
[in] Pointer to a null-terminated string that specifies the domain name.
InfoLevel
[in] Contains a value that indicates the version of the DS_DOMAIN_CONTROLLER_INFO structure to return. This can be one of the following values.
Value Meaning
1 The function provides the domain data in the DS_DOMAIN_CONTROLLER_INFO_1 structure format.
2 The function provides the domain data in the DS_DOMAIN_CONTROLLER_INFO_2 structure format.
pcOut
[out] Pointer to a DWORD variable that receives the number of items returned in ppInfo array.
ppInfo
[out] Pointer to a pointer variable that receives an array of DS_DOMAIN_CONTROLLER_INFO_* structures. The type of structures in this array is defined by the InfoLevel parameter. The caller must free this array, when it is no longer required, by using the DsFreeDomainControllerInfo function.

Return Values

If the function returns domain controller data, the return value is ERROR_SUCCESS. If the caller does not have the privileges to access the server objects, the return value is ERROR_SUCCESS, but the DS_DOMAIN_CONTROLLER_INFO structures could be empty.

If the function fails, the return value can be one of the following error codes.

Return Code Description
ERROR_DS_INTERNAL_FAILURE The version of the DS_DOMAIN_CONTROLLER_INFO structure returned by the domain controller did not match the version requested in InfoLevel.
ERROR_DS_OBJ_NOT_FOUND DomainName is not NULL and contains an invalid domain name.
ERROR_INVALID_PARAMETER One or more parameters are invalid.
ERROR_NOT_SUPPORTED The requested version of the directory service server extensions is unsupported.

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.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000/XP.
Header: Declared in Ntdsapi.h.
Library: Use Ntdsapi.lib.

See Also

DsBind, DsBindWithCred, DS_DOMAIN_CONTROLLER_INFO_1, DS_DOMAIN_CONTROLLER_INFO_2, DsFreeDomainControllerInfo, Domain Controller and Replication Management Functions