Mozilla LDAP SDK Programmer's Guide/About Mozilla LDAP C SDK
This section introduces the LDAP C SDK.
Contents
Overview of LDAP C SDK
LDAP C SDK includes the C libraries for the LDAP API as well as sample code that demonstrates how to call many functions. The APIs are defined by the header files that declare all of the functions, data types, and code values in the SDK. You use the functions in this API to write C or C++ client applications that take full advantage of server capabilities.
The APIs are built around core functions of the LDAP v2 and v3 standards. Therefore, the APIs can be used to interact with any conforming LDAP server. This API conforms to the standard that is proposed in The C LDAP Application Programming Interface.
LDAP API
RFC 4511, Lightweight Directory Access Protocol (v3), defines a set of operations to access data in an LDAP v3 compliant directory server. The functionality implemented in LDAP C SDK closely follows these operations because a C API is defined for each operation.
- Search for and retrieve a list of entries.
- Add new entries to the database.
- Update existing directory entries.
- Delete entries.
- Rename entries.
For example, if you are writing an email application, you can use the functions in the API to retrieve email addresses from an LDAP server.
Synchronous and Asynchronous Operations
The API functions allow you to perform LDAP operations synchronously or asynchronously. The only differences between these two options are in the calling convention. The LDAP exchanges are identical.
- Call a synchronous function to wait for the operation to complete before receiving the return value of a function.
- Call an asynchronous function to perform other work while waiting for an operation to complete. Your application must then poll for results.
For more information, see Synchronous Examples, and Asynchronous Examples.
Files Provided With LDAP C SDK
LDAP C SDK includes a number of sample files, headers, libraries, and tools. This section helps you to locate the files. All locations are relative to the directory where the software is installed, which depends on your operating system.
| Directory Location |
Description |
|---|---|
| etc/ |
Contains miscellaneous files for you to use. |
| examples/ |
Contains sample source code and Makefiles for LDAP clients. See the README file in this directory for more information. |
| include/ |
Contains the header files. You must include the files in this directory in your client source files. |
| include-nspr/ |
Contains Netscape Portable Runtime (NSPR) header files. NSPR provides a platform-neutral API for systemlevel and libcstyle functions. |
| include-private/ |
Contains private header files that are not documented in this guide. |
| lib/ |
Contains the C library files. The specific library used is dependent on the type of application you are building. |
| lib-private/ |
Contains private header files that are not documented in this guide. |
| tools/ |
Contains the LDAP command-line tools. To use these applications, you must ensure that the tools can find the LDAP API shared library or dynamic link library. |
LDAP C SDK Header Files
The following table describes LDAP C SDK header files that are in the include/ directory.
Note: All locations are relative to the directory where the software is installed, which depends on your operating system.
| Header File |
Description |
|---|---|
| disptmpl.h |
A header file related to the templates (ldaptemplates.conf). |
| lber.h |
Contains prototypes for the standard Basic Encoding Rules (BER) functions, structures, and defines. |
| ldap-deprecated.h |
Contains deprecated functions that should not be used. |
| ldap-extension.h |
Contains functions, structures, and defines that extend the standard LDAP C API specification. |
| ldap-platform.h |
A private header file that contains platform-specific definitions, which allow abstraction from the underlying system. |
| ldap-standard.h |
Contains the standard LDAP functions, structures, and defines. |
| ldap-to-be-deprecated.h |
Contains functions, structures, and defines that might be deprecated in future releases. |
| ldap.h |
This base header contains LDAP functions, structures, and defines to mirror the latest LDAP C API specifications. Includes: ldap-deprecated.h, ldap-extension.h, ldap-standard.h, ldap-to-be-deprecated.h |
| ldap_ssl.h |
Contains prototypes for LDAP over SSL functions, structures, and defines. |
| ldappr.h |
Contains prototypes for the functions, structures, and defines that are contained in the Netscape Portable Runtime (NSPR) API. |
| srchpref.h |
A header file related to the search preferences (ldapsearchprefs.conf). |
ldap.h Header File
To make use of the LDAP C SDK functions, include the ldap.h header file in your C source files as shown in this line of code:
#include "ldap.h"
lber.h Header File
lber.h is included in ldap-standard.h. You do not need to include the header explicitly. Basic Encoding Rules (BER) is a simple tag-value scheme to encode requests and decode results.
ldap_ssl.h Header File
If you are calling LDAP over SSL functions, you also need to include the ldap_ssl.h header file, as follows:
#include "ldap_ssl.h"
ldappr.h Header File
To make use of the Netscape Portable Runtime (NSPR) API with your LDAP applications, you must include the ldappr.h file. The NSPR is a set of platform-neutral APIs that provides system functions such as threads, thread synchronization, I/O, interval timing, and atomic operations. This header file contains prototypes for functions that tie the LDAP libraries to NSPR. You include the header file as follows:
#include "ldappr.h"
For more information about NSPR, see the ldappr.h header file and the Netscape Portable Runtime project page at http://www.mozilla.org/projects/nspr/.
Miscellaneous Files
LDAP C SDK includes the sample files described in the following table. Sample files can be retrieved when using certain APIs. Sample files are located in the etc/ directory. All locations are relative to the directory where the software is installed, which depends on your operating system.
| File Name |
Description |
|---|---|
| ldapfilter.conf |
This filter configuration file can be used in context with ldap_init_getfilter(). |
| ldapfriendly |
This file is used to map the twoletter country codes to their full names by ldap_friendly_name(). |
| ldapsearchprefs.conf |
This configuration file was used in context with a deprecated function. |
| ldaptemplates.conf |
This configuration file was used in context with a deprecated function. |
LDAP C SDK Libraries
LDAP C SDK includes several different libraries. A library is a set of ready-made functions that are linked into a program. LDAP C SDK uses shared libraries. Shared libraries are dynamically loaded into memory when needed, reducing the size of the executable.
Library Naming Conventions
Libraries on different systems have different naming conventions. The following table shows the LDAP C SDK naming conventions.
| Operating System |
Static Library Name |
Shared Library Name |
|---|---|---|
| Solaris and Red Hat systems |
liblibraryname.a |
liblibraryname.so.versionnumber |
| HP-UX systems |
liblibraryname.a |
liblibraryname.sl |
| Windows systems |
nslibraryname.lib |
nslibraryname.dll |
On UNIX systems, the shared library file name can be fully qualified by prefixing path information.
Installed Shared Libraries
The following table describes the installed libraries that are in the lib/ directory. All locations are relative to the directory where the software is installed, which depends on your operating system.
| UNIX Library |
Windows Library |
Description |
|---|---|---|
| libldap60.so |
nsldap32v60.dll |
LDAP library |
| libprldap60.so |
nsldappr32v60.dll |
LDAP library built with NSPR. This library requires the libnspr4.so library in the lib-private/ directory. |
| libssldap60.so |
nsldapssl32v60.dll |
LDAP library that is built with support for the Secure Sockets Layer protocol. This library depends on the libnss3.so and libnspr4.so libraries in the lib-private/ directory. |
LDAP C SDK Dependencies
- Netscape Portable Runtime (NSPR) provides core cross-platform functions.
- Netscape Security Services (NSS) provides encryption, cryptographic, Secure Sockets Layer (SSL), and Public Key Infrastructure (PKI) support.
- Simple Authentication and Security Layer (SASL) provides support for applications that require SASL.
LDAP Tools
LDAP C SDK includes several utilities to help you work with LDAP data sets. These utilities are installed in the tools/ directory. For details on each tool described in the following table, see the corresponding man pages. A list of options can be retrieved by typing the tool name at the command line.
| Command |
Description |
|---|---|
| ldapcmp |
Compares the contents of a single LDAP entry or subtree in two directories. |
| ldapcompare |
Compares an attribute value against the contents of a given LDAP entry. |
| ldapdelete |
Deletes existing LDAP entries. |
| ldapmodify |
Edits the contents of an LDAP directory, either by adding new entries or modifying existing ones. |
| ldappasswd |
Changes user passwords on LDAP entries. |
| ldapsearch |
Issues search requests to an LDAP directory, then displays the result as LDAP Data Interchange Format (LDIF) text. |
Compiling Applications with LDAP C SDK
When compiling applications, you must include the header files and link to the libraries required. Information about including the header files is in LDAP C SDK Header Files. Linking to shared libraries is covered in this section. LDAP C SDK is qualified to work with C compilers.
Note: LDAP C SDK is not guaranteed to work with C++ compilers.
Compiling on UNIX Platforms
When compiling clients on UNIX platforms, specify link options correctly to link the application to the appropriate shared libraries. See the Makefile in the examples/ directory for details on compiling your applications on UNIX platforms.
Compiling on Windows Systems With LDAP C SDK
- _CONSOLE if you are writing a console application
- _WINDOWS if you are writing a standard Windows GUI application
Linking Dependencies
When you run LDAP clients, you must ensure that the operating system can find the shared libraries that support the functions called by your application. Generally, these files are referred to as runtime libraries. Any of the following options ensure that the operating system can find the shared libraries.
- Make sure that the shared library file, such as libldap60.so, is in a location specified by environment variables.
- On some platforms, clients can be complied with flags that let you set the runtime path to load libraries as an environment variable.
- On Solaris‚Ñ¢ and Red Hat systems, you can use the LD_LIBRARY_PATH environment variable if you use the -Wl,+s+b flag when compiling and linking.
- On HP-UX system, use the SHLIB_PATH environment variable.
- The directory from which the application loaded
- The current directory
- The Windows system directory, typically winnt\system32\
To avoid potential conflicts, do not copy the DLL to this directory - The directories listed in the PATH environment variable
- Use a link flag that specifies the path where the executable can find the library. For example, on Solaris systems, 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 settings for compiling and linking your LDAP client. Different platforms might require different sets of define statements.
Sample Programs for LDAP C SDK
LDAP C SDK includes several examples that demonstrate the use of the functions that the SDK provides. The examples are located in the examples/ directory. The example code is designed to run against the LDAP v3 compliant Directory Server. Furthermore, the example code is designed to work with sample data that has been properly loaded. For details on the source files, refer to the README in the examples/ directory.
The samples use synchronous LDAP calls and their asynchronous counterparts. Because synchronous LDAP calls are more straightforward than their asynchronous counterparts, look at the synchronous examples first.
Synchronous Examples
The synchronous calls block the calling process until all results have been returned. As these programs usually rely on event loops, the programs are not appropriate for use with clients that implement a GUI in a single-threaded environment. However, these sample programs do work with command-line clients and CGI programs.
| Example Source |
Description |
|---|---|
| authzid.c |
Shows how to use the authorization ID control, which allows you to get the authorization ID for an LDAP operation. |
| 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. |
| crtfilt.c |
Shows how to use the ldap_create_filter() function to generate LDAP filters. |
| csearch.c |
Like search.c, but enables an in-memory cache. |
| effright.c |
Shows how to use the get effective rights control, which allows you to determine access rights to entries and their attributes. |
| getattrs.c |
Retrieves specific attributes from an entry. |
| getfilt.c |
Shows how to use the ldap_getfilter*() family of functions, which generate LDAP filters that are based on an arbitrary search string provided by a user. |
| 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. |
| passwordpolicy.c |
Shows how to use the password policy control. This control allows you to retrieve information about the password policy that applies to the user binding to the directory. |
| pwdextop.c |
Shows how to use the LDAP password modify extended operation to change a password. |
| rdentry.c |
Shows how to use ldap_search_s() to retrieve a particular entry from the directory. |
| realattr.c |
Shows how to use the control to retrieve only real attributes during a search. |
| search.c |
Shows how to use ldap_search_s() to search for all entries that have an attribute value that exactly matches what you search for. |
| srvrsort.c |
Shows how to use server-side sorting in conjunction with the ldap_search_ext_s() function. |
| ssearch.c |
Like ssnoauth.c, but includes certificate-based authentication. |
| ssnoauth.c |
Like search.c, but the search is done over an SSL-protected TCP connection. |
| starttls.c |
Shows how to use the Start TLS extended operation. |
| userstatus.c |
Shows how to use the account status control to retrieve information about the account of the user binding to the directory. |
| virtattr.c |
Shows how to use the control to retrieve only virtual attributes during a search. |
| whoami.c |
Shows how to use the Who am I? extended operation to retrieve the authorization ID. |
Asynchronous Examples
These examples use the asynchronous LDAP calls. You begin an operation. You then periodically poll to see if any results have been returned.
| Example Source |
Description |
|---|---|
| add.c |
Adds an entry to the directory. |
| asearch.c |
Initiates a search for entries, printing the results on arrival. |
| del.c |
Deletes an entry from the directory. |
| nsprio.c |
Like asearch. but uses the PerLDAP routines to incorporate the Netscape Portable Runtime (NSPR) API. |
| ppolicy.c |
Attempts to bind to the directory and reports back any password expiration information received. This program demonstrates how clients can process password policy information. |
| psearch.c |
Shows how to use Persistent Search, an LDAP v3 extension, to monitor a directory for changes. |
