[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
);
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.
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. |
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.
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.
Value | Meaning |
---|---|
ERROR_NO_SUCH_DOMAIN | No DC is available for the specified domain or the domain does not exist. |
ERROR_INVALID_DOMAINNAME | The format of the specified DomainName is invalid. |
ERROR_INVALID_COMPUTERNAME | The format of the specified ComputerName is invalid. |
ERROR_INVALID_FLAGS | The Flags parameter has conflicting or superfluous bits set. |
ERROR_NOT_ENOUGH_MEMORY | Insufficient memory is available. |
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.
Networking (Net) Overview, Net Functions, DsGetSiteName, DSValidateSubnetName