7.6.2.2 Connecting to a Directory Server

This task establishes a TCP connection to an Active Directory server specified by the elements of an input ConnectionInfo instance.

The parameters for this task are as follows:

Name	Type	Description	Optional
TaskInputConnectionInfo	ConnectionInfo	An initialized ConnectionInfo on which to perform an LDAP bind.	No

The task returns the following results to the caller:

Name	Type	Description
TaskReturnStatus	Boolean	This task returns TRUE if a TCP connection was successfully established, FALSE otherwise.

The task performs the following actions:

1. Let connectionSuccessful be a Boolean initialized to FALSE.

2. Let dcAddress be a Unicode string initialized to NULL.

3. Let containingADConnection be the ADConnection instance contained in ADCList for which containingADConnection.primaryConnection is set to TaskInputConnectionInfo or for which the containingADConnection.referralConnections list contains TaskInputConnectionInfo. Note that these conditions are mutually exclusive and there is exactly one ADConnection which satisfies these conditions.

4. If TaskInputConnectionInfo.targetName is NULL:

   • If ComputerRole is DSRole_RoleBackupDomainController or DsRole_RolePrimaryDomainController, then set dcAddress to "localhost" and go to step 8; otherwise go to step 7.

5. If TaskInputConnectionInfo.targetName is an IP address, then go to step 9.

6. If containingADConnection.LDAP_OPT_AREC_EXCLUSIVE is set to TRUE, then go to step 8, skipping the DC location process described in step 7.

7. Assume that TaskInputConnectionInfo.targetName represents a domain name and attempt to locate a domain controller in the specified domain:

   1. Let domainControllerInfo be an instance of the DOMAIN_CONTROLLER_INFOW structure ([MS-NRPC] section 2.2.1.2.1, DOMAIN_CONTROLLER_INFOW).

   2. Let addedFlags be an unsigned integer. If TaskInputConnectionInfo.portNumber is 3268 or 3269, addedFlags is set to the bitwise OR of the D, M, and R flags defined for the Flags parameter in [MS-NRPC] section 3.5.4.3.1, DsrGetDcNameEx2. Otherwise addedFlags is set to the bitwise OR of the M and R flags.

   3. The DsrGetDcName method ([MS-NRPC] section 3.5.4.3.3, DsrGetDcName) is invoked with the following parameters:

      • ComputerName is NULL.

      • DomainName is TaskInputConnectionInfo.targetName.

      • DomainGuid is NULL.

      • SiteGuid is NULL.

      • Flags is the bitwise OR of containingADConnection.LDAP_OPT_GETDSNAME_FLAGS and addedFlags.

      • DomainControllerInfo is a pointer to the domainControllerInfo structure.

   4. If the invocation of DsrGetDcName listed in step 3 returned 0 (Success), then:

      • TaskInputConnectionInfo.targetName specified a domain name and domainControllerInfo.DomainControllerAddress now identifies a domain controller in the specified domain; if domainControllerInfo.DomainControllerAddress is an IP address, set dcAddress to domainControllerInfo.DomainControllerAddress with the "\\" prefix omitted.

   5. If the invocation of DsrGetDcName listed in step 3 returned a non-zero value and TaskInputConnectionInfo.targetName is NULL, then this task returns FALSE.

8. If dcAddress is NULL, then assume that TaskInputConnectionInfo.targetName is a host name, and set dcAddress to TaskInputConnectionInfo.targetName.

9. A TCP connection is established to the server whose host name or IP address is specified by dcAddress, with destination port set to TaskInputConnectionInfo.portNumber. If dcAddress is a host name, gethostbyname (see the note shown below) is invoked and each of the returned IP addresses is tried in parallel until a connection returns successfully or all IP addresses returned by gethostbyname have been exhausted. If a TCP connection is successfully established, the client sets TaskInputConnectionInfo.networkConnection to the TCP connection and connectionSuccessful is set to TRUE.

   Note gethostbyname is a well-known, standards-based API call that is a POSIX-compliant method to retrieve information about hosts. For one example of an implementation of this API, see [MSDN-gethostbyname].

10. If connectionSuccessful is TRUE:

    1. If containingADConnection.LDAP_OPT_TCP_KEEPALIVE is TRUE, the client enables TCP Keep-alives ([RFC1122] section 4.2.3.6, TCP Keep-Alives) on the TCP connection represented by TaskInputConnectionInfo.networkConnection.

    2. This task returns TRUE.

11. If connectionSuccessful is FALSE, this task returns FALSE.

In addition to the above, if the LDAP client is unable to establish a TCP connection to an IP address obtained from DC Location (step 7), it will retry DC Location once, this time including the "A" flag in the Flags parameter passed to DsrGetDcName (in addition to whichever flags were passed in during the first DC Location attempt). It will then try establishing a TCP connection to the IP address obtained. If this fails, the task will return FALSE.