Chapter 1
The Netscape LDAP SDK for C
This chapter introduces the Lightweight Directory Access Protocol (LDAP) Application Programming Interface (API) and describes the Netscape LDAP SDK for C.
This chapter contains the following sections:
The LDAP API
The Lightweight Directory Access Protocol (v3), RFC 2251 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 RFC 2251. 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:
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 SDK for C. For a complete list of the functions implemented in this SDK, refer to Chapter 18 "Function Reference."
Files Provided With the LDAP SDK for C
The Netscape LDAP SDK for C is a Software Development Kit (SDK) that contains C header files, C libraries, tools, and example programs. To install the SKD, you download the compressed SDK package from the iPlanet web site on the Internet, 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 SDK for C 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 SDK for C directories
|
Directory
|
Description
|
|
include
|
This directory contains the header files for the LDAP SDK for C. In your client source files, you must include the files contained in this directory as described in the section "Include Files Supplied with the LDAP SDK for C."
|
|
lib
|
This directory contains the C library files provided with the LDAP SDK for C. For details on these files, see the section "Libraries Supplied with the LDAP SDK for C."
|
|
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 iPlanet Directory Server and are described in the iPlanet Directory Server Command and File Reference (see http://docs.iplanet.com/docs/manuals/directory/ 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 SDK for C."
|
|
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 SDK for C Programmer's Guide) and the associated product Release Notes, which you can download from the iPlanet documentation web site detailed in the README file.
|
Include Files Supplied with the LDAP SDK for C
The Netscape LDAP SDK for C ships with the following header files:
Table 1-2 Header files shipped with the LDAP SDK for C
|
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 SDK for C
The Netscape LDAP SDK for C 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 Netscape LDAP SDK for C, v4.1:
Table 1-3 Library files shipped with the LDAP SDK for C
|
Library File
|
Description
|
|
libldapssl41.so
|
The SSL-enabled library for Solaris, AIX, and Linux.
|
|
libnspr3.so
|
Library containing the core Netscape Portable Runtime (NSPR) functions.
|
|
libldapssl41.sl
|
The SSL-enabled library for HP-UX.
|
|
libnspr3.sl
|
Library containing the core NSPR functions for HP-UX.
|
|
nsldapssl32v41.dll
|
The SSL-enabled DLL library for 32-bit Microsoft Windows.
|
|
nsldapssl32v41.lib
|
The SSL-enabled import library for 32-bit Microsoft Windows.
|
|
libnspr3.dll
|
Library containing the core NSPR functions, utilizes Microsoft fibers (specific to Windows NT and Windows 2000).
|
|
nspr3.dll
|
Library containing the core NSPR functions.
|
|
nsldap32v41bc.lib
|
The standard import library for 32-bit Microsoft Windows, to be used with Inprise (Borland) compilers. This library is not is not officially supported at this time.
|
Tools Supplied With the LDAP SDK for C
The LDAP SDK for C includes the following utilities that help you to work with LDAP data sets:
Table 1-4 Utilities supplied with the LDAP SDK for C
|
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 iPlanet Directory Server.
Compiling LDAP Clients
The Netscape LDAP SDK for C 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 Netscape LDAP SDK for C 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 libldapssl41.so. On HP-UX, the library is named libldapssl41.sl. For example, on Solaris, you would use the following link option:
-L../lib -lldapssl41
Refer to the Makefile in the examples directory for details on compiling your applications.
|
Note
|
The NSPR libraries are now distributed with the LDAP SDK for C. 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 libldap41.so for 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_PATH environment 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 32-bit Windows Systems
When compiling clients on 32-bit Windows systems (Windows NT, Windows 95, Windows 98, 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 nsldapssl32v41.lib for Microsoft compilers.
Make sure to copy the nsldap32v41.dll dynamic link library to a directory where your client can find it.
|
Note
|
Some iPlanet servers (such as the iPlanet Directory Server) might install a different version of the nsldap32v41.dll in the Windows system32 directory. Make sure that your client finds the version of the DLL that is included with the Netscape LDAP SDK for C 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 32-bit Windows system directory, typically winnt\system32.
-
Note that a version of the LDAP API DLL may already exist in this directory. For example, other iPlanet servers 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 Netscape LDAP SDK for C ships with several examples that demonstrate the use of the functions contained in the LDAP SDK for C 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, version 4.12) and that you have the sample database (airius.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 airius.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 SDK for C 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, o=airius.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 3.0 and later, and the iPlanet Directory Server.
|