Chapter 29. Functions for Thread-Safe LDAP Connections

This chapter contains reference information on functions for thread-safe LDAP connections.

Table 29.1. Thread-Safe LDAP Connection Routines

Function Description
slapi_ldap_init() Initializes an LDAP session with another LDAP server.
slapi_ldap_unbind() Unbinds from another LDAP server and frees the resources contained in the LDAP structure.

29.1. slapi_ldap_init()

Initializes an LDAP session with another LDAP server.
Description

This function initializes an LDAP session with another LDAP server. If you want to connect to another LDAP server over TLS or if you want to allow multiple threads to use the same connection, call this function instead of the ldap_init() function provided with the Red Hat Directory SDK.

This function allocates an LDAP structure containing information about the session, including the hostname and port of the LDAP server, preferences for the session (such as the maximum number of entries to return in a search), and the error code of the last LDAP operation performed.
You can specify a list of LDAP servers that you want to attempt to connect to. Your client will attempt to connect to the first LDAP server in the list. If the attempt fails, your client will attempt to connect to the next LDAP server in the list.
If you specify a non-zero value for the secure argument, this function initializes the plug-in for TLS and installs the I/O routines for TLS.
If you specify a non-zero value for the shared argument, this function installs the server's threading functions and allows multiple threads to share this session (the returned LDAP structure). The Directory Server processes each request in a separate thread. When handling multiple requests, it is possible for the server to call your plug-in function concurrently for different threads.
If you initialize a session by calling this function, make sure to call the slapi_ldap_unbind() function (not the ldap_unbind() or ldap_unbind_s() functions provided with the Directory Server SDK) when you are done with the session.
As the slapi_ldap_init() function returns a regular LDAP *, you can use the LDAP C SDK connect timeout feature for plug-ins. That is, when connecting to an external LDAP server from a plug-in, you can specify a time limit for establishing the connection. To specify the timeout, call ldap_set_option() with the LDAP_X_OPT_CONNECT_TIMEOUT option after calling slapi_ldap_init(), as illustrated in the sample code below: 
					void my_ldap_function( void ) {
					
					LDAP *ld; 
					int to = 5000; /* 5000 milliseconds == 5 second timeout */
					if (( ld = slapi_ldap_init( host, port, 0, 1 )) == NULL ) { 
					/* error trying to create an LDAP session */ 
					return -1;
					}
					if ( ldap_set_option( ld, LDAP_X_OPT_CONNECT_TIMEOUT, &to ) != 0 ) {
					/* error setting timeout */
					slapi_ldap_unbind( ld );
					return -1;
					}
					/* use the handle, e.g., call ldap_search_ext() */
					slapi_ldap_unbind( ld );
					return 0;
					}
Syntax

#include "slapi-plugin.h"
LDAP *slapi_ldap_init( char *ldaphost, int ldapport, int secure, int shared );

Parameters

This function takes the following parameters:

ldaphost
Space-delimited list of one or more host names (or IP address in dotted notation, such as 141.211.83.36) of the LDAP servers to which you want to connect. The names can be in hostname:portnumber format, in which case portnumber overrides the port number specified by the ldapport argument.
ldapport
Port number of the LDAP server.
secure
Determines whether to establish the connection over TLS. Set this to a non-zero value to establish the connection over TLS.
shared
Determines whether the LDAP session (the LDAP structure) can be shared by different threads. Set this to a non-zero value to allow multiple threads to share the session.
Returns

This function returns one of the following values:

  • If successful, returns a pointer to an LDAP structure, which should be passed to subsequent calls to other LDAP API functions.
  • If unsuccessful, returns NULL.