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.

Syntax

DWORD DsGetDcName(
  __in   LPCTSTR ComputerName,
  __in   LPCTSTR DomainName,
  __in   GUID *DomainGuid,
  __in   LPCTSTR SiteName,
  __in   ULONG Flags,
  __out  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 Server 4.0does not support remote calling of this function, so this computer name cannot be a Windows NT Server 4.0 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 does not contain 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	When called from a domain controller, specifies that the returned domain controller name should not be the current computer. If the current computer 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 Windows 2000 or later domain controller that supports directory service functions. 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 and later.
DS_DIRECTORY_SERVICE_6_REQUIRED	This flag encapsulates two key pieces of information. First, it identifies that the query is in need of a fully writable DC (Full DC), and second that it is imperative that it be a Windows Server 2008 Full DC or later. A Windows Server 2003 DC is not adequate. If one is not found then an error will be returned.
DS_FORCE_REDISCOVERY	Forces cached domain controller data to be ignored. When the DS_FORCE_REDISCOVERY flag is not specified, DsGetDcName may return cached domain controller data. If this flag is specified, DsGetDcName will not use cached information (if any exists) but will instead perform a fresh domain controller discovery. This flag should not be used under normal conditions, as using the cached domain controller information has better performance characteristics and helps to ensure that the same domain controller is used consistently by all applications. This flag should be used only after the application determines that the domain controller returned by DsGetDcName (when called without this flag) is not accessible. In that case, the application should repeat the DsGetDcName call with this flag to ensure that the unuseful cached information (if any) is ignored and a reachable domain controller is discovered.
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	This parameter indicates that the domain controller must have an IP address. In that case, 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 cannot 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_TRY_NEXTCLOSEST_SITE	When this flag is specified, DsGetDcName attempts to find a domain controller in the same site as the caller. If no such domain controller is found, it will find a domain controller that can provide topology information and call DsBindToISTG to obtain a bind handle, then call DsQuerySitesByCost over UDP to determine the "next closest site," and finally cache the name of the site found. If no domain controller is found in that site, then DsGetDcName falls back on the default method of locating a domain controller. If this flag is used in conjunction with a non-NULL value in the input parameter SiteName, then ERROR_INVALID_FLAGS is thrown. Also, the kind of search employed with DS_TRY_NEXT_CLOSEST_SITE is site-specific, so this flag is ignored if it is used in conjunction with DS_PDC_REQUIRED. Finally, DS_TRY_NEXTCLOSEST_SITE is ignored when used in conjunction with DS_RETURN_FLAT_NAME because that uses NetBios to resolve the name, but the domain of the domain controller found won't necessarily match the domain to which the client is joined. Note  This flag is Group Policy enabled. If you enable the "Next Closest Site" policy setting, Next Closest Site DC Location will be turned on for the machine across all available but un-configured network adapters. If you disable the policy setting, Next Closest Site DC Location will not be used by default for the machine across all available but un-configured network adapters. However, if a DC Locator call is made using the DS_TRY_NEXTCLOSEST_SITE flag explicitly, DsGetDcName honors the Next Closest Site behavior. If you do not configure this policy setting, Next Closest Site DC Location will be not be used by default for the machine across all available but un-configured network adapters. If the DS_TRY_NEXTCLOSEST_SITE flag is used explicitly, the Next Closest Site behavior will be used.
DS_WRITABLE_REQUIRED	Requires that the returned domain controller be writable; that is, host a writable copy of the directory service, for Windows 2000 and 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 Value

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.

Notes on Domain Controller Stickiness

In Active Directory Domain Services, the domain controller locator function is designed so that once a client finds a preferred domain controller, the client will not look for another unless that domain controller stops responding or the client is restarted. This is referred to as "Domain Controller Stickiness." Because workstations typically operate for months without a problem or restart, one unintended consequence of this behavior is that if a particular domain controller goes down for maintenance, all of the clients that were connected to it shift their connections to another domain controller. But when the domain controller comes back up, no clients ever reconnect to it because the clients don't restart very often. This can cause load-balancing problems.

Previously, the most common solution to this problem was to deploy a script on each client machine that periodically called DsGetDcName using the DS_FORCE_REDISCOVERY flag. This was a somewhat cumbersome solution, so Windows Server 2008 and Windows Vista introduced a new mechanism that caused issues with domain controller stickiness.

Whenever DsGetDcName retrieves a domain controller name from its cache, it checks to see if this cached entry is expired, and if so, discards that domain controller name and tries to rediscover a domain controller name. The "lifespan" of a cached entry is controlled by the value in the following registry keys

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\
     Netlogon\Parameters\ForceRediscoveryInterval

HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\
     Netlogon\Parameters\ForceRediscoveryInterval

Note  The registry settings of ForceRediscoveryInterval are group policy enabled. If you disable the policy setting, Force Rediscovery will used by default for the machine at every 12 hour interval. If you do not configure this policy setting, Force Rediscovery will used by default for the machine at every 12 hour interval, unless the local machine setting in the registry is a different value.

Note that if the DS_BACKGROUND_ONLY flag is specified, DsGetDcName will never try to rediscover the domain controller name, since the point of that flag is to force DsGetDcName to use the cached domain controller name even if it is expired.

ETW Tracing within DsGetDcName

To turn on ETW Tracing for DsGetDcName, create the following registry key:

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\
     DCLocator\Tracing

The key will have a structure as follows:

String ProcessName
		DWORD 	PID <optional>

ProcessName must be the full name including extension of the process that you want to get trace information for. PID is only required when multiple processes with the same name exist. If it is defined, then only the process with that PID will be enabled for tracing. It is not possible to trace only 2 out of 3 (or more) processes with the same name. You can enable one instance or all instances (when multiple instances with the same process name exist and PID is not specified, all instances will be enabled for tracing).

For example, this would trace all instances of App1.exe and App2.exe, but only the instance of App3.exe that has a PID of 999:

App1.exe 
App2.exe
App3.exe
			  PID 999 

Run the following command to start the tracing session:

tracelog.exe -start <sessionname> -guid #cfaa5446-c6c4-4f5c-866f-31c9b55b962d -f <filename> -flag <traceFlags>

sessionname is the name given for the trace session. The guid for the DCLocator tracing provider is "cfaa5446-c6c4-4f5c-866f-31c9b55b962d". filename is the name of the log file to which the events are written. traceFlags is one or more of the following flags which signify which areas to trace:

Run the following command to stop the trace session:

tracelog.exe -stop <sessionname>

sessionname is the same name as the name you used when starting the session.

Note  The registry key for the process being traced must be present in the registry at the time the trace session is started. When the session starts, the process will verify whether or not it should be generating trace messages (based on the presence or absence of a registry key for that process name and optional PID). The process checks the registry only at the start of the session. Any changes in the registry occurring after that will not have any effect on tracing.

Requirements

See Also

GUID
DOMAIN_CONTROLLER_INFO
DsGetSiteName
DsValidateSubnetName
NetApiBufferFree
Directory Service Functions

Send comments about this topic to Microsoft

Build date: 10/9/2008