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
- Files Provided With the LDAP C SDK
- Compiling LDAP Clients
- Running LDAP Application Programs
- The Example Programs
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
||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."|
||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."|
This directory contains sample source code and makefiles for LDAP
clients. See the
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
||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
||Prototypes the standard Basic Encoding Rules (BER) functions, structures and defines for the LDAP SDK.|
||Prototypes for the standard functions, structures, and defines contained in the LDAP SDK.|
||Prototypes for the SSL functions, structures, and defines contained in the LDAP SDK.|
||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
||The SSL-enabled library for Solaris, AIX, and Linux.|
||Library containing the core Netscape Portable Runtime (NSPR) functions.|
||The SSL-enabled library for HP-UX.|
||Library containing the core NSPR functions for HP-UX.|
||The SSL-enabled DLL library for 32-bit Microsoft Windows.|
||The SSL-enabled import library for 32-bit Microsoft Windows.|
||Library containing the core NSPR functions, utilizes Microsoft fibers (specific to Windows NT and Windows 2000).|
||Library containing the core NSPR functions.|
||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
||Lets you modify, add, delete, or rename directory entries.|
||Lets you search for directory entries and display attributes and values found.|
||Lets you delete existing directory entries.|
||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
ldap.h header file in your C source files.
The following line of code shows as shown in the following line
ldap.h header file declares the functions and
structures contained in the LDAP API.
You do not need to explicitly include the
lber.h is already included in
If you are calling the LDAP SSL functions, you also need to
ldap_ssl.h header file, as follows:
To make use of the Netscape Portable Runtime (NSPR) with your
LDAP applications, you must include
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:
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:
Refer to the
Makefile in the
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):
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_PATHenvironment variable if you use the
-Wl,+s+bflag when compiling and linking. On AIX, you can use the
Use a link flag that specifies the path where the executable can
find the library. For example, on Solaris, you can use the
-Rflag 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
Make sure to link to the LDAP API import library. The name of the
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
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
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
environment variable if you are using the
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
To compile and run these examples, refer to the
README file contained in the
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
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
Shows how to use
Shows how to use server side sorting in conjunction with the
Shows how to use
Shows how to use
Shows how to use
Shows how to use
Shows how to use the
Shows how to use the
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
||Initiates a search for entries and polls for results, printing them as they arrive.|
||Adds an entry to the directory.|
||Deletes an entry from the directory.|
||Shows how to use the Persistent Search (an LDAPv3 protocol extension) to monitor a directory server for changes.|
||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.|