contents

Next | Index

Netscape Directory SDK 3.0 for C Programmer's Guide

This guide describes the LDAP API functions available in the Netscape Directory SDK 3.0. The book explains how to write an LDAP client application that you can use to search a directory and update directory information.

October 1, 1998

Contents

Getting Started

What You Should Already Know

Where to Find LDAP Information

New in This Release

Backward Compatibility with Earlier Releases

Documentation Conventions

Part 1 Introduction to LDAP and the Netscape Directory SDK for C

Chapter 1 Understanding LDAP

This chapter explains the LDAP protocol and the concepts behind LDAP.

How Directory Services Work

How LDAP Servers Organize Directories

How LDAP Clients and Servers Work

Understanding the LDAP v3 Protocol

For More Information

Chapter 2 Using the Netscape Directory SDK for C

This chapter describes the Lightweight Directory Access Protocol (LDAP) Application Programming Interface (API) and the Netscape Directory SDK for C.

Understanding the LDAP API

Working with the Netscape Directory SDK for C

Including the LDAP Header File

Compiling Clients on UNIX

Compiling Clients on Windows

Compiling Clients on Mac OS

Chapter 3 Quick Start

This chapter provides a simple example of an LDAP client written with the Netscape Directory SDK for C.

Understanding the Sample Client

Compiling the Sample Client

Running the Sample Client

Part 2 Writing Clients with the LDAP C SDK

Chapter 4 Writing an LDAP Client

This chapter describes the general process of writing an LDAP client. The chapter covers the procedures for connecting to an LDAP server, authenticating, requesting operations, and disconnecting from the server.

Overview: Designing an LDAP Client

Initializing an LDAP Session

Specifying a Single LDAP Server

Specifying a List of LDAP Servers

Setting Preferences

Examples of Initializing an LDAP Session

Binding and Authenticating to an LDAP Server

Understanding Authentication Methods

Using Simple Authentication

Binding Anonymously

Performing LDAP Operations

Closing the Connection to the Server

Chapter 5 Using the LDAP API

This chapter covers some of the general LDAP API functions that are commonly used when writing LDAP clients. This chapter includes instructions on getting version information, freeing memory, checking for errors, and requesting synchronous and asynchronous functions.

Getting Information About the SDK

Managing Memory

Reporting Errors

Getting Information About the Error

Getting the Error Message

Setting Error Codes

Printing Out Error Messages

Calling Synchronous and Asynchronous Functions

Calling Synchronous Functions

Calling Asynchronous Functions

Handling Referrals

Understanding Referrals

Enabling or Disabling Referral Handling

Limiting Referral Hops

Binding When Following Referrals

Setting Up an In-Memory Cache

Handling Failover

Creating a New Connection Handle

Using the Reconnect Option

Chapter 6 Searching the Directory

This chapter explains how to call the LDAP API functions to search the directory, retrieve search results, and get attributes and values from each entry in the search results. The chapter also provides examples of calling synchronous and asynchronous functions to search the directory.

Overview: Searching with LDAP API Functions

Sending a Search Request

Specifying the Base DN and Scope

Specifying a Search Filter

Specifying the Attributes to Retrieve

Setting Search Preferences

Example of Sending a Search Request

Getting Search Results

Getting Results Synchronously

Getting Results Asynchronously

Iterating Through a Chain of Results

Getting Distinguished Names for Each Entry

Getting Attributes from an Entry

Getting the Values of an Attribute

Getting Referrals from Search References

Sorting the Search Results

Sorting Entries by an Attribute

Sorting Entries by Multiple Attributes

Sorting the Values of an Attribute

Freeing the Results of a Search

Example: Searching the Directory (Asynchronous)

Example: Searching the Directory (Synchronous)

Reading an Entry

Listing Subentries

Chapter 7 Using Filter Configuration Files

This chapter explains how to use API function to work with filter configuration files. Filter configuration files can help simplify the process of selecting the appropriate search filter for a search request.

Understanding Filter Configuration Files

Understanding the Configuration File Syntax

Understanding Filter Parameters

Loading a Filter Configuration File

Retrieving Filters

Adding Filter Prefixes and Suffixes

Freeing Filters from Memory

