Cisco Knowledge Suite Cisco SystemsCisco Press

Cutting Edge
Core Reference
Guided Learning
Networking Architecture
Internet Protocols (IP)
Network Protocols
Transport and Application Protocols
Desktop Protocols
Security and Troubleshooting
Network Resources and Management
Integrated Services

Overview of the LDAP C API

by Timothy A. Howes, Ph.D., and Mark C. Smith - May 30, 2000

Overview of the

Synopsis and Objectives


The Core LDAP Functions


Typical Use of the LDAP Library


Synchronous Versus Asynchronous Use of the LDAP C API






Typical Use of the LDAP Library

The general sequence of a typical block of code that uses LDAP is as follows:

Step 1.  Initialize the library and obtain an LDAP session handle.
Step 2.  Initiate an LDAP operation, and wait for any result(s).
Step 3.  Process the result(s).
Step 4.  Dispose of the LDAP session handle obtained in step 1. 

Note that steps 1 and 4 are required by nearly all applications that use the LDAP library. Typically, these steps consist of one LDAP C API call each: ldap_init() and ldap_unbind(), respectively. Some programmers may want to obtain a single LDAP session handle once when their application starts up and then use it throughout their application, finally disposing of it just before exiting. Other programmers will use a different strategy to manage their use of the LDAP library. For example, you could obtain a new session handle each time you need to use LDAP, and then dispose of it as soon as you are done.

Remember that when you dispose of the LDAP session handle, you are closing your connection to the directory server; reopening the connection can be costly if it is done too often. Sometimes the structure of the application itself may dictate the right strategy (for example, it may be convenient to obtain one LDAP session handle per thread in a multithreaded application). The important point to remember is that every time you obtain an LDAP session handle, you must dispose of it; that is, for every call to ldap_init(), there should be a matching call to ldap_unbind().

Step 1: Initialize the Library and Obtain a Session Handle

The LDAP session handle is of type LDAP * and is the first parameter passed to nearly all of the LDAP C API functions. Roughly speaking, an LDAP library session corresponds to a single connection to an LDAP directory server (in reality, multiple connections may be opened underneath the covers to handle LDAP URLs and referrals). When you use the ldap_init() call to obtain a session handle, you pass the hostname and port of the server that is to be used. The TCP connection itself is not opened until it is needed (that is, when some LDAP operation call is made). The LDAP library hides most of the connection-related details from you.

Step 2: Initiate an LDAP Operation and Wait for Results

This is where the network action occurs. First, any work needed to construct the parameters for the LDAP operation to be performed is done. (For example, construct a filter to use for a search operation, or create a list of changes for a modify operation.) Next, one of the core LDAP functions that was mentioned earlier is called to send an LDAP request to the directory server. The application then waits for an LDAP result to be returned by the server.

The result includes a result code (typically LDAP_SUCCESS, if all went well) and may include other error-related information. For an LDAP search operation, the server may also return one or more entries before the LDAP result.

This process of initiating the LDAP operation and receiving entries and the result may be done synchronously (in which case, a single LDAP C API function is called) or asynchronously (in which case, several simple functions are called). (This is explained in more detail in the section "Synchronous Versus Asynchronous Use of the LDAP C API," later in this tutorial.)

As part of this step, the LDAP result code that the server returned is checked for errors, and appropriate action is taken. For most operations, a result code of LDAP_SUCCESS means that the operation completed successfully. For the modify, add, delete, and modify RDN operations, any other result code indicates that the library or LDAP server failed to perform the requested directory modification. The compare operation uses two special codes to indicate the result of the comparison. The LDAP search operation may return one or more entries even though an error result is returned. This essentially means that only some of the available entries were examined during the search, and your application must decide whether this should be treated as an error.

Step 3: Process the Result(s)

Step 3 is where your application makes use of the data that was returned. For all operations except search, there is probably very little work to do here. Because the search operation returns directory entries, your application will want to parse the entries to pull out information returned from the directory server.

For example, if the purpose of the LDAP search operation was to obtain a person's e-mail address, you will want to call ldap_get_values() to obtain the e-mail address attribute value from the entry. If the purpose of the search operation was to obtain and print the names of a list of entries, you will want to call ldap_first_entry() and ldap_next_entry() to step through the entries, calling ldap_get_dn() on each entry to retrieve its name.

Step 4: Dispose of the LDAP Session Handle

This step is done when you are completely finished with an LDAP session and it is accomplished by ldap_unbind(), as discussed earlier. It is an error to reference an LDAP session handle after it has been disposed of by a call to ldap_unbind().

Previous | Next



Breaking News

One of the primary architects of OpenCable, Michael Adams, explains the key concepts of this initiative in his book OpenCable Architecture.

Expert Advice

Ralph Droms, Ph.D., author of The DHCP Handbook and chair of the IETF Dynamic Host Configuration Working Group, guides you to his top picks for reliable DHCP-related information.

Just Published

Residential Broadband, Second Edition
by George Abe

Introduces the topics surrounding high-speed networks to the home. It is written for anyone seeking a broad-based familiarity with the issues of residential broadband (RBB) including product developers, engineers, network designers, business people, professionals in legal and regulatory positions, and industry analysts.


From the Brains at InformIT


Contact Us


Copyright, Terms & Conditions


Privacy Policy


© Copyright 2000 InformIT. All rights reserved.