7.7.3.2 Performing an LDAP Operation on an ADUDPHandle

This task sends an LDAP request to an Active Directory server and returns the response returned by the server.

The parameters for this task are as follows:

Name	Type	Description	Optional
TaskInputADUDPHandle	LDAP_UDP_HANDLE ([MS-DTYP] section 2.2.24)	Refers to an initialized ADUDPHandle used to send the LDAP request.	No
TaskInputRequestMessage	LDAPMessage	The request to send to the directory server.	No
TaskOutputResultMessages	LDAPMessage list	A sequence of LDAPMessage (as defined in [RFC1777] section 4 for LDAP version 2 and [RFC2251] section 4.1.1 for LDAP version 3) representing the results that the client receives in response to TaskInputRequestMessage.	No
TaskInputRequestTimeout	Unsigned integer	Time in milliseconds the client waits to receive the response from the server. Value 0 indicates that there is no time limit.	No

The task returns the following results to the caller:

Name	Type	Description
TaskReturnStatus	Unsigned integer	The LDAP resultCode ([RFC2251] section 4.1.10) returned from the directory server in response to the request, or an error indicating that the directory server could not be contacted or that a timeout has occurred.

The task performs the following actions:

1. Let adUDPHandle be the ADUDPHandle instance referred to by TaskInputADUDPHandle.

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

3. If TaskInputADUDPHandle.targetName is NULL:

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

4. If TaskInputADUDPHandle.targetName is an IP address, then go to step 6.

5. Assume TaskInputADUDPHandle.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. It is set to the bitwise OR of the M and R flags defined for the Flags parameter in [MS-NRPC] section 3.5.4.3.1, DsrGetDcNameEx2.

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

      • ComputerName is NULL.

      • DomainName is TaskInputADUDPHandle.targetName.

      • DomainGuid is NULL.

      • SiteGuid is NULL.

      • Flags is set to addedFlags.

      • DomainControllerInfo is a pointer to the domainControllerInfo structure.

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

      • TaskInputADUDPHandle.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 and go to step 6.

   5. If the invocation of DsrGetDcName listed in step 3 returned a nonzero value and TaskInputADUDPHandle.targetName is NULL, then this task returns a local implementation-specific error code indicating that the directory server was unreachable, using an error code value reserved for APIs as specified in [RFC2251] section 4.1.10, Result Message.

      Note The Microsoft implementation of LDAP client sets the resultCode of LDAPResult to LDAP_SERVER_DOWN (0x51) when the directory server is unreachable ([MS-ERREF] section 2.4, LDAP error to Win32 mapping).

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

7. Let ldapRequest be set to TaskInputRequestMessage.

8. ldapRequest.messageID is set as described in [RFC2251] section 4.1.1.1.

9. Let ipAddress be a Unicode string initialized to NULL. If dcAddress is a host name, gethostbyname (see the note shown below) is invoked and ipAddress is set to the first address returned. Otherwise, assume that dcAddress is an IP address and set ipAddress to dcAddress.

   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. Let networkUDPHandle be an abstract element representing the UDP handle used to perform UDP operations (see [RFC768] sections "User Interface" and "IP interface"). The networkUDPHandle is created using ipAddress and the TaskInputADUDPHandle.portNumber parameter.

11. The client sends ldapRequest to the directory server indicated by ipAddress using networkUDPHandle.

12. The client creates a timer for the duration specified by TaskInputRequestTimeout and begins counting down.

13. The client then waits for either the UDP response to arrive or the timer to expire.

14. If the timer expires and no response has been received from the directory server:

    • Let ldapResponse be a freshly constructed LDAPMessage containing an LDAPResult ldapResult.

    • Set ldapResponse.messageID to ldapRequest.messageID.

    • Set ldapResult.resultCode to a local implementation-specific error code indicating a timeout has occurred, using an error code value reserved for APIs as specified in [RFC2251] section 4.1.10, Result Message.

      Note The Microsoft implementation of LDAP client sets the resultCode of LDAPResult to LDAP_TIMEOUT (0x55) on timer expiration ([MS-ERREF] section 2.4, LDAP error to Win32 mapping).

    • Insert the ldapResponse into TaskOutputResultMessages.

15. Otherwise, the timer is canceled, and for each LDAPMessage lm in the response received from the directory server:

    • If lm.messageID equals TaskInputRequestMessage.messageID, append lm to the TaskOutputResultMessages.

16. Return the resultCode of the last message in TaskOutputResultMessages.