Establishing an LDAP Session

The first step in establishing a session with an LDAP server is to create a connection block to the server. If your session doesn't require any special connection options, call ldap_open to establish a connection over TCP/IP or cldap_open to establish a connectionless UDP-based session. Either call returns a handle to an LDAP structure, which maintains state for the LDAP session.

If you want to specify an option, such as a timeout value, that will affect how you establish the connection, call ldap_init to create and initialize the connection block. To create a connection block to a secured LDAP server, call ldap_sslinit. Then, using the connection handle, call ldap_set_option with the appropriate option and value.

When ldap_set_option returns, you can call ldap_connect to verify that the server is available. However the first call to an operation function that requires an open connection will call ldap_connect internally if a connection doesn't already exist.

Effective with Microsoft® Windows® 2000, the LDAP run time automatically tries to reestablish a connection that is broken for any reason. This reconnection happens when a client tries to access a connection that no longer exists. If the server doesn't respond within 2 minutes, the run time pings the server with ICMP packets until it receives a response.

Finally, if you want to change options that apply to the session, such as the LDAP version (the default is version 2), call ldap_set_option. Call ldap_get_option to review the current settings. See Session Options for a complete description of session options.

The following example code shows how to establish an LDAP connection using LDAP version 3:

//LDAP_PORT is the default port, 389
LDAP *ldapConnection = NULL;
ULONG version = LDAP_VERSION3;
ldap_set_option( ldapConnection, LDAP_OPT_VERSION, &version );