LDAP APIs

Early on, the developers of LDAP realized that directory-enabled applications would be created much more quickly if a standard API existed for accessing and updating the directory. The original LDAP distribution from the University of Michigan (often referred to as the U-M LDAP release; see Chapter 1, Directory Services Overview and History) included a C programming library and several sample client programs built on this library. For a while, the C API included in the U-M distribution was the only API/SDK available. With the current industry momentum behind LDAP, however, the number of SDKs is increasing, and additional SDKs are becoming available. (We will discuss these additional SDKs later in this section and in Chapter 21, Developing New Applications.) Figure 2.22 shows how the LDAP SDK fits into a directory-enabled client application.

Figure 2.22. The LDAP API Provides a Common Interface to an LDAP Client Library SDK

The LDAP C API for LDAPv2 is documented in RFC 1823, and a proposed C API for LDAPv3 is in draft form at this time (available from the IETF Web site at http://www.ietf.org). The C API document simply defines the API calls and their semantics.

To obtain an SDK, you need to download one from any of the following sources:

• The OpenLDAP Project includes an LDAPv2/LDAPv3 SDK and is available in source code from http://www.openldap.org.

• An LDAPv2/LDAPv3 C SDK is available free of charge in binary form from Sun Microsystems at http://wwws.sun.com/software/download/developer. The Mozilla LDAP C SDK, upon which the Netscape SDK is based, is available in source code form from http://www.mozilla.org/directory.

• Microsoft provides an LDAPv2/LDAPv3 SDK with Windows 2000. Documentation is available from the MSDN site at http://msdn.microsoft.com.

All the C SDKs can, of course, be used from a C++ program.

Overview of the LDAP C API

The LDAP C API defines a set of core functions, listed in Table 2.7, that map almost one to one onto the LDAP protocol operations. These APIs provide an asynchronous interface to the directory; that is, the calls are used to initiate a protocol operation to the server, and the ldap_result() call is used later to collect results from the previously initiated operations. This capability allows a client to issue multiple protocol requests or perform other work, such as updating window contents, while the operation is in progress on the server.

The API also provides a synchronous interface, in which the API calls are blocked until all results are returned from the server. The synchronous calls are generally simpler to use and are appropriate for simple command-line clients and multithreaded applications.

In addition to the API calls listed in Table 2.7 and their synchronous counterparts, the LDAP C API (1) defines a set of utility routines that can be used to parse returned results from the server; (2) iterates over sets of entries, attributes, and attribute values; and (3) performs other useful operations. For a complete description of the various API calls available in the SDK you're using, consult the documentation.

Table 2.7. The Main LDAP C API Functions

Function	Description
ldap_search()	Searches for directory entries
ldap_compare()	Tests whether an entry contains a given attribute value
ldap_bind()	Authenticates (proves your identity) to a directory server
ldap_unbind()	Terminates an LDAP session
ldap_modify()	Makes changes to an existing directory entry
ldap_add()	Adds a new directory entry
ldap_delete()	Deletes an existing directory entry
ldap_rename()	Renames an existing directory entry (this function is named ldap_modrdn() in LDAPv2-only SDKs)
ldap_result()	Retrieves the results of one of the previous operations

A useful reference book that covers the LDAP C API in detail and offers general advice on building directory-enabled applications was written by two of the authors of this book. It is called LDAP: Programming Directory-Enabled Applications with Lightweight Directory Access Protocol , by Tim Howes and Mark Smith, published in 1997 by Macmillan Technical Publishing. Note that that book describes the LDAPv2 C API calls only, and not the updated LDAPv3 API calls.

Other LDAP APIs

In addition to the various implementations of the C API, four other APIs are available:

1. Netscape has developed an LDAPv2 and LDAPv3 Java API that, like the LDAP C API, has a close mapping onto the LDAP protocol. The Java API specification, currently in draft form, is available from the IETF Web site at http://www.ietf.org. An SDK that implements the draft API is available from http://wwws.sun.com/software/download/developer and, like the C SDK, is available in source code form at http://www.mozilla.org. Online documentation is also available. The Java classes that implement the Netscape SDK are also included with versions of Netscape Communicator currently being shipped.

2. Perl fans can use Net::LDAP, available from http://www.cpan.org, or PerLDAP, available from http://www.mozilla.org.

3. Python programmers can use the python-ldap module, available from http://python-ldap. sourceforge .net.

4. JavaSoft has developed the proprietary Java Naming and Directory Interface (JNDI). This API/SDK defines a common interface for accessing various different directory systems from a Java application or applet. Additional types of directory systems and protocols can be supported through the development of additional service provider interfaces (SPIs) for JNDI. This feature allows a JNDI client to access several distinct directory services, such as NIS, DNS, LDAP, NDS, or X.500. JNDI is available from JavaSoft at http://www.javasoft.com.

5. Microsoft also has a proprietary, object-oriented SDK, called ADSI (Active Directory Services Interface), for accessing multiple directory systems. ADSI APIs are available for Visual Basic, C, and C++. For more information on ADSI, see http://www.microsoft.com.