ldap_init

The ldap_init function initializes a session with an LDAP server.

LDAP* ldap_init(
  PCHAR HostName,
  ULONG PortNumber
);

Parameters

HostName

[in] A pointer to a null-terminated string that contains a domain name, or a space-separated list of host names or dotted strings that represent 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 (:). For more information about the use of the LDAP_OPT_AREC_EXCLUSIVE option when connecting to Active Directory servers, see the Remarks section.

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 Values

If the function succeeds, it returns a session handle, in the form of a pointer to an LDAP data structure. The session handle must be freed with a call to ldap_unbind when it is no longer required.

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

Remarks

Call ldap_init to create a connection block to an LDAP server. Unlike ldap_open, a call to ldap_init 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 timeout 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 been called.

The function allocates an LDAP data structure to maintain state data for the session, and returns a handle to this structure. 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 attempted in the order listed, stopping with the first successful connection. For Active Directory servers, the DsGetDcName function can be used to obtain name of the server, which can then be passed as the HostName parameter instead of using NULL.

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

If NULL is passed for the HostName parameter and the calling computer is a DC of an Active Directory domain, then the runtime will switch NULL with 127.0.0.1 and connect to the local computer 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 DNS 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. This forces an A-record lookup and bypasses any SRV record lookup when resolving the host name. In the case of a branch office with a dial-up connection, using A-Record lookup can avoid forcing the dialup to query a remote DNS server for SRV records when resolving names.

If a Global Catalog port number is passed to ldap_init as one of the arguments, then the HostName passed for that port number must be the name of the forest for the underlying call to DsGetDcName() to correctly find the GC in the enterprise.

Multithreading: A call to ldap_init is thread safe.

Note  ldap_init is the preferred method of initializing an LDAP session. The use of ldap_open is heavily deprecated by the current LDAP RFC, because it precludes the use of setting any session options.

Requirements

Client: Included in Windows XP and Windows 2000 Professional.
Server: Included in Windows Server 2003 and Windows 2000 Server.
Redistributable: Requires Active Directory Client Extension on Windows NT 4.0 SP6a and Windows 95/98/Me.
Unicode: Implemented as Unicode and ANSI versions on all platforms.
Header: Declared in Winldap.h.
Library: Use Wldap32.lib.

See Also

Functions, ldap_connect, ldap_open, ldap_set_option, ldap_unbind, Initializing a Session