| Platform SDK: Active Directory, ADSI, and Directory Services |
The DsGetDcName function returns the name of a domain controller (DC) in a specified domain. You can supply DC selection criteria 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 this parameter is NULL and the DS_GC_SERVER_REQUIRED flag is specified, DomainName defaults to the tree name of the primary domain of ComputerName.
If this parameter is NULL 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_AVOID_SELF | Specifies that the DC returned should not be the DC named by ComputerName. If ComputerName is not a DC, this flag is ignored. One might use this flag to get the name of another DC in the domain. |
| DS_DIRECTORY_SERVICE_PREFERRED | Prefers that the returned DC support directory service functions (Windows 2000® or later). If no such DC is available, an earlier version of the DC returns. If a DC that supports a directory service 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_DIRECTORY_SERVICE_REQUIRED | Requires that the returned DC support Windows 2000 or later. |
| 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 and successfully returned a domain controller. You should attempt to access the cached domain controller. Only if that access fails should you call again with this flag. |
| 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 either of the following flags are set: DS_WRITABLE_REQUIRED or DS_PDC_REQUIRED. |
| DS_GOOD_TIMESERV_PREFERRED | Prefers that the returned DC be a DC that is a "reliable" time server. The Windows Time Service can be configured to declare one or more DCs as a "reliable" time server. See the Windows Time Service documentation for details. This flag is intended to be used only by the Windows Time Service. Its behavior is subject to change. |
| DS_IP_REQUIRED | Requires that the IP address of the discovered DC be returned in DomainControllerAddress of the DOMAIN_CONTROLLER_INFO structure. |
| 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 or DS_RETURN_FLAT_NAME flags. |
| 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 will NOT search for the DNS-style name of the domain |
| DS_KDC_REQUIRED | Requires that the returned DC be currently running the Kerberos Key Distribution Center service. |
| DS_ONLY_LDAP_NEEDED | Specifies that the server returned is an LDAP server. The server returned is not necessarily a DC. No other services are implied to be present at the server. The server returned does not necessarily have a writeable "config" container nor a writeable "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 DC. 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, and DS_KDC_REQUIRED flags are ignored. |
| DS_PDC_REQUIRED | Requires that the returned DC be the primary domain controller (PDC) for the domain. This flag may not be set if either of the following flags are set: DS_WRITABLE_REQUIRED or DS_GC_SERVER_REQUIRED. |
| DS_RETURN_DNS_NAME | Specifies that the returned DomainControllerName and returned DomainName should be DNS names. If a DNS name is not available, an error will be returned. This flag may not be specified with the DS_RETURN_FLAT_NAME or DS_IS_FLAT_NAME flags. This flag implies the DS_IP_REQUIRED flag. |
| DS_RETURN_FLAT_NAME | Specifies that the returned DomainControllerName and returned DomainName should be flat names. If a flat name is not available, an error will be returned. This flag may not be specified with the DS_RETURN_DNS_NAME or DS_IS_DNS_NAME flags. |
| DS_TIMESERV_REQUIRED | Requires that the returned DC be currently running the Windows Time Service. |
| DS_WRITABLE_REQUIRED | Requires that the returned DC host a writeable 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 writeable DCs. Only the PDC is writeable in a Windows 2000 "mixed mode" domain. All DCs are writeable in a Windows 2000 "non-mixed mode" domain. In future releases of Windows NT/Windows 2000, certain DCs may be configured as "read only"; such DCs are not writeable. This flag may not be set if either of the following flags are set: DS_PDC_REQUIRED or DS_GC_SERVER_REQUIRED. |
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 can be one of the following error codes.
Windows NT/2000: Requires Windows 2000.
Header: Declared in Dsgetdc.h.
Library: Included as a resource in Netapi32.dll.
Unicode: Implemented as Unicode and ANSI versions on Windows 2000.
Directory Service Functions, DOMAIN_CONTROLLER_INFO, DsGetSiteName, DsValidateSubnetName, GUID, NetApiBufferFree