Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

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 LdapGetLastErrorfunction 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_connectexplicitly 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_connectinternally 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 HostNameparameter can be NULL, in which case the run time attempts to find the "default" LDAP server. When ldap_connectis called, the hosts are tried in the order listed, stopping with the first successful connection.

If NULL is passed for the HostNameparameter 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 HostNameparameter 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 HostNameparameter, then ldap_initwill find the "default" LDAP server in that domain.

If an Active Directory server name is passed for the HostNameparameter, then ldap_set_optionshould 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_initare thread-safe.

Requirements

Header winldap.h
Library wldap32.lib
Windows Embedded CE Windows CE .NET 4.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also