Creating Filters Programmatically

Chapter 8 Adding, Updating, and Deleting Entries

This chapter explains how to use the API functions to add, modify, delete, and rename entries in the directory. The chapter also provides examples of calling synchronous and asynchronous functions to perform these operations.

Specifying a New or Modified Attribute

Adding a New Entry

Specifying the Attributes

Adding the Entry to the Directory

Example: Adding an Entry to the Directory (Synchronous)

Example: Adding an Entry to the Directory (Asynchronous)

Modifying an Entry

Specifying the Changes

Modifying the Entry in the Directory

Example: Modifying an Entry in the Directory (Synchronous)

Example: Modifying an Entry in the Directory (Asynchronous)

Deleting an Entry

Performing a Synchronous Delete Operation

Performing an Asynchronous Delete Operation

Example: Deleting an Entry from the Directory (Synchronous)

Example: Deleting an Entry from the Directory (Asynchronous)

Changing the DN of an Entry

Performing a Synchronous Renaming Operation

Performing an Asynchronous Renaming Operation

Deleting the Attribute for the Old RDN

Changing the Location of the Entry

Example: Renaming an Entry in the Directory (Synchronous)

Example: Renaming an Entry in the Directory (Asynchronous)

Chapter 9 Comparing Values in Entries

This chapter explains how to use the API functions to compare data in entries in the directory. The LDAP API includes functions that you can call to compare the value of an attribute in an entry against a specified value.

Comparing the Value of an Attribute

Performing a Synchronous Comparison Operation

Performing an Asynchronous Comparison Operation

Example: Comparing a Value in an Entry (Synchronous)

Example: Comparing a Value in an Entry (Asynchronous)

Chapter 10 Working with LDAP URLs

This chapter explains how you can call functions to parse an LDAP URL into its components and to process a search request specified by an LDAP URL.

Understanding LDAP URLs

Examples of LDAP URLs

Determining If a URL is an LDAP URL

Getting the Components of an LDAP URL

Freeing the Components of an LDAP URL

Processing an LDAP URL

Part 3 Advanced Topics

Chapter 11 Getting Server Information

This chapter explains how to access and modify information about your LDAP server over the LDAP protocol.

Understanding DSEs

Getting the Root DSE

Determining If the Server Supports LDAP v3

Getting Schema Information

Chapter 12 Connecting Over SSL

This chapter describes the process of enabling an LDAP client to connect to an LDAP server over the Secure Sockets Layer (SSL) protocol. The chapter covers the procedures for connecting to an LDAP server and authenticating.

Overview: How SSL Works with the Netscape LDAP C SDK

Prerequisites for Connecting Over SSL

Enabling Your Client to Connect Over SSL

Installing Your Own SSL I/O Functions

Using Certificate-Based Client Authentication

Chapter 13 Using SASL Authentication

This chapter describes the process of using a SASL mechanism to authenticate an LDAP client to an LDAP server.

Understanding SASL

Determining the SASL Mechanisms Supported

Authenticating Using a SASL Mechanism

Performing a Synchronous SASL Bind Operation

Performing an Asynchronous SASL Bind Operation

Chapter 14 Working with LDAP Controls

This chapter explains how LDAP controls work and how to use the LDAP controls that are supported by the Netscape Directory Server 3.0.

How LDAP Controls Work

Using Controls in the LDAP API

Determining the Controls Supported By the Server

Using the Server-Side Sorting Control

Specifying the Sort Order

Creating the Control

Performing the Search

Interpreting the Results

Known Problems with Server Sorting

Example of Using the Server-Sorting Control

Using the Persistent Search Control

Using the Entry Change Notification Control

Using the Virtual List View Control

Using the Manage DSA IT Control

Using Password Policy Controls

Chapter 15 Working with Extended Operations

This chapter explains how LDAP v3 extended operations work and how to use the extended operations that are supported by your LDAP server.

How Extended Operations Work

Determining the Extended Operations Supported

Performing an Extended Operation

Performing a Synchronous Extended Operation

Performing an Asynchronous Extended Operation

Example: Extended Operation

Chapter 16 Writing Multithreaded Clients

This chapter explains how to write multi-threaded LDAP clients.

Specifying Thread Functions

