ldap_init

The ldap_init function initializes a session with an LDAP server.

LDAP* ldap_init(
  PCHAR HostName,
  ULONG PortNumber
);

Parameters

HostName

[in] A 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 Values

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

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

Remarks

Call ldap_init to create a connection block to an LDAP server. 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.

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.

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 since the first operation function that requires an open connection calls ldap_connect internally if it hasn't already been called.

Multithreading: A call to ldap_init is thread safe.

Requirements

  Windows NT/2000: Requires Windows NT 4.0 SP4 or later.
  Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
  Header: Declared in Winldap.h.
  Library: Use Wldap32.lib.
  Unicode: Declared as Unicode and ANSI prototypes.

See Also

Functions, ldap_connect, ldap_open, ldap_set_option