| Sun Java System LDAP SDK for C Programming Guide |
Chapter 1
IntroductionThe Sun™ Java System Directory Server Resource Kit (DSRK) LDAP SDK for C Programming Guide provides instructions for the Lightweight Directory Access Protocol (LDAP) software development kit (SDK) for C as well as usage information for the application programming interfaces (APIs). This introductory chapter contains the following sections:
OverviewThe DSRK includes the Sun Java System LDAP SDK for C. The LDAP SDK for C includes the C libraries for the LDAP API as well as sample code that demonstrates how to call most of the functions. The APIs are defined by the header files that declare all of the functions, data types and code values available in the binaries. You use the functions contained in this API to write C or C++ client applications that take full advantage of the capabilities of Sun Java System Directory Server. The API also includes custom extensions that give access to the latest features in Directory Server 5.2.
Note
Because they are built around core functions of the LDAP v2 and v3 standards, the API can be used to interact with any conforming LDAP server. This API conforms to the Internet Engineering Task Force (IETF) standard proposed in The C LDAP Application Programming Interface (http://www.ietf.org/proceedings/00dec/I-D/draft-ietf-ldapext-ldap-c-api-05.txt).
The LDAP API
The Lightweight Directory Access Protocol (v3), RFC 2251 (http://www.faqs.org/rfcs/rfc2251.html) defines a set of operations that must be used to access data in a LDAPv3-compliant directory server. The functionality implemented in the LDAP SDK for C closely follows these operations as a C API is defined for each operation. Using the C API, you can enable your clients to connect to LDAPv3-compliant directory servers and perform standard or extended LDAP functions such as:
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.)
- You can call a synchronous function if you want the client applications’ calling thread to wait for the operation to complete before receiving the return value of a function.
- You can call an asynchronous function and poll the LDAP client library to check the status of the operation if you want to perform other work while waiting for an operation to complete.
For more information on synchronous and asynchronous operations, see "Synchronous Examples" and "Asynchronous Examples" as well as "Managing Memory" of Chapter 4, "Using the LDAP API." For a complete list of the functions implemented in this SDK, refer to Chapter 17, "Function Reference."
Installation Instructions
Instructions on installing the DSRK can be found in the Sun Java System Directory Server Resource Kit Tools Reference (http://docs.sun.com/doc/816-6400-10). After installation, the base directory for the LDAP SDK for C on a Solaris™ operating system is DSRK_base/lib/ldapcsdk.
Provided Directories and FilesThe DSRK, in addition to the utilities discussed in the Sun Java System Directory Server Resource Kit Tools Reference (http://docs.sun.com/doc/816-6400-10) and the SDK discussed in the Sun Java System Directory Server Resource Kit LDAP SDK for Java Programming Guide (http://docs.sun.com/doc/817-6708-05), installs C header files, C libraries, tools, and example programs for use with the LDAP SDK for C. These files are contained in the directories outlined in Table 1-1. The directories are installed in DSRK_base/lib/ldapcsdk.
Table 1-1 LDAP SDK for C Directories
Directory
Description
etc
This directory contains miscellaneous files that can be modified and used. They are described in this chapter’s section, "Miscellaneous Files."
examples
This directory contains sample source code and makefiles for LDAP clients. See the README file in this directory for more information.
include
This directory contains the header files. You must include the files contained in this directory in your client source files. The header files are described in this chapter’s section, "Header Files."
include-nspr
This directory contains Netscape Portable Runtime (NSPR) header files. The NSPR provides a platform-neutral API for system level and libc-like functions. More information on these headers and NSPR in general can be found in the NSPR Reference (http://www.mozilla.org/projects/nspr/reference/html/index.html).
include-private
This directory contains private header files that are not documented in this guide.
lib
This directory contains the C library files. The specific library used is dependent on the type of application you are building. For details, see this chapter’s section, "Libraries."
lib-private
This directory contains private libraries that are not documented.
tools
This directory contains the LDAP command-line tools. They are described in the Tools Reference (http://docs.sun.com/doc/816-6400-10). In order to use these applications, you need to ensure that they can find the LDAP API shared library or dynamic link library.
Header Files
Header files contain information about the library that programs using it need to know; for example, it might contain constants and types, along with prototypes for functions available in the library. The LDAP SDK for C header files can be found in the DSRK_base/lib/ldapcsdk/include directory. They are listed in Table 1-2.
Table 1-2 LDAP SDK for C Header Files
Header File
Description
disptmpl.h
A header file related to the templates (ldaptemplates.conf).
iutil.h
Contains the interface for libiutil, the Innosoft migration library.
lber.h
Contains prototypes for the standard Basic Encoding Rules (BER) functions, structures and defines. More information is in the section on "lber.h."
ldap-deprecated.h
Contains deprecated functions that should not be used. This header is included by ldap.h.
ldap-extension.h
Contains functions, structures and defines that extend the standard LDAP C API specification. This header is included by ldap.h.
ldap-platform.h
A private header file that contains platform-specific definitions / abstraction layer.
ldap-standard.h
Contains the standard LDAP functions, structures and defines. This header is included in ldap.h.
ldap-to-be-deprecated.h
Contains functions, structures and defines that will be deprecated in future releases. This header is included in ldap.h.
ldap.h
This base header contains LDAP functions, structures, and defines to mirror the latest LDAP C API specifications. This header also includes the ldap-deprecated.h, ldap-extension.h, ldap-standard.h, and ldap-to-be-deprecated.h headers. More information is in "ldap.h."
ldap_ssl.h
Contains prototypes for LDAP over SSL functions, structures, and defines. More information is in "ldap_ssl.h."
ldappr.h
Contains prototypes for the functions, structures, and defines contained in the Netscape Portable Runtime. More information is in "ldappr.h."
srchpref.h
A header file related to the search preferences (ldapsearchprefs.conf).
ldap.h
To make use of the functions contained in the LDAP SDK for C, whether you are developing on a UNIX�-based or 32-bit Microsoft� Windows system, you must include the ldap.h header file in your C source files as shown in the following line of code:
#include “ldap.h”
Including this file in your source also includes the following header files:
lber.h
lber.h is included in ldap-standard.h; therefore you do not need to explicitly include it. Basic Encoding Rules (BER) is a simple tag/value scheme that encodes requests and decodes results as well as sending and receiving said requests.
ldap_ssl.h
If you are calling the LDAP over SSL functions, you also need to include the ldap_ssl.h header file, as follows:
#include “ldap_ssl.h”
ldappr.h
To make use of the Netscape Portable Runtime (NSPR) with your LDAP applications, you must include ldappr.h. NSPR is a set of platform-neutral API 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 it as follows:
#include “ldappr.h”
You can find more information on NSPR in the ldappr.h header file itself and at the Netscape Portable Runtime project page. Additional information regarding the DSRK and NSPR can be found in "Dependencies."
Miscellaneous Files
The LDAP SDK for C ships with the the sample files described in Table 1-3. They can be called by the end user specifically when using certain API. They are in the DSRK_base/lib/ldapcsdk/etc directory.
Table 1-3 Sample Configuration Files
File Name
Description
ldapfilter.conf
This LDAP filter configuration file can be used in context with ldap_init_getfilter().
ldapfriendly
This file is used to map the two letter 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.
Libraries
The LDAP SDK for C comes with several different libraries. A library is a set of ready-made functions which are linked into a program. There are two types of libraries: static and shared. Static (or archive) libraries are compiled with the code. Shared libraries are dynamically loaded into memory when needed, reducing the size of the executable. The specific library files to which you link is dependent on the type of application you are building.
Library Naming Conventions
Libraries on different systems have different naming conventions. Table 1-4 details the conventions relevant to Sun Java System DSRK.
Installed Shared Libraries
Table 1-5 outlines the installed libraries. They can be found in the DSRK_base/lib/ldapcsdk/lib directory.
Dependencies
The following dependencies are essential when compiling your application.
- Libraries built with NSPR require a link to the libnspr4.so library installed in DSRK_base/lib/ldapcsdk/lib-private. libnspr4.so contains the core functions of the NSPR.
- The libraries built with support for Secure Sockets Layer (SSL) require a link to the libnss3.so and libnspr4.so libraries installed in DSRK_base/lib/ldapcsdk/lib-private. libnspr4.so contains the core functions of the NSPR and libnss3.so contains the Netscape Security Services (NSS) which provides encryption, cryptographic and SSL/Public Key Infrastructure (PKI) support.
LDAP Tools
The LDAP SDK for C includes several utilities to help you work with LDAP data sets. They are installed in the DSRK_base/lib/ldapcsdk/tools directory (and duplicated in the DSRK_base/bin/dsrk52 directory). Table 1-6 outlines the tools; more information can be found in the Tools Reference (http://docs.sun.com/doc/816-6400-10). A list of options can be retreived by typing the tool name at the command line.
Compiling ApplicationsAs detailed in "Provided Directories and Files," the DSRK includes header files and corresponding shared libraries for it’s API functions. You must include the header files and link to the libraries when compiling your application. Inclusion of the header files is discussed in "Header Files." Linking to shared libraries is done when compiling the application; this is discussed in the following sections.
Note
The LDAP SDK for C is tested and certified to work with C compilers. It is not guaranteed to work with C++ compilers.
Compiling on UNIX Platforms
When compiling clients on UNIX platforms, you might need to specify a link option to link the application to the appropriate shared libraries. When compiling the application (using the gcc or cc command), you would use the -L option to add a new path and file for which the link editor can search. (Path names defined using the -L option are used only by the link editor implementation of the compiler application.) For example, on Solaris, you might use the following link option:
gcc ... -Lpath_to_file -file_name ...
Where:
- path_to_file is the path to the file to be linked.
- file_name is the name of the file to be linked.
Refer to Makefile in the DSRK_base/lib/ldapcsdk/examples directory for more details on compiling your applications on UNIX platforms.
Compiling on Windows Systems
The DSRK provides both static (or import) and dynamic versions of it’s Windows-based libraries. When compiling clients on 32-bit Windows systems (Windows 2000, Windows 2003, Windows XP, Windows NT, Windows 95, Windows 98, and Windows ME), make sure to link to the SSL-enabled static library. The name of the library, installed in DSRK_base/WindowsVersion/lib/ldapcsdk/lib, is nsldapssl32v50.lib.
Using the DLL
You should also copy the nsldap32v50.dll dynamic link library (DLL) to a directory where your client can find it. Sun Java System 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 DSRK before it finds the version in the system32 directory. For example, you can copy the DSRK DLL to the same directory as your client application. During run-time, your client searches for the DLL in the following locations:
Definitions
A Windows application can use either a command-line interface, or a graphical user interface (GUI). Under 32-bit Windows systems, there is also the notion of a console application in which all user interaction happens via a standard DOS shell interface, with a FILE pointer like that in Unix. This does not exist under Win16, where a Windows window is required. Because of this, make sure to define:
Linking To NSPR Libraries
The NSPR libraries (as discussed in “ldappr.h”) are distributed with the LDAP SDK for C. When linking with SSL-enabled applications, you must also link with the NSPR libraries. For more information on the NSPR libraries, see the NSPR Reference (http://www.mozilla.org/projects/nspr/reference/html/index.html).
Linking Dependencies
When you run LDAP clients on UNIX-based or Windows system, 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 will accomplish this.
- Make sure that the shared library file (such as libldap50.so for Solaris) is in a location specified by environment variables.
- On some platforms, if you have compiled your client with certain flags set, you can set an environment variable to specify the runtime path to check when loading libraries. For example, on Solaris and Linux, you can use the LD_LIBRARY_PATH environment variable if you use the -Wl,+s+b flag when compiling and linking. (On HP-UX, you can use the SHLIB_PATH environment variable, and 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.
The Example ProgramsThe DSRK ships with several examples that demonstrate the use of the functions contained in the LDAP SDK for C library. Located in the DSRK_base/lib/ldapcsdk/examples directory, the example code assumes that you are running clients against the LDAPv3-compliant Sun Java System Directory Server and that you have the sample database properly loaded. For details on the source files, refer to the README contained in the examples directory.
Synchronous Examples
The synchronous calls block the calling process until all results have been returned. Because these programs usually rely on event loops, they are not appropriate for use with clients that implement a GUI in a single-threaded environment. However, these sample programs work fine with command-line clients and CGI programs. Table 1-7 lists the synchronous examples in the LDAP SDK for C.
Table 1-7 Synchronous Example Programs
Example Source
Description
search.c
Shows how to use ldap_search_s() to search for all entries which have an attribute value that 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.
getattrs.c
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 functions, 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; you begin an operation, and periodically poll to see if any results have been returned. Table 1-8 lists the asynchronous examples in the LDAP SDK for C.