Setting Up the ldap_thread_fns Structure

Setting Up the ldap_extra_thread_fns Structure

Setting the Session Options

Example of Specifying Thread Functions

Example of a Pthreads Client Application

Part 4 Reference

Chapter 17 Data Types and Structures

This chapter describes the data structures and data types used by functions in the LDAP API.

LDAP_CMP_CALLBACK

LDAP_DNSFN_GETHOSTBYADDR

LDAP_DNSFN_GETHOSTBYNAME

ldap_extra_thread_fns

LDAP_IOF_CLOSE_CALLBACK

LDAP_IOF_CONNECT_CALLBACK

LDAP_IOF_IOCTL_CALLBACK

LDAP_IOF_READ_CALLBACK

LDAP_IOF_SELECT_CALLBACK

LDAP_IOF_SOCKET_CALLBACK

LDAP_IOF_SSL_ENABLE_CALLBACK

LDAP_IOF_WRITE_CALLBACK

LDAP_REBINDPROC_CALLBACK

LDAP_TF_GET_ERRNO_CALLBACK

LDAP_TF_SET_ERRNO_CALLBACK

LDAP_TF_GET_LDERRNO_CALLBACK

LDAP_TF_SET_LDERRNO_CALLBACK

LDAP_TF_MUTEX_ALLOC_CALLBACK

LDAP_TF_MUTEX_FREE_CALLBACK

LDAP_TF_MUTEX_LOCK_CALLBACK

LDAP_TF_MUTEX_TRYLOCK_CALLBACK

LDAP_TF_MUTEX_UNLOCK_CALLBACK

LDAP_TF_SEMA_ALLOC_CALLBACK

LDAP_TF_SEMA_FREE_CALLBACK

LDAP_TF_SEMA_POST_CALLBACK

LDAP_TF_SEMA_WAIT_CALLBACK

ldap_thread_fns

LDAP_VALCMP_CALLBACK

LDAPVirtualList

Chapter 18 Functions

This chapter lists all the public functions of the LDAP API in alphabetic order. Each description identifies the name of the function, its header file, its syntax, what it returns, its parameters, and an example of its use.

Summary of Functions by Task

Initializing and Ending LDAP Sessions

Authenticating to an LDAP Server

Performing LDAP Operations

Getting Search Results

Sorting Search Results

Working with Search Filters

Working with Distinguished Names

Working with LDAP v3 Controls

Working with LDAP URLs

Getting the Attribute Values for a Particular Language

Handling Errors

Functions (in alphabetical order)

ldap_abandon_ext()

ldap_add_ext_s()

ldap_ber_free()

ldap_build_filter()

ldap_compare_ext()

ldap_compare_ext_s()

ldap_compare_s()

ldap_control_free()

ldap_controls_free()

ldap_count_entries()

ldap_count_messages()

ldap_count_references()

ldap_count_values()

ldap_count_values_len()

ldap_create_filter()

ldap_create_persistentsearch_control()

ldap_create_sort_control()

ldap_create_sort_keylist()

ldap_create_virtuallist_control()

ldap_delete_ext()

ldap_delete_ext_s()

ldap_delete_s()

ldap_err2string()

ldap_explode_dn()

ldap_explode_rdn()

ldap_extended_operation()

ldap_extended_operation_s()

ldap_first_attribute()

ldap_first_entry()

ldap_first_message()

ldap_first_reference()

ldap_free_friendlymap()

ldap_free_sort_keylist()

ldap_free_urldesc()

ldap_friendly_name()

ldap_get_entry_controls()

ldap_getfilter_free()

ldap_getfirstfilter()

ldap_get_lang_values()

ldap_get_lang_values_len()

ldap_get_lderrno()

ldap_getnextfilter()

ldap_get_option()

ldap_get_values()

ldap_get_values_len()

ldap_init_getfilter()

ldap_init_getfilter_buf()

ldap_is_ldap_url()

ldap_memcache_destroy()

ldap_memcache_flush()

ldap_memcache_get()

ldap_memcache_init()

ldap_memcache_set()

ldap_memcache_update()

ldap_modify_ext()

ldap_modify_ext_s()

ldap_modify_s()

ldap_modrdn_s()

