ldap_init (Compact 2013)

3/26/2014

This function initializes a session with an LDAP server.

Syntax

LDAP* ldap_init(
  UNICODE PTCHAR HostName,
  ULONG PortNumber
);

Parameters

• HostName
  [in] Domain name or space-separated list of host names or dotted strings representing the IP address of hosts running an LDAP server to which to connect. Each host name in the list can include an optional port number, which is separated from the host itself with a colon (:) character.

• PortNumber
  [in] Contains the TCP port number to which to connect. Set to LDAP_PORT to obtain the default port, 389. This parameter is ignored if a host name includes a port number.

Return Value

If this function succeeds, it returns a session handle in the form of a pointer to an LDAP data structure.

If this function fails, it returns NULL. Use the LdapGetLastError function to retrieve the error code.

Remarks

Call this function to create a connection block to an LDAP server. Unlike ldap_open, a call to this function does not open the connection. You can call ldap_connect explicitly to have the library contact the server. This is useful when you want to specify a local time-out in which case you would call ldap_set_option (with the connection block from ldap_init) before calling ldap_connect. Typically, however, this call is unnecessary because the first operation function that requires an open connection calls ldap_connect internally if it has not already been called.

The function allocates an LDAP data structure to maintain state information for the session and returns a handle to this structure. You pass this handle to LDAP function calls during the session.

The HostName parameter can be NULL, in which case the run time attempts to find the "default" LDAP server. When ldap_connect is called, the hosts are tried in the order listed, stopping with the first successful connection.

If NULL is passed for the HostName parameter and the calling machine is a member of an Active Directory domain, then the run time will search for a domain component in the domain in which the current machine is a member when attempting to connect.

If NULL is passed for the HostName parameter and the calling machine is a domain component of an Active Directory domain, then the run time will switch NULL with 127.0.0.1 and connect to the local machine using loopback when attempting to connect.

If an Active Directory domain name is passed for the HostName parameter, then ldap_init will find the "default" LDAP server in that domain.

If an Active Directory server name is passed for the HostName parameter, then ldap_set_option should be called to set the LDAP_OPT_AREC_EXCLUSIVE flag on before calling any LDAP function that creates the actual connection.

In a multithreading environment, calls to ldap_init are thread-safe.

Requirements

See Also

Reference

LDAP Session Functions
ldap_connect
ldap_open
ldap_set_option
ldap_unbind