You are currently viewing a snapshot of www.mozilla.org taken on April 21, 2008. Most of this content is highly out of date (some pages haven't been updated since the project began in 1998) and exists for historical purposes only. If there are any pages on this archive site that you think should be added back to www.mozilla.org, please file a bug.

Mozilla LDAP C SDK Programmer's Guide

Chapter 1 - The Mozilla LDAP C SDK

This chapter introduces the Lightweight Directory Access Protocol (LDAP) Application Programming Interface (API) and describes the Mozilla LDAP C SDK.

This chapter contains the following sections:

The LDAP API

The The C LDAP Application Program Interface Internet Draft defines a set of API functions that you can use to build LDAP-enabled clients. The functionality implemented in this SDK closely follows the interfaces outlined in the Internet Draft, which should become an RFC someday. Using the functionality provided with this SDK, you can enable your clients to connect to LDAPv3-compliant servers and perform standard LDAP functions. Among other things, with this SDK you can:

Search for and retrieving a list of entries.
Ad new entries (modify) the database.
Update existing entries.
Delete entries.
Rename entries.

For example, if you are writing an email application, you can use the functions in the LDAP API to retrieve email addresses from an LDAP server.

The API functions allow you to perform LDAP operations synchronously or asynchronously.

You can call a synchronous function if you want to wait for the operation to complete before receiving the return value of a function.
If you want to perform other work while waiting for an operation to complete, you can call an asynchronous function and poll the LDAP client library to check the status of the operation.

The LDAP API also includes functionality defined in LDAPv3. For example, you can call functions to request extended operations from an LDAPv3 server.

Subsequent chapters in this manual explain how to use the LDAP API functions contained in the LDAP C SDK. For a complete list of the functions implemented in this SDK, refer to Chapter 18 - Function Reference.

Files Provided With the LDAP C SDK

The Mozilla LDAP C SDK is a Software Development Kit (SDK) that contains C header files, C libraries, tools, and example programs. To install a binary release of the SDK, you download the compressed SDK package and unpack the files to the directory of your choice. When you unpack the SDK, it will create several directories and populate them with the various files provided with the SDK. The directories and files supplied with the SDK are detailed in the sections below.

Directories Installed With the SDK

The LDAP C SDK installation process creates several directories. These directories are populated with the files provided by the SDK. The table below outlines the directories that are created by the installation process:

Table 1-1 - LDAP C SDK directories

Directory	Description
`include`	your client source files, you must include the files contained in this directory as described in the section "Header Files Supplied with the LDAP C SDK."
`lib`	This directory contains the C library files provided with the LDAP C SDK. For details on these files, see the section "Libraries Supplied with the LDAP C SDK."
`examples`	This directory contains sample source code and makefiles for LDAP clients. See the `README` file in this directory for information about building these client programs.
`tools`	This directory contains the LDAP command-line tools. These are similar to the tools provided with the Netscape Directory Server and are described in the Netscape Directory Server Command and File Reference (see `http://enterprise.netscape.com/docs/directory/index.html` for details). Note that in order to use these applications, you need to make sure that the application can find the LDAP API shared library or dynamic link library, as described in the section "Libraries Supplied with the LDAP C SDK."
`docs`	Initially this directory contains only the README file that is shipped with this version of the SDK. However, the directory is intended as a location for this guide (the LDAP C SDK Programmer's Guide) and the associated product Release Notes, which you can download from the web site as detailed in the README file.

Header Files Supplied with the LDAP C SDK

The Mozilla LDAP C SDK ships with the following header files:

Table 1-2 - Header files shipped with the LDAP C SDK

Header File	Description
`lber.h`	Prototypes the standard Basic Encoding Rules (BER) functions, structures and defines for the LDAP SDK.
`ldap.h`	Prototypes for the standard functions, structures, and defines contained in the LDAP SDK.
`ldap_ssl.h`	Prototypes for the SSL functions, structures, and defines contained in the LDAP SDK.
`ldappr.h`	Prototypes the functions, structures, and defines contained in the Netscape Portable Runtime (NSPR) for the LDAP SDK.

Libraries Supplied with the LDAP C SDK

The Mozilla LDAP C SDK comes with several different library sets. The specific library files that you link with depend on the type of application(s) you are building. Table 1-3 outlines the library files provided with the Mozilla LDAP C SDK:

Table 1-3 - Library files shipped with the LDAP C SDK

Library File	Description
`libldap50.so`	The SSL-enabled library for Solaris, AIX, and Linux.
`libnspr4.so`	Library containing the core Netscape Portable Runtime (NSPR) functions.
`libldap50.sl`	The SSL-enabled library for HP-UX.
`libnspr4.sl`	Library containing the core NSPR functions for HP-UX.
`nsldap32v50.dll`	The SSL-enabled DLL library for 32-bit Microsoft Windows.
`nsldap32v50.lib`	The SSL-enabled import library for 32-bit Microsoft Windows.
`libnspr4.dll`	Library containing the core NSPR functions, utilizes Microsoft fibers (specific to Windows NT and Windows 2000).
`nspr4.dll`	Library containing the core NSPR functions.
`nsldap32v50bc.lib`	The standard import library for 32-bit Microsoft Windows, to be used with Borland compilers. This library is not is not officially supported at this time.

Tools Supplied With the LDAP C SDK

The LDAP C SDK includes the following utilities that help you to work with LDAP data sets:

Table 1-4 - Utilities supplied with the LDAP C SDK

Utility	Description
`ldapmodify`	Lets you modify, add, delete, or rename directory entries.
`ldapsearch`	Lets you search for directory entries and display attributes and values found.
`ldapdelete`	Lets you delete existing directory entries.
`ldapcmp`	Lets you compare entries between directory servers.

A list of options for each utility can be obtained by typing the utility name at the command line. For detailed documentation on these utilities, refer to the Command and File Reference shipped with the Netscape Directory Server.

Compiling LDAP Clients

The Mozilla LDAP C SDK includes the header files and libraries for the LDAP API functions. You can include these header files and link to these libraries to enable your application to use LDAP.

Including the LDAP Header File

To make use of the functions contained in the LDAP SDK, whether you are developing on UNIX or in a 32-bit Windows system, you must include the ldap.h header file in your C source files. The following line of code shows as shown in the following line of code:

#include "ldap.h"

The ldap.h header file declares the functions and structures contained in the LDAP API.

You do not need to explicitly include the lber.h header file; lber.h is already included in ldap.h.

If you are calling the LDAP SSL functions, you also need to include the ldap_ssl.h header file, as follows:

#include "ldap_ssl.h"

To make use of the Netscape Portable Runtime (NSPR) with your LDAP applications, you must include ldappr.h (this header file contains the prototypes for functions that tie the LDAP libraries to NSPR). You can find more information on NSPR in the ldappr.h header file and at the following URL:

http://www.mozilla.org/projects/nspr

Compiling Clients on UNIX

The Mozilla LDAP C SDK has an include directory that contains C header files and a lib directory that contains the shared libraries and objects to which you must link.

When compiling clients on UNIX platforms, you need to link to the appropriate LDAP API shared library. On Solaris, AIX, Linux, and OSF, the shared library is libldap50.so. On HP-UX, the library is named libldap50.sl. For example, on Solaris, you would use the following link option:

-L../lib -lldap50

Refer to the Makefile in the examples directory for details on compiling your applications.

The NSPR libraries are now distributed with the LDAP C SDK. When linking with the SSL-enabled applications, you must also link with the NSPR libraries. For more information on the NSPR libraries, refer to the documentation at the following URL (follow the "Documentation and Training" link):
http://www.mozilla.org/projects/nspr/

If you linked the shared library, you need to make sure that the LDAP client can find the library. Do one of the following:

Make sure that the LDAP API shared library file (such as libldap50.sofor Solaris) is in a standard location, as in /usr/lib. Alternatively, you can use environment variables to specify the library location.
On some platforms, if you have compiled your client with certain flags set, you can set an environment variable to specify the run-time path to check when loading libraries. If you do this, you can set this variable to the location of the LDAP library.
For example, on Solaris and Linux, you can use the LD_LIBRARY_PATHenvironment variable. On HP-UX, you can use the SHLIB_PATH environment variable if you use the -Wl,+s+b flag when compiling and linking. On AIX, you can use the LIBPATH environment variable.
Use a link flag that specifies the path where the executable can find the library. For example, on Solaris, you can use the -R flag to specify the path where the executable can find the library.

See the makefile in the examples directory for examples of additional flags and defines that you might need to specify when compiling and linking your LDAP client. Different platforms might require different sets of define statements.

Compiling Clients on Windows Systems

When compiling clients on Windows systems (Windows NT, Windows 2000, Windows 9x, Windows XP, and Windows ME), make sure to define _CONSOLE if you are writing a console application, or _WINDOWS if you are writing a standard Windows GUI application.

Make sure to link to the LDAP API import library. The name of the library is nsldap32v50.lib for Microsoft compilers.

Make sure to copy the nsldap32v50.dll dynamic link library to a directory where your client can find it.

Some products servers (such as the Netscape Directory Server) might install a different version of the nsldap32v50.dll in the Windows system32 directory. Make sure that your client finds the version of the DLL that is included with the Mozilla LDAP C SDK before finding the version in the system32 directory. For example, you can copy the SDK DLL to the same directory as your client application.

During run-time, your client searches for the LDAP API dynamic link library in the following locations:

The directory from which the application loaded.
The current directory.
The Windows system directory, typically winnt\system32.
Note that a version of the LDAP API DLL may already exist in this directory. For example, other software packages might install a different version of this DLL. To avoid potential conflicts, you should not install the DLL in this directory.
The Windows directory.
The directories listed in the PATH environment variable.

Running LDAP Application Programs

When you run LDAP clients on UNIX or Windows system, you must ensure that the operating system can find the libraries that support the LDAP functions that are called by your application. On UNIX, these files are called shared objects; on Windows, they are call Dynamic Link Libraries. Generally, these files are referred to as runtime libraries.

The UNIX Runtime Library Files

On Unix systems (such as Solaris, AIX, and HP-UX), the library files consist of a shared object library. When running clients built with these libraries, make sure to set the appropriate environment variable that specifies the run-time path used to find libraries.

For example, on Solaris and Linux, set the LD_LIBRARY_PATH environment variable to the location of the shared library. On HP-UX, set the SHLIB_PATH environment variable if you are using the -Wl,+s+b flag to compile your client application. On AIX, set the LIBPATH environment variable.

The Windows Runtime Library Files

For Windows applications, the library files include an import library and a dynamic link library. When running clients built with these libraries, make sure to copy the dynamic link library to the directory containing your client or copy it to a location where the DLL can be found by the operating system.

The Example Programs

The Mozilla LDAP C SDK ships with several examples that demonstrate the use of the functions contained in the LDAP C SDK library. This code was tested on a Solaris 2.6 machine and on a Windows NT 4.0 machine with Microsoft Visual C++ 6.0 SP3.

Located in the examples directory of the installed the SDK, the example code assumes that you are running clients against a directory server that is compliant with LDAPv3 (such as the Netscape Directory Server) and that you have the sample database (example.com) loaded on the server. (If you want to run the examples, you will need to have a working LDAP server running and the sample data contained in example.com must be properly loaded.)

To compile and run these examples, refer to the README file contained in the examples directory. The Windows NT versions of the LDAP C SDK include sample project files. Sample Visual C++ makefiles for a 32-bit Windows application (winldap) are included in the windows example directory. The Win32 version of the makefile is named winldap.mak.

Synchronous Examples

These samples use the synchronous LDAP calls. These function calls are more straightforward to use than their asynchronous counterparts. Because of this, it is suggested you look at these examples first.

The synchronous calls block the calling process until all results have been returned, so they are probably not appropriate for use with clients that implement a graphical user interface (GUI) in a single-threaded environment because these programs usually rely on event loops. However, these sample programs fine for command-line clients and CGI programs.

Table 1-5 - Synchronous example programs

Example Program	Description
`search.c`	Shows how to use `ldap_search_s()` to search for all entries which have an attribute value which exactly matches what you're searching for. In this example, all entries with the surname (last name) "`Jensen`" are retrieved and displayed.
`csearch.c`	Like `search.c`, but enables an in-memory cache.
`ssnoauth.c`	Like `search.c`, but the search is done over an SSL protected TCP connection.
`ssearch.c`	Like `ssnoauth.c`, but with certificate based authentication thrown in.
`srvrsort.c`	Shows how to use server side sorting in conjunction with the `ldap_search_ext_s()` function.
`rdentry.c`	Shows how to use `ldap_search_s()` to retrieve a particular entry from the directory. In this example, the entry "`uid=bjensen, ou=People, dc=example,dc=com`" is retrieved and displayed.
`getattrs.c`	Just like `read.c`, but retrieves specific attributes from an entry.
`compare.c`	Shows how to use `ldap_compare_s()`, which allows you to test if a particular value is contained in an attribute of an entry.
`modattrs.c`	Shows how to use `ldap_modify_s()` to replace and add to values in an attribute.
`modrdn.c`	Shows how to use `ldap_modrdn2_s()` to change the relative distinguished name (rdn) of an entry.
`getfilt.c`	Shows how to use the `ldap_getfilter*()` family of routines, which help generate LDAP filters based on an arbitrary search string provided by a user.
`crtfilt.c`	Shows how to use the `ldap_create_filter()` function to generate LDAP filters.

Asynchronous Examples

These examples use the asynchronous LDAP calls. The general idea is that you begin an operation, and then periodically poll to see if any results have been returned.

Table 1-6 - Asynchronous example programs

Example	Description
`asearch.c`	Initiates a search for entries and polls for results, printing them as they arrive.
`nsprio.c`	Like `asearch.c` but uses the PerLDAP routines to incorporate Netscape Portable Runtime (NSPR).
`add.c`	Adds an entry to the directory.
`del.c`	Deletes an entry from the directory.
`psearch.c`	Shows how to use the Persistent Search (an LDAPv3 protocol extension) to monitor a directory server for changes.
`ppolicy.c`	Attempts to bind to the directory and reports back any password expiration information received. This demonstrates how clients can process password policy information that is optionally returned by Netscape Directory Server.