ldap_modrdn2_s()

ldap_mods_free()

ldap_multisort_entries()

ldap_next_attribute()

ldap_next_entry()

ldap_next_message()

ldap_next_reference()

ldap_parse_entrychange_control()

ldap_parse_extended_result()

ldap_parse_reference()

ldap_parse_result()

ldap_parse_sasl_bind_result()

ldap_parse_sort_control()

ldap_parse_virtuallist_control()

ldap_rename_s()

ldap_result2error()

ldap_sasl_bind()

ldap_sasl_bind_s()

ldap_search_ext()

ldap_search_ext_s()

ldap_search_s()

ldap_search_st()

ldap_set_filter_additions()

ldap_setfilteraffixes()

ldap_set_lderrno()

ldap_set_option()

ldap_set_rebind_proc()

ldap_simple_bind()

ldap_simple_bind_s()

ldap_sort_entries()

ldap_sort_values()

ldap_sort_strcasecmp()

ldap_unbind_s()

ldap_url_parse()

ldap_url_search()

ldap_url_search_s()

ldap_url_search_st()

ldap_value_free()

ldap_value_free_len()

ldapssl_advclientauth_init()

ldapssl_client_init()

ldapssl_clientauth_init()

ldapssl_enable_clientauth()

ldapssl_install_routines()

Chapter 19 Result Codes

This chapter lists the LDAP result codes returned by functions in the LDAP API.

LDAP_ADMINLIMIT_EXCEEDED

LDAP_AFFECTS_MULTIPLE_DSAS

LDAP_ALIAS_DEREF_PROBLEM

LDAP_ALIAS_PROBLEM

LDAP_ALREADY_EXISTS

LDAP_AUTH_UNKNOWN

LDAP_CLIENT_LOOP

LDAP_COMPARE_FALSE

LDAP_COMPARE_TRUE

LDAP_CONFIDENTIALITY_REQUIRED

LDAP_CONNECT_ERROR

LDAP_CONSTRAINT_VIOLATION

LDAP_CONTROL_NOT_FOUND

LDAP_DECODING_ERROR

LDAP_ENCODING_ERROR

LDAP_FILTER_ERROR

LDAP_INAPPROPRIATE_AUTH

LDAP_INAPPROPRIATE_MATCHING

LDAP_INDEX_RANGE_ERROR

LDAP_INSUFFICIENT_ACCESS

LDAP_INVALID_CREDENTIALS

LDAP_INVALID_DN_SYNTAX

LDAP_INVALID_SYNTAX

LDAP_LOCAL_ERROR

LDAP_LOOP_DETECT

LDAP_MORE_RESULTS_TO_RETURN

LDAP_NAMING_VIOLATION

LDAP_NO_OBJECT_CLASS_MODS

LDAP_NO_RESULTS_RETURNED

LDAP_NO_SUCH_ATTRIBUTE

LDAP_NO_SUCH_OBJECT

LDAP_NOT_ALLOWED_ON_NONLEAF

LDAP_NOT_ALLOWED_ON_RDN

LDAP_NOT_SUPPORTED

LDAP_OBJECT_CLASS_VIOLATION

LDAP_OPERATIONS_ERROR

LDAP_PARAM_ERROR

LDAP_PARTIAL_RESULTS

LDAP_PROTOCOL_ERROR

LDAP_REFERRAL_LIMIT_EXCEEDED

LDAP_RESULTS_TOO_LARGE

LDAP_SASL_BIND_IN_PROGRESS

LDAP_SERVER_DOWN

LDAP_SIZELIMIT_EXCEEDED

LDAP_SORT_CONTROL_MISSING

LDAP_STRONG_AUTH_NOT_SUPPORTED

LDAP_STRONG_AUTH_REQUIRED

LDAP_TIMELIMIT_EXCEEDED

LDAP_TYPE_OR_VALUE_EXISTS

LDAP_UNAVAILABLE

LDAP_UNAVAILABLE_CRITICAL_EXTENSION

LDAP_UNDEFINED_TYPE

LDAP_UNWILLING_TO_PERFORM

LDAP_USER_CANCELLED

Glossary

This glossary defines terms commonly used when working with LDAP.

Index

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