DsGetDcName

[This is preliminary documentation and subject to change.]

The DsGetDcName function returns the name of a domain controller (DC) in a specified domain. You can supply DC selection criteria are to this function to indicate preference for a DC with particular characteristics.

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

Parameters

ComputerName

Pointer to a null-terminated string that specifies the name of the remote server to process this function. Typically, this parameter should be specified as NULL.

DomainName

Pointer to a null-terminated string that specifies the name of the domain to query. This name can either be a DNS-style name (for example, microsoft.com.) or a flat-style name (for example, microsoft). If a DNS-style name is specified, the name may be specified with or without a trailing period.

If NULL is specified and the DS_GC_SERVER_REQUIRED flag is specified, DomainName defaults to the tree name of the primary domain of ComputerName.

If NULL is specified and the DS_GC_SERVER_REQUIRED flag is not specified, DomainName defaults to the domain name of the primary domain of ComputerName.

DomainGuid

Pointer to a GUID structure that specifies the Domain GUID of the domain being queried. This value renames the domain. That is, if this value is specified and DomainName has been renamed, DsGetDcName attempts to locate a DC in the domain having the GUID specified by DomainGuid.

SiteName

Pointer to a null-terminated string that specifies the name of the site the returned DC should be physically near. The parameter should typically be the name of the site where the client is located. If not specified, SiteName defaults to the site of ComputerName.

Flags

Passes additional information to be used to process the request. This parameter can be a combination of the following values.

Value	Meaning
DS_FORCE_REDISCOVERY	Use this flag when an additional domain controller becomes available or where a domain controller has been detected to be unavailable. This function only guarantees the DC returned when the DC was initially entered into the cache. Do not specify this flag unless you have recently called this function without this flag. You should attempt to access the cached domain controller. Only if that access fails should you call again with this flag.
DS_DIRECTORY_SERVICE_REQUIRED	Requires that the returned DC support Windows NT 5.0 or later.
DS_DIRECTORY_SERVICE_PREFERRED	Prefers that the returned DC support directory service functions (Windows NT 5.0 or later). If no such DC is available, an earlier version of the DC returns. If a DC that supports a DS is not available, DsGetDcName returns the name of a non-DS DC. However, DsGetDcName returns only the non-DS DC information after the attempt to find a DS DC times out.
DS_GC_SERVER_REQUIRED	Requires that the returned DC be a global catalog (GC) server for the tree of domains with this domain as the root. This flag may not be set if any of the following flags are set: DS_WRITABLE_REQUIRED, DS_FDC_REQUIRED, or DS_PDC_REQUIRED.
DS_PDC_REQUIRED	Requires that the returned DC be the primary domain controller (PDC) for the domain. This flag may not be set if any of the following flags are set: DS_WRITABLE_REQUIRED, DS_FDC_REQUIRED, or DS_GC_SERVER_REQUIRED.
DS_WRITABLE_REQUIRED	Requires that the returned DC host a writable copy of the DS (or SAM). If the specified DomainName is a flat name, this flag is the same as DS_PDC_REQUIRED. If the specified DomainName is a DNS name, this flag finds writable DCs. Only the PDC is writable in a Windows NT 5.0 "mixed mode" domain. All DCs are writable in a Windows NT 5.0 "non-mixed mode" domain. In future releases of Windows NT, certain DCs may be configured as "read only"; such DCs are not writableIn future releases of Windows NT, certain DCs may be configured as "read only"; such DCs will not list themselves as writable. This flag may not be set if any of the following flags are set: DS_PDC_REQUIRED, DS_FDC_REQUIRED, or DS_GC_SERVER_REQUIRED.
DS_FDC_REQUIRED	Requires that the returned DC be the floating domain controller (FDC) for the domain. In a mixed domain with a Windows NT 3.x or Windows NT 4.0 PDC and one or more Windows NT 5.0 BDCs, one of the Windows NT 5.0 PDCs plays the special role of replicating account changes from the PDC. That DC is called the "floating" DC because the function "floats" to another Windows NT 5.0 BDC automatically if the current FDC becomes unavailable.This flag may not be set if any of the following flags are set: DS_PDC_REQUIRED, DS_WRITABLE_REQUIRED, or DS_GC_SERVER_REQUIRED.
DS_IP_REQUIRED	Requires that the IP address of the discovered DC be returned in DomainControllerAddress of the DOMAIN_CONTROLLER_INFO structure.
DS_KDC_REQUIRED	Requires that the returned DC be currently running the Kerberos Key Distribution Center service.
DS_TIMESERV_REQUIRED	Requires that the returned DC be currently running the Windows Time service.
DS_IS_FLAT_NAME	Specifies that the DomainName parameter is a flat name. As such, the IP/DNS compatible locator will not be attempted. This flag may not be specified with the DS_IS_DNS_NAME flag. It is valid to not set DS_IS_FLAT_NAME and DS_IS_DNS_NAME; however, DsGetDcName will take longer to find a DC in that case because it has to search for both the DNS-style and flat name. It is potentially ambiguous to specify neither flag. When this flag is specified, DsGetDcName is NOT search for the DNS-style name of the domain
DS_IS_DNS_NAME	Specifies that the DomainName parameter is a DNS name. This flag may not be specified with the DS_IS_FLAT_NAME flag.

DomainControllerInfo

Pointer to a variable that receives a pointer to a DOMAIN_CONTROLLER_INFO structure describing the domain controller selected. The returned structure must be deallocated using NetApiBufferFree.

Remarks

The DsGetDcName function is sent to the Netlogon service on the remote computer specified by ComputerName.

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. Rather, the caller should attempt to use the returned domain controller. If the domain controller is not available, the caller should repeat the DsGetDcName function, specifying the DS_FORCE_REDISCOVERY flag.

Return Values

If the function returns domain controller information, the return value is NO_ERROR.

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

QuickInfo

  Windows NT: Requires version 5.0 or later.
  Windows: Unsupported.
  Windows CE: Unsupported.
  Header: Declared in dsgetdc.h.
  Import Library: Use netapi32.lib.
  Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Networking (Net) Overview, Net Functions, DsGetSiteName, DSValidateSubnetName