| Platform SDK: Active Directory, ADSI, and Directory Services |
The directory service (DS) functions provide a mechanism for locating a domain controller (DC) in a Windows NT®/Windows® 2000 domain. The architecture interacts with clients as well as servers in all versions of Windows NT and Windows 2000. The following functions allow developers to work with the domain controller and domain membership in the directory service:
| Function | Description |
|---|---|
| DsAddressToSiteNames | Returns the site names corresponding the addresses specified. |
| DsDeregisterDnsHostRecords | Deletes domain name service (DNS) entries that were registered by a domain controller. It can be executed on a domain controller other than the domain controller whose DNS entries are being removed. Only an Administrator, Account Operator or Server Operator may call this function. |
| DsEnumerateDomainTrusts | Returns information about domain trusts for the domain which has ServerName as a member. |
| DsGetDcName | Returns the name of a domain controller (DC) in a specified domain. The DsGetDcName function provides information from the DOMAIN_CONTROLLER_INFO structure. |
| DsGetDcSiteCoverage | Returns the site names of all sites covered by a domain controller. |
| DsGetSiteName | Returns the name of the site for either the domain controller, member workstation, or the member server. |
| DsRoleFreeMemory | Frees the memory returned from other directory service functions. |
| DsRoleGetPrimaryDomainInformation | Retrieves state information of the computer. This information includes the state of the Ds installation and domain information. |
| DsValidateSubnetName | Validates a subnet name of a valid IP address. |
The DC locator (DsGetDcName) is implemented by the Netlogon service. Each DC registers its DNS name on the domain name service (DNS) server and its NetBIOS name using a transport-specific mechanism (for example, in WINS). The DC locator looks up the name, then sends a datagram to (or "pings") the DC that registered the name. For NetBIOS domain names, the datagram is a mailslot message. For DNS domain names, the datagram is an LDAP UDP search. Each such DC responds indicating that it is currently operational. The first DC to respond is returned to the caller.
The returned DC is cached so that subsequent callers need not repeat the preceding algorithm, and to encourage all callers to use that same DC. This ensures that a single client has a consistent view of the contents of the DC.
When searching for a DC by DNS domain name, the DC locator will attempt to find a DC in the "closest" site. Each DC registers additional DNS records indicating what site that the DC is in and what sites the DC includes. The DC locator first searches for this site-specific DNS record before searching for the DNS record that is not site-specific (thus preferring a DC in that site). When the DC locator sends a datagram to the DC, the DC looks up the IP address of the client in the Configuration/Sites/Subnet container of the DS to find a subnet object. The SiteObject property of the subnet object defines the name of the site that contains the client. The DC responds to the ping with the name of the site that contains the client, along with an indicator of whether this DC covers that site. If the DC does not include that site and the DC locator has not yet attempted to find a DC in that site, the DC locator tries again to find a DC in the site.
To find the name of the site containing the client, use the DsGetSiteName function. The names of the objects in the Configuration/Sites/Subnet container must be valid subnet names. The DsValidateSubnetName function indicates whether a specified subnet name is valid.
Active Directory Display Functions, DC and Replication Management Functions, Directory Backup Functions, DOMAIN_CONTROLLER_INFO