Mozilla LDAP C SDK Programmer's Guide
Preface
The LDAP C SDK Programmer's Guide documents the Mozilla LDAP C SDK, a software development kit (SDK) for writing Lightweight Directory Access Protocol (LDAP) client applications. This SDK supports the The C LDAP Application Program Interface Internet-Draft. The draft is a formal description of the C language API for LDAP.
The Mozilla LDAP C SDK includes the C libraries for the LDAP application programming interface (API). You use the functions contained in this API to enable your applications to connect to, search, and update LDAP servers located on a network or on the Internet. For a more detailed explanation of LDAP, see Chapter 2 - "An Introduction to LDAP"."
This Preface contains the following sections:
- What You Are Expected to Know
- About This Release
- Organization of This Guide
- Documentation Conventions
- Where to Find Additional Information
What You Are Expected to Know
This guide is intended for use by C and C++ programmers who want to enable new or existing client applications to connect to LDAP servers. The functionality contained in the LDAP C SDK allows you to search and update databases that are managed by LDAP servers. This book assumes that you are familiar with writing and compiling C applications on the platform(s) that you want to implement your client applications.
About This Release
While this manual has been updated to cover many of the newer features of the Mozilla LDAP C SDK, there are several areas of functionality that have not been fully documented. When in doubt, consult the header files or the source code.
Deprecated Functions
Although several functions have been deprecated in this release
of the LDAP C SDK, the SDK still supports these deprecated functions
for backward compatibility. The following table outlines some of the
deprecated functions and the functions you should use in their place
whenever you write new code. For more information on the functions
that have been deprecated, refer to the ldap.h header
file and the most recent C LDAP API Internet Draft.
Table 1 - Deprecated functions and their suggested replacements
| Deprecated Function | Suggested Replacement Function(s) |
|---|---|
ldap_bind() |
ldap_simple_bind() or ldap_sasl_bind()
|
ldap_bind_s() |
ldap_simple_bind_s() or ldap_sasl_bind_s()
|
ldap_build_filter() |
ldap_create_filter() |
ldap_cache_flush() |
ldap_memcache_*() functions |
ldap_modrdn |
ldap_rename() |
ldap_modrdn_s() |
ldap_rename_s() |
ldap_open() |
ldap_init() |
ldap_perror() |
ldap_get_lderrno() (to get the result code) and
ldap_err2string() (to get the corresponding error
message for this result code)
|
ldap_result2error() |
ldap_parse_result() |
ldap_setfilteraffixes() |
ldap_set_filter_additions() |
ldap_version |
ldap_get_option() with the LDAP_OPT_API_INFO option
|
Organization of This Guide
This guide explains how to use the Mozilla LDAP C SDK to enable applications to interact with LDAP servers. The guide documents the LDAP API, which consists of data structures and functions used to communicate with LDAP servers.
This manual is divided into four parts:
- Part 1, "Getting Started", explains how you can use the LDAP C SDK to enable your applications for LDAP.
- Part 2, "Writing Clients with the Mozilla LDAP C SDK", explains how you can use the LDAP C SDK to enable your applications for LDAP communications.
- Part 3, "Advanced Topics", contains additional material that you might need, including descriptions of entries and attributes.
- Part 4, "Reference", describes each data structure, function, and status code in the LDAP API.
Table 2 details the chapters contained in the book:
Table 2 - Finding information in this manual
| Chapter | Description |
|---|---|
| Preface | This chapter |
| Part 1, "Getting Started" | |
| Chapter 1 "The Mozilla LDAP C SDK" | Understand the components of the Mozilla LDAP C SDK and how to compile your own applications. |
| Chapter 2 "An Introduction to LDAP" | Learn more about LDAP and the Directory Server. |
| Chapter 3 "A Short Example" | See the complete source code for a sample client. |
| Part 2, "Writing Clients with the Mozilla LDAP C SDK" | |
| Chapter 4 "Writing an LDAP Client" | Write a program that connects, searches, and updates an LDAP server. |
| Chapter 5 "Using the LDAP API" | Handle errors, understand synchronous and asynchronous functions, handle LDAP referrals. |
| Chapter 6 "Searching the Directory" | Search an LDAP server for entries. |
| Chapter 7 "Using Filter Configuration Files" | Create a search filter or parse a filter configuration file. |
| Chapter 8 "Adding, Updating, and Deleting Entries" | Add, update, or remove a directory entry from an LDAP server. |
| Chapter 9 "Comparing Values in Entries" | Compare a value against the attribute values in a directory entry. |
| Chapter 10 "Working with LDAP URLs" | Interpret an LDAP URL. |
| Part 3, "Advanced Topics" | |
| Chapter 11 "Getting Server Information" | Get information about the server over the LDAP protocol. |
| Chapter 12 "Connecting Over SSL" | Connect to an LDAP server over SSL. |
| Chapter 13 "Using SASL Authentication" | Use a SASL mechanism to authenticate to the LDAP server. |
| Chapter 14 "Working with LDAP Controls" | Send, receive, and interpret LDAPv3 controls. |
| Chapter 15 "Working with Extended Operations" | Perform LDAPv3 extended operations. |
| Chapter 16 "Writing Multithreaded Clients" | Write a multi-threaded client. |
| Part 4, "Reference" | |
| Chapter 17 "Data Types and Structures" | Look up the description of a data structure. |
| Chapter 18 "Function Reference" | Look up the description of a function. |
| Chapter 19 "Result Codes" | Look up the description of a status code returned by an API function. |
Documentation Conventions
This book uses the following font conventions:
-
Monospacetype is used for all sample code and code listings. -
Monospacetype is also used within paragraph text to represent language elements (such as function names and class names), reserved names, filenames, pathnames, directory names, HTML tags, and any text that must be typed at a terminal. -
Italic serif fontis used within code and language elements to indicate variable placeholders. For example, in the following command,filenameis a variable placeholder:gunzipfilename.tar.gz - Italic type is used within paragraph text for book titles, emphasis, variables, and placeholders.
Where to Find Additional Information
Netscape provides binary releases of this SDK with their Directory Server product. However, note that this SDK is primarily available in source code form as part of the Mozilla.org open source project. Refer to the following site for more information on how you can get the source code and contribute to the further development of this SDK:
http://www.mozilla.org/directoryRelated Information
The following table lists several sources of information on LDAP and its associated technologies. Note that some of the links in this table are time-sensitve and the drafts might expire.
Table 3 - Sources of information on LDAP and associated protocols
| RFC or Internet-Draft / Internet Location |
|---|
|
Lightweight Directory Access Protocol (v2), RFC 1777 http://www.ietf.org/rfc/rfc1777.txt |
|
Lightweight Directory Access Protocol (v3), RFC 2251 http://www.ietf.org/rfc/rfc2251.txt |
|
The C LDAP Application Program Interface,
Internet-Draft Revision 5 - Status: Deleted http://www.ietf.org/proceedings/01mar/I-D/ldapext-ldap-c-api-05.txt |
|
LDAP Control Extension for Server Side Sorting of Search Results, RFC 2891 ftp://http://www.ietf.org/rfc/rfc2891.txt |
|
Simple Authentication and Security Layer (SASL), RFC 2222 http://www.ietf.org/rfc/rfc2222.txt |
|
Secure Sockets Layer (SSL) Protocol (v3), Internet-Draft Revision 3 http://home.netscape.com/eng/ssl3/ssl-toc.html |
|
Access Control Model for LDAPv3,
Internet-Draft Revision 8 - Status: Deleted http://www.ietf.org/proceedings/01aug/I-D/draft-ietf-ldapext-acl-model-08.txt |
|
LDAP Extensions for Scrolling View Browsing
of Search Results, Internet-Draft Revision 5 - Status: Deleted http://www.ietf.org/proceedings/02mar/I-D/draft-ietf-ldapext-ldapv3-vlv-05.txt |
|
LDAP Control Extension for Server Side
Sorting of Search Results, Internet Draft Revision 3 - Status: Deleted http://www.ietf.org/proceedings/00jul/I-D/ldapext-sorting-03.txt |
|
LDAP Proxied Authorization Control, Revision 12 http://www.ietf.org/internet-drafts/draft-weltman-ldapv3-proxy-12.txt |
|
LDAP Authentication Response Control, RFC 3829 http://www.ietf.org/rfc/rfc3829.txt |
|
Persistent Search: A Simple LDAP Change
Notification Mechanism, Internet-Draft Revision 2 http://www.ietf.org/internet-drafts/draft-ietf-ldapext-psearch-02.txt |
|
Netscape Portable Runtime Library http://www.mozilla.org/projects/nspr |
Technical Documentation Provided By Netscape
You can find information on the LDAP protocol in the documentation for Netscape Directory Server. These documents, along with the installation instructions, release notes, and documentation for all Netscape servers, can be found at the following location: http://enterprise.netscape.com/docs/directory/