DsGetDcName

The DsGetDcName function returns the name of a domain controller in a specified domain. This function accepts additional domain controller selection criteria to indicate preference for a domain controller with particular characteristics.

DWORD DsGetDcName(
  LPCTSTR ComputerName,
  LPCTSTR DomainName,
  GUID* DomainGuid,
  LPCTSTR SiteName,
  ULONG Flags,
  PDOMAIN_CONTROLLER_INFO* DomainControllerInfo
);

Parameters

ComputerName

[in] Pointer to a null-terminated string that specifies the name of the server to process this function. Typically, this parameter is NULL, that indicates the local computer is used. Windows NT 4.0 server does not support remote calling of this function, so this computer name cannot be a Windows NT 4.0 server unless it is the local computer.

DomainName

[in] Pointer to a null-terminated string that specifies the name of the domain or application partition to query. This name can either be a DNS style name, for example, fabrikam.com, or a flat-style name, for example, Fabrikam. If a DNS style name is specified, the name may be specified with or without a trailing period.

If the Flags parameter contains the DS_GC_SERVER_REQUIRED flag, DomainName must be the name of the forest. In this case, DsGetDcName fails if DomainName specifies a name that is not the forest root.

If the Flags parameter contains the DS_GC_SERVER_REQUIRED flag and DomainName is NULL, DsGetDcName attempts to find a global catalog in the forest of the computer identified by ComputerName, which is the local computer if ComputerName is NULL.

If DomainName is NULL and the Flags parameter contains the DS_GC_SERVER_REQUIRED flag, ComputerName is set to the default domain name of the primary domain of the computer identified by ComputerName.

DomainGuid

[in] Pointer to a GUID structure that specifies the GUID of the domain queried. If DomainGuid is not NULL and the domain specified by DomainName or ComputerName cannot be found, DsGetDcName attempts to locate a domain controller in the domain having the GUID specified by DomainGuid.

SiteName

[in] Pointer to a null-terminated string that specifies the name of the site where the returned domain controller should physically exist. If this parameter is NULL, DsGetDcName attempts to return a domain controller in the site closest to the site of the computer specified by ComputerName. This parameter should be NULL, by default.

Flags

[in] Contains a set of flags that provide additional data used to process the request. This parameter can be a combination of the following values.

