Mozilla LDAP C SDK Recent Changes

Last updated August 21, 2003
(but this file is not completely up-to-date)

Contents

Added features and enhancements

Miscellaneous Changes

LDAP_X_OPT_CONNECT_TIMEOUT

There is a new option that allows you to control the TCP/IP timeout. Normally connection attempts will block for a period of time when the connection is for a host that is not reachable. LDAP_X_OPT_CONNECT_TIMEOUT allows you to control the amount of time for which a connection attempt will block in the event that the host is not reachable. You can tell the SDK to return immediately, return after an amount of time that you specify, or to block indefinitely.

The timeout value is set on a per-session handle basis and you can control the default timeout that is used by all session handles. Use ldap_set_option() to set the timeout value. Use ldap_get_option() to return the timeout value that is set for the current session handle.

Timeout Values

To support this option, the following special values are now available:

In addition, you can specify a timeout value in milliseconds.

Setting the Timeout Value

The following code fragment sets the timeout value for the session handle to 10 seconds.

#include <stdio.h>
#include "ldap.h"

#define HOST "ldap.example.com"
#define PORT 389

...

LDAP *ld;
LDAPMessage *result;
int rc, version;

/* timeout is specified in milliseconds. 10000 = 10 seconds. */
int timeout = 10000;

...

if ( ( ld = ldap_init( HOST, PORT ) ) == NULL ) {
	perror( "ldap_init" );
	return( -1 );
}

if ( ldap_set_option( ld, LDAP_X_OPT_CONNECT_TIMEOUT, &timeout ) != LDAP_SUCCESS ) {
	rc = ldap_get_lderrno( ld, NULL, NULL);
	fprintf( stderr, "ldap_set_option: %s\n", ldap_err2string( rc ) );
	ldap_unbind( ld );
	return (rc);
}

...

You can also control the default timeout for all LDAP session handles by setting the LDAP * value to NULL using ldap_set_option(). For example:

int timeout = LDAP_X_IO_TIMEOUT_WAIT;

ldap_set_option( NULL, LDAP_X_OPT_CONNECT_TIMEOUT, &timeout );

/* the default timeout is now set for all new ldap connections that 
    are created after this call to ldap_set_option. */

Retrieving the Timeout Value

The following code fragment retrieves the timeout value for the current session handle.

#include <stdio.h>
#include "ldap.h"

#define HOST "ldap.example.com"
#define PORT 389

...

LDAP *ld;
LDAPMessage *result;
int rc, version, timeout;

...

if ( ( ld = ldap_init( HOST, PORT ) ) == NULL ) {
  perror( "ldap_init" );
  return( -1 );
}

if ( ldap_get_option( ld, LDAP_X_OPT_CONNECT_TIMEOUT, &timeout ) != LDAP_SUCCESS ) {
  rc = ldap_get_lderrno( ld, NULL, NULL);
  fprintf( stderr, "ldap_set_option: %s\n", ldap_err2string( rc ) );
  ldap_unbind( ld );
  return (rc);
}

switch( timeout ) {
  case LDAP_X_IO_TIMEOUT_NO_WAIT:
    printf("The connection is set to not block\n");
    break;

  case LDAP_X_IO_TIMEOUT_NO_TIMEOUT:
    printf("The connection is set to block indefinitely\n");
    break;

  default:
    printf("The connection timeout is set to %d seconds", (timeout/1000) );
    break;
}

...

LDAP library/API Version Mismatch Error Messages

Various macros and structures have been added to the SDK to allow for compile-time and run-time discovery of the API version. Their intended use is to allow you to ensure that you are compiling and running with the correct version of the LDAP SDK for C. These features are in line with the latest LDAP SDK for C API Internet Draft.

As a result of these changes, the command line tools bundled with the LDAP SDK for C now check to ensure that they are running with the correct version of the library. If your library path variable (LD_LIBRARY_PATH on most Unix systems and the PATH variable on Windows NT) is set so that an old version of the LDAP SDK for C library is in use, then the command line tools can return one of the following error messages:

ldapsearch: unable to retrieve LDAP library version information; 
            this program requires an LDAP library that implements 
            revision 2003 or greater of the LDAP API. 

ldapsearch: this program requires an LDAP library that implements revision 
            2003 or greater of the LDAP API; running with revision 2002. 

ldapsearch: this program requires Mozilla's LDAP 
            library version 5.05 or greater; running with version 5.00.

By default, the tools will exit if they see a mismatch in versions. To override the version mismatch, you can use -0 option (zero, not 'o') with the tools, but results may vary.

64-Bit Safe Changes

Internal data types for liblber have been upgraded so that the data types are 64-bit safe. This is done in the following section of code in lber.h:

/*
 * Implementation-specific integer data types.  If living in an LP64
 * environment (where sizeof(long) is 64 bits), we use unsigned ints;
 * otherwise we use unsigned longs.  The goal is to always use 32-bit
 * quantities and to also be backwards compatible with previous SDK
 * versions which used unsigned longs.
 */

#if defined(_LP64)
       typedef unsigned int ber_len_t;
       typedef          int ber_signed_len_t;
       typedef unsigned int ber_tag_t;
       typedef          int ber_int_t;
#else
       typedef unsigned long ber_len_t;
       typedef          long ber_signed_len_t;
       typedef unsigned long ber_tag_t;
       typedef          long ber_int_t;
#endif

This change makes liblber consistent between environments where int data types are 32 bits and those where they are 64 bits. However, this change may cause some compilers, especially c++ compilers where strong type checking is enforced, to emit warnings or errors when you recompile old code.

ldap_url_parse() with Space-Separated Lists of Hosts

You can now pass ldap_url_parse() a string that uses the following format:

ldap://host1:port1 host2:port2 host2:port3 ... hostn:portn/<basedn>

Using this formatting, ldap_url_parse() will return results that are acceptable to ldap_init(). For example:

LDAP *ld;
LDAPURLDesc *ludpp;
int res;

char *url = "ldap://phonebook.example.com:2389 directory.example.com:389/dc=example,dc=com";

res = ldap_url_parse(url, &ludpp);
ld = ldap_init(ludpp->host, ludpp->port);

This input causes ldap_init() to try to connect to each host and port in the URL string until it finds a host with which it can connect.

Note that ludpp->port is set to the port identified on the last host in the URL string. If ludpp->port is used as shown here, then the last port identified on the URL string becomes the default port for any hosts for which a port is not explicitly set. Using the example above, suppose the URL string contained the following:

ldap://phonebook.example.com phonebook2.example.com phonebook3.example.com:2389/dc=example,dc=com

Here, ldap_init() would use port 2389 for all the hosts that it tries. If the last host in the string does not identify a port, then ludpp->port is set to zero (0). Setting the port to 0 tells ldap_init() to use the default port, which is 389 for ldap:// urls and 636 for ldaps:// urls.

Known problems

Please use Bugzilla to find out about known problems and recent fixes. List All Open LDAP C SDK bugs.