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
- The
ldap.h
file is now a small file that, for clarity, #includes several other files. - A new extended I/O function callback scheme was added to the
SDK. The
ldap_x_ext_io_fns
struct has been added to hold extended I/O function pointers. Theldap-extension.h
file outlines the new callbacks. - Netscape Portable Runtime library (NSPR) support was added.
The library,
libprldap
was added to provide a simple way for an application that is using NSPR to tielibldap
into their environment. Theldappr.h
file outlines the new interface. The new examplensprio.c
shows how to use the new interfaces. - The
ldap_search*()
line of functions was modified as follows:- The
ldap_search*()
line of functions now returnLDAP_PARAM_ERROR
if asizelimit
smaller than -1 is passed to the function call. - The
ldap_search*()
line of functions now set*result
toNULL
in all error situations.
- The
- The
ldapmodify
utility was modified as follows:- The
-A
option was added, which causes the tool to display non-ASCII values in conjunction with the-v
option. - The
-B
and-q
options were added, which provide support for the bulk import feature available in the Netscape Directory Server 6.0 and later. - Support for the
version
directive was added. - Support for
changetype
withmoddn
was added. - Improved the LDIF output to provide better support for file URLs.
- The
- The
ldapsearch
utility was modified as follows:- The
-e
option was added, which minimizes base-64 encoding of values. By default,ldapsearch
will always produce ASCII values and any non-ASCII values (such as UTF-8 characters) as base-64 encoded characters. The new-e
option causesldapsearch
to return as much real data as is possible. With-e
, only values or DNs that contain an '\r
', an '\n
', or that start with ':', ' ', or '<
' are base-64 encoded. Note that the-e
option may causeldapsearch
to produce LDIF that does not conform to RFC 2849). - The
-U
option was added, which operates in conjunction with the-t
option (which causesldapsearch
to produce file URLs). - To conform with
RFC 2849,
ldapsearch
now outputs a "version: 1
" line at the start of all LDIF. A new-1
(minus 1) option has been added toldapsearch
to suppress this line. - The
ldapsearch
utility has been modified to support a zero length filter, represented as either "" orNULL
. The zero-length filter "" is now an alias for "(objectclass=*)
".
- The
- The following new examples have been added to the SDK:
- csearch -- search with ldap_memcache
- ssnoauth -- search over SSL
- ssearch -- search over SSL with cert based authentication
- nsprio -- example usage of the extended IO callbacks
- psearch -- uses persistent search
- srvsort -- shows server-side sorting
- ppolicy -- shows use of password policies
- crtfilt -- demonstrates the use of
ldap_create_filter()
- The
ldap.h
header file was modified as follows:- Support was added for discovery of API version information at
run-time with the
LDAP_OPT_API_INFO
option andLDAPAPIInfo
structure. - Support was added for the discovery of API extensions at
run-time with the
LDAP_OPT_API_FEATURE_INFO
andLDAPAPIFeatureInfo
structures. - The following macros were added to support the discovery of
API version information at compile-time:
LDAP_VENDOR_VERSION
,LDAP_VENDOR_NAME
, andLDAP_API_VERSION
. - A set pf
LDAP_API_FEATURE_*
macros were added to support the discovery of API extensions at compile-time. - The
LDAP_OPT_PRIVATE_EXTENSION_BASE
macro was added. - The
ldap_unbind_ext()
function was added. - The
ldap_mods_u
name was added to themod_vals
union. - A number of function parameters were modified to be declared
with
const
.
- Support was added for discovery of API version information at
run-time with the
- The
ldap_get_option()
function was modified as follows:- Support for the
LDAP_OPT_HOST_NAME
option was added. - The function now returns a duplicate copy of data when
LDAP_OPT_SERVER_CONTROLS
,LDAP_OPT_CLIENT_CONTROLS
, orLDAP_OPT_ERROR_STRING
are retrieved. - The
LDAP_OPT_MATCHED_DN
option was added. - Support for
LDAP_OPT_ERROR_NUMBER
andLDAP_OPT_ERROR_STRING
were added.
- Support for the
- The
lber.h
header file was modified as follows:- Support was added for the
LBER_USE_DER
option. - Several internal datatypes were changed to provide support
for
liblber
. In the header file, see the definition for_LP64
for details. - The typedef
BerValue
was added to theberval
struct, as follows:typedef struct berval { unsigned long bv_len; char *bv_val; } BerValue;
- Support was added for the
- Support was added for receiving unsolicited LDAPv3 notification messages.
- The header files
disptmpl.h
andsrchpref.h
are now shipped with the SDK. - When using SSL client authentication with the command-line
utilities, you are no longer required to provide the Cert DB
password with the
-W
option on the command line. If you do not specify the-W
option, the command-line utility will prompt you for your Cert DB password. Alternatively, you can provide a path to a PIN file that contains your Cert DB password. The format of a PIN file is the same as the PIN file that you would use for Netscape Directory Server. That is, if your Cert DB password issecret12
, then you would enter the following line into your PIN file:Internal (Software) Token:secret12
You would then point to this file using the-I
option on the command line utility. For example:-I /home/bjensen/.mozilla/bjensen/8vlmm76q.slt/my_pin_file
The use of either the PIN file or interactive prompting for your password means that your Cert DB password is not exposed through process examination (that is, by using theps
command on Unix).
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:
LDAP_X_IO_TIMEOUT_NO_WAIT
-- The connection attempt returns immediately even if the server is reachable.LDAP_X_IO_TIMEOUT_NO_TIMEOUT
-- The connection attempt will block until the host responds, or for the duration of the platform's connection timeout. Depending on the platform, the default connection timeout can be anywhere from 20 seconds to 3 minutes or longer. This value is the default.
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.