Value	Meaning
DS_AVOID_SELF	Specifies that the domain controller returned should not be the domain controller named by ComputerName. If ComputerName is not a domain controller, this flag is ignored. This flag can be used to obtain the name of another domain controller in the domain.
DS_BACKGROUND_ONLY	If the DS_FORCE_REDISCOVERY flag is not specified, this function uses cached domain controller data. If the cached data is more than 15 minutes old, the cache is refreshed by pinging the domain controller. If this flag is specified, this refresh is avoided even if the cached data is expired. This flag should be used if the DsGetDcName function is called periodically.
DS_DIRECTORY_SERVICE_PREFERRED	DsGetDcName attempts to find a domain controller that supports directory service functions (Microsoft® Windows® 2000 or later). If a domain controller that supports directory services is not available, DsGetDcName returns the name of a non-directory service domain controller. However, DsGetDcName only returns a non-directory service domain controller after the attempt to find a directory service domain controller times out.
DS_DIRECTORY_SERVICE_REQUIRED	Requires that the returned domain controller support Windows 2000 or later.
DS_FORCE_REDISCOVERY	Forces cached domain controller data to be ignored. This flag is used when an additional domain controller becomes available or where a domain controller has previously been detected to be unavailable. When this flag is not specified, DsGetDcName may return cached domain controller data. Do not use this flag unless DsGetDcName has been recently called without this flag and has successfully returned a domain controller. This flag is normally not used and should only be used if a previous call to DsGetDcName without this flag has failed.
DS_GC_SERVER_REQUIRED	Requires that the returned domain controller be a global catalog server for the forest of domains with this domain as the root. If this flag is set and the DomainName parameter is not NULL, DomainName must specify a forest name. This flag cannot be combined with the DS_PDC_REQUIRED or DS_KDC_REQUIRED flags.
DS_GOOD_TIMESERV_PREFERRED	DsGetDcName attempts to find a domain controller that is a reliable time server. The Windows Time Service can be configured to declare one or more domain controllers as a reliable time server. For more information, see the Windows Time Service documentation. This flag is intended to be used only by the Windows Time Service.
DS_IP_REQUIRED	DsGetDcName will place the Internet protocol address of the domain controller in the DomainControllerAddress member of DomainControllerInfo.
DS_IS_DNS_NAME	Specifies that the DomainName parameter is a DNS name. This flag cannot be combined with the DS_IS_FLAT_NAME flag. Specify either DS_IS_DNS_NAME or DS_IS_FLAT_NAME. If neither flag is specified, DsGetDcName may take longer to find a domain controller because it may have to search for both the DNS-style and flat name.
DS_IS_FLAT_NAME	Specifies that the DomainName parameter is a flat name. This flag canot be combined with the DS_IS_DNS_NAME flag.
DS_KDC_REQUIRED	Requires that the returned domain controller be currently running the Kerberos Key Distribution Center service. This flag cannot be combined with the DS_PDC_REQUIRED or DS_GC_SERVER_REQUIRED flags.
DS_ONLY_LDAP_NEEDED	Specifies that the server returned is an LDAP server. The server returned is not necessarily a domain controller. No other services are implied to be present at the server. The server returned does not necessarily have a writable config container nor a writable schema container. The server returned may not necessarily be used to create or modify security principles. This flag may be used with the DS_GC_SERVER_REQUIRED flag to return an LDAP server that also hosts a global catalog server. The returned global catalog server is not necessarily a domain controller. No other services are implied to be present at the server. If this flag is specified, the DS_PDC_REQUIRED, DS_TIMESERV_REQUIRED, DS_GOOD_TIMESERV_PREFERRED, DS_DIRECTORY_SERVICES_PREFERED, DS_DIRECTORY_SERVICES_REQUIRED, and DS_KDC_REQUIRED flags are ignored.
DS_PDC_REQUIRED	Requires that the returned domain controller be the primary domain controller for the domain. This flag cannot be combined with the DS_KDC_REQUIRED or DS_GC_SERVER_REQUIRED flags.
DS_RETURN_DNS_NAME	Specifies that the names returned in the DomainControllerName and DomainName members of DomainControllerInfo should be DNS names. If a DNS name is not available, an error is returned. This flag cannot be specified with the DS_RETURN_FLAT_NAME flag. This flag implies the DS_IP_REQUIRED flag.
DS_RETURN_FLAT_NAME	Specifies that the names returned in the DomainControllerName and DomainName members of DomainControllerInfo should be flat names. If a flat name is not available, an error is returned. This flag cannot be specified with the DS_RETURN_DNS_NAME flag.
DS_TIMESERV_REQUIRED	Requires that the returned domain controller be currently running the Windows Time Service.
DS_WRITABLE_REQUIRED	Requires that the returned domain controller be writable; that is, host a writable copy of the directory service, for Windows 2000 or later DCs, or of SAM (for DCs in operating systems prior to Windows 2000). A DC in an operating system prior to Windows 2000 is writable only if it is a primary domain controller. All Windows 2000 domain controllers are writable.

DomainControllerInfo

[out] Pointer to a PDOMAIN_CONTROLLER_INFO value that receives a pointer to a DOMAIN_CONTROLLER_INFO structure that contains data about the domain controller selected. This structure is allocated by DsGetDcName. The caller must free the structure using the NetApiBufferFree function when it is no longer required.

Return Values

If the function returns domain controller data, the return value is ERROR_SUCCESS.

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

Remarks

The DsGetDcName function is sent to the Netlogon service on the remote computer specified by ComputerName. If ComputerName is NULL, the function is processed on the local computer.

DsGetDcName does not verify that the domain controller name returned is the name of an actual domain controller or global catalog. If mutual authentication is required, the caller must perform the authentication.

DsGetDcName does not require any particular access to the specified domain. By default, this function does not ensure that the returned domain controller is currently available. Instead, the caller should attempt to use the returned domain controller. If the domain controller is not available, the caller should call the DsGetDcName function again, specifying the DS_FORCE_REDISCOVERY flag.

With the DSClient for Windows 95/98, the DsGetDcName function is exported from Logonsrv.dll and there is no corresponding library file. Be aware that this differs from Windows 2000, where DsGetDcName is exported by Netapi32.dll and the library file is Netapi32.lib.

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 Dsgetdc.h.
Library: Use Netapi32.lib.

See Also

GUID, DOMAIN_CONTROLLER_INFO, DsGetSiteName, DsValidateSubnetName, NetApiBufferFree, Directory Service Functions