Preface
The LDAP SDK for C Programmer's Guide documents the Netscape LDAP SDK for C, 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 Netscape LDAP SDK for C 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
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 SDK for C 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
The Netscape LDAP SDK for C, v4.1 has been updated to provide even more support for LDAPv3 than the previous 4.0 release. For details on the new features, refer to the Release Notes that accompany the SDK and the ldap.h header file.
While this manual has been updated to cover many of the new features contained this release, there are several areas of functionality that have not been fully documented. In particular, documentation is forthcoming for the Netscape UTF8 extensions and the LDAPv3 extended I/O callback interface.
Deprecated Functions
Although several functions have been deprecated in this release of the LDAP SDK for C, 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_modrdn2()
|
ldap_rename()
|
ldap_modrdn_s()
ldap_modrdn2_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 Netscape LDAP SDK for C 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 SDK for C to enable your applications for LDAP.
Part 2, "Writing Clients with the Netscape LDAP SDK for C," explains how you can use the LDAP SDK for C 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 Netscape LDAP SDK for C"
|
Understand the components of the Netscape LDAP SDK for C 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 Netscape LDAP SDK for C"
|
|
|
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:
Monospace type is used for all sample code and code listings.
Monospace type 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 font is used within code and language elements to indicate variable placeholders. For example, in the following command, filename is a variable placeholder:
-
gunzip filename.tar.gz
Italic type is used within paragraph text for book titles, emphasis, variables, and placeholders.
Where to Find Additional Information
Netscape and iPlanet provide binary releases of this SDK. However, note that this SDK is also 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/directory
Related 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://info.internet.isi.edu:80/in-notes/rfc/files/rfc1777.txt
|
|
Lightweight Directory Access Protocol (v3), RFC 2251
http://info.internet.isi.edu:80/in-notes/rfc/files/rfc2251.txt
|
|
The C LDAP Application Program Interface, Internet-Draft Revision 5
http://www.ietf.org/internet-drafts/draft-ietf-ldapext-ldap-c-api-05.txt
|
|
LDAP Control Extension for Server Side Sorting of Search Results, RFC 2891
ftp://ftp.isi.edu/in-notes/rfc2891.txt
|
|
Simple Authentication and Security Layer (SASL), RFC 2222
http://info.internet.isi.edu:80/in-notes/rfc/files/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 6
http://www.ietf.org/internet-drafts/draft-ietf-ldapext-acl-model-06.txt
|
|
LDAP Extensions for Scrolling View Browsing of Search Results, Internet-Draft Revision 4
http://www.ietf.org/internet-drafts/draft-ietf-ldapext-ldapv3-vlv-04.txt
|
|
LDAP Control Extension for Server Side Sorting of Search Results
http://www.ietf.org/internet-drafts/draft-ietf-ldapext-sorting-00.txt
|
|
LDAP Proxied Authorization Control, Revision 5
http://www.ietf.org/internet-drafts/draft-weltman-ldapv3-proxy-05.txt
|
|
LDAP Authentication Response Control, Internet-Draft Revision 1
http://www.ietf.org/internet-drafts/draft-weltman-ldapv3-auth-response-01.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
|
iPlanet Technical Documentation
In addition to these sources of information, you can find addition information on the LDAP protocol, the iPlanet Directory Server, and its associated technologies at the following iPlanet development site:
http://developer.iplanet.com/tech/directory/index.html
You can also find information on the LDAP protocol in the documentation for the iPlanet Directory Server. These documents, along with the installation instructions, release notes, and documentation for all iPlanet and Netscape servers, can be found at the following location:
http://docs.iplanet.com/docs/manuals/index.html