Getting Started

Table of Contents | Previous | Next | Index

Netscape Directory SDK 3.0 for C Programmer’s Guide

Getting Started

The Netscape Directory SDK 3.0 for C Programmer's Guide documents the Netscape Directory SDK for C, a development kit for writing LDAP (Lightweight Directory Access Protocol) applications. (For an explanation of LDAP, see Chapter 1, "Understanding LDAP.")

Sections:

What You Should Already Know

Where to Find LDAP Information

New in This Release

Backward Compatibility with Earlier Releases

In This Guide

Documentation Conventions

Sample Code

What You Should Already Know

This guide is intended for use by C and C++ programmers who want to enable new or existing applications to connect to, search, and update LDAP servers. You should already be familiar with writing and compiling C applications.

Where to Find LDAP Information

To find more information about the LDAP protocol and directories, see Directory Developer Central at the Netscape DevEdge site:

http://developer.netscape.com/tech/directory/index.html

New in This Release

This manual accompanies the Netscape Directory SDK 3.0 for C release. This new version of the SDK supports the LDAP v3 protocol and includes new functions for:

working with LDAP v3 controls (for example, to request server-side sorting of search results)

requesting LDAP v3 extended operations and parsing extended responses

handling search references

using a SASL mechanism for authentication

The Netscape Directory SDK 3.0 for C supports the Internet-Draft "The C LDAP Application Program Interface" (available at http://www.ietf.org/internet-drafts/draft-ietf-ldapext-ldap-c-api-00.txt), which describes a C language application programming interface to LDAP.

Backward Compatibility with Earlier Releases

The Netscape Directory SDK 3.0 for C release introduces new versions of functions that perform LDAP operations. These new functions have names ending with _ext or _ext_s. (For example, the newer functions for performing LDAP add operations are ldap_add_ext() and ldap_add_ext_s().)

The new versions of these functions allow you to pass LDAP v3 controls along with an LDAP request to the server. The asynchronous versions of these new functions (those with names that end with _ext) now return a result code indicating whether or not the LDAP request was sent successfully.

The older versions of these functions (such as ldap_add() and ldap_add_s()), which were provided with the Netscape Directory SDK 1.0, are still supported for backwards-compatibility. If you already have LDAP clients that use these function calls, you do not need to rewrite the clients to use the newer versions of functions.

If you are writing a new client, however, you should use the new versions of these functions.

Also note that, although some functions are deprecated, the Netscape Directory SDK 3.0 for C release still supports these functions. The following table lists the functions that are deprecated.

Table 1 Deprecated functions and their suggested replacements

Deprecated Function Suggested Replacement
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()

Deprecated Function	Suggested Replacement
`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()`

In This Guide

This guide explains how to use the Netscape Directory 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 organized into four parts:

Part 1, "Introduction to LDAP and the Netscape Directory SDK for C", explains how you can use the LDAP C SDK to enable your applications for LDAP.

Part 2, "Writing Clients with the LDAP C SDK", explains how you can use the LDAP C SDK to enable your applications for LDAP.

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 1 describes each chapter in more detail.

Finding information In this manual

To do this: See this chapter:
Learn more about LDAP and the Directory Server
Chapter 1, "Understanding LDAP"

Understand the components of the Netscape Directory SDK for C and how to compile your own applications
Chapter 2, "Using the Netscape Directory SDK for C"

See the complete source code for a sample client
Chapter 3, "Quick Start"

Write a program that connects, searches, and updates an LDAP server
Chapter 4, "Writing an LDAP Client"

Handle errors, understand synchronous and asynchronous functions, handle LDAP referrals
Chapter 5, "Using the LDAP API"

Search an LDAP server for entries
Chapter 6, "Searching the Directory"

Create a search filter or parse a filter configuration file
Chapter 7, "Using Filter Configuration Files"

Add, update, or remove a directory entry from an LDAP server
Chapter 8, "Adding, Updating, and Deleting Entries"

Compare a value against the attribute values in a directory entry
Chapter 9, "Comparing Values in Entries"

Interpret an LDAP URL
Chapter 10, "Working with LDAP URLs"

Get information about the server over the LDAP protocol
Chapter 11, "Getting Server Information"

Connect to an LDAP server over SSL
Chapter 12, "Connecting Over SSL"

Use a SASL mechanism to authenticate to the LDAP server
Chapter 13, "Using SASL Authentication"

Send, receive, and interpret LDAP v3 controls
Chapter 14, "Working with LDAP Controls"

Perform LDAP v3 extended operations
Chapter 15, "Working with Extended Operations"

Write a multi-threaded client
Chapter 16, "Writing Multithreaded Clients"

Look up the description of a data structure
Chapter 17, "Data Types and Structures"

Look up the description of a function
Chapter 18, "Functions"

Look up the description of a status code returned by an API function
Chapter 19, "Result Codes"

To do this:	See this chapter:
Learn more about LDAP and the Directory Server	Chapter 1, "Understanding LDAP"
Understand the components of the Netscape Directory SDK for C and how to compile your own applications	Chapter 2, "Using the Netscape Directory SDK for C"
See the complete source code for a sample client	Chapter 3, "Quick Start"
Write a program that connects, searches, and updates an LDAP server	Chapter 4, "Writing an LDAP Client"
Handle errors, understand synchronous and asynchronous functions, handle LDAP referrals	Chapter 5, "Using the LDAP API"
Search an LDAP server for entries	Chapter 6, "Searching the Directory"
Create a search filter or parse a filter configuration file	Chapter 7, "Using Filter Configuration Files"
Add, update, or remove a directory entry from an LDAP server	Chapter 8, "Adding, Updating, and Deleting Entries"
Compare a value against the attribute values in a directory entry	Chapter 9, "Comparing Values in Entries"
Interpret an LDAP URL	Chapter 10, "Working with LDAP URLs"
Get information about the server over the LDAP protocol	Chapter 11, "Getting Server Information"
Connect to an LDAP server over SSL	Chapter 12, "Connecting Over SSL"
Use a SASL mechanism to authenticate to the LDAP server	Chapter 13, "Using SASL Authentication"
Send, receive, and interpret LDAP v3 controls	Chapter 14, "Working with LDAP Controls"
Perform LDAP v3 extended operations	Chapter 15, "Working with Extended Operations"
Write a multi-threaded client	Chapter 16, "Writing Multithreaded Clients"
Look up the description of a data structure	Chapter 17, "Data Types and Structures"
Look up the description of a function	Chapter 18, "Functions"
Look up the description of a status code returned by an API function	Chapter 19, "Result Codes"

Documentation Conventions

This book uses the following font conventions:

The monospace font is used for sample code and code listings, API and language elements (such as function names and class names), filenames, pathnames, directory names, HTML tags, and any text that must be typed on the screen. (Monospace italic font is used for placeholders embedded in code.)

Italic type is used for book titles, emphasis, variables and placeholders, and words used in the literal sense.

Boldface type is used for glossary terms.

Sample Code

This book contains sample C code for LDAP clients. This code was tested on a Solaris 2.5.1 machine and on a Windows NT 4.0 machine with Microsoft Visual C++ 4.2.

Table of Contents | Previous | Next | Index

Last Updated: 10/01/98 17:02:01