Contents


Preface

What You Are Expected to Know
About This Release

Deprecated Functions

Organization of This Guide
Documentation Conventions
Where to Find Additional Information

Related Information
iPlanet Technical Documentation

Part 1 Getting Started

Chapter 1 The Netscape LDAP SDK for C

The LDAP API
Files Provided With the LDAP SDK for C

Directories Installed With the SDK
Include Files Supplied with the LDAP SDK for C
Libraries Supplied with the LDAP SDK for C
Tools Supplied With the LDAP SDK for C

Compiling LDAP Clients

Including the LDAP Header File
Compiling Clients on UNIX
Compiling Clients on 32-bit Windows Systems

Running LDAP Application Programs

The UNIX Runtime Library Files
The Windows Runtime Library Files

The Example Programs

Synchronous Examples
Asynchronous Examples

Chapter 2 An Introduction to LDAP

How Directory Services Work
How LDAP Servers Organize Directories
How LDAP Clients and Servers Work
Support for the LDAPv3 Protocol

Chapter 3 A Short Example

Understanding the Sample Client
Compiling the Sample Client

Compiling on Solaris
Compiling on Windows NT

Running the Sample Client

Running on UNIX
Running on Windows NT

Part 2 Writing Clients with the Netscape LDAP SDK for C

Chapter 4 Writing an LDAP Client

Overview: Designing an LDAP Client
Initializing an LDAP Session

Specifying a Single LDAP Server
Specifying a List of LDAP Servers
Setting Preferences

Setting the Restart Preference
Specifying the LDAP Version of Your Client

Examples of Initializing an LDAP Session

Binding and Authenticating to an LDAP Server

Understanding Authentication Methods
Using Simple Authentication

Performing a Synchronous Authentication Operation
Performing an Asynchronous Authentication Operation

Binding Anonymously

Performing LDAP Operations
Closing the Connection to the Server

Chapter 5 Using the LDAP API

Getting Information About the SDK
Managing Memory
Reporting Errors

Getting Information About the Error

Receiving the Portion of the DN Matching an Entry
Getting the Information from an LDAPMessage Structure
Getting the Information from an LDAP Structure

Getting the Error Message
Setting Error Codes
Printing Out Error Messages

Calling Synchronous and Asynchronous Functions

Calling Synchronous Functions
Calling Asynchronous Functions

Checking if the LDAP Request was Sent
Getting the Server Response
Getting Information from the Server Response
Canceling an Operation in Progress
Example of Calling an Asynchronous Function

Handling Referrals

Understanding Referrals
Enabling or Disabling Referral Handling
Limiting Referral Hops
Binding When Following Referrals

How Binding Works When Following Referrals
Defining the Rebind Function
Registering the Rebind Function

Setting Up an In-Memory Cache
Handling Failover

Creating a New Connection Handle
Using the Reconnect Option

Chapter 6 Searching 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 the Distinguished Name of an Entry
Getting the Components of a Distinguished Name

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

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

Specifying a New or Modified Attribute
Adding a New Entry

Specifying the Attributes

Specifying a Single Value in an Attribute
Specifying Multiple Values in an Attribute
Specifying Binary Data as the Values of an Attribute
Specifying the Attributes in the Entry

Adding the Entry to the Directory

Performing a Synchronous Add Operation
Performing an Asynchronous Add Operation

Example: Adding an Entry to the Directory (Synchronous)
Example: Adding an Entry to the Directory (Asynchronous)
Modifying an Entry

Specifying the Changes

Replacing the Values of an Attribute
Removing Values from an Attribute
Adding Values to an Attribute
Removing an Attribute
Adding an Attribute
Assembling the List of Changes

Modifying the Entry in the Directory

Performing a Synchronous Modify Operation
Performing an Asynchronous Modify Operation

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 from 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

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

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

Understanding DSEs
Getting the Root DSE
Determining If the Server Supports LDAPv3
Getting Schema Information

Chapter 12 Connecting Over SSL

How SSL Works with the LDAP SDK for C
Prerequisites for Connecting Over SSL
Enabling Your Client to Connect Over SSL

Handling Errors

Installing Your Own SSL I/O Functions
Using Certificate-Based Client Authentication

Chapter 13 Using SASL Authentication

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

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
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
Using the Proxied Authorization Control

Access Control: The Proxy Right
The Proxied Authorization Control

Example

Chapter 15 Working with Extended Operations

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

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

berva
BerElemen
FriendlyMa
LDA
LDAP_CMP_CALLBAC
LDAPContro
LDAP_DNSFN_GETHOSTBYADD
LDAP_DNSFN_GETHOSTBYNAM
ldap_dns_fn
ldap_extra_thread_fn
LDAPFiltDes
LDAPFiltInf
LDAPHostEn
LDAP_IOF_CLOSE_CALLBAC
LDAP_IOF_CONNECT_CALLBAC
LDAP_IOF_IOCTL_CALLBAC
LDAP_IOF_READ_CALLBAC
LDAP_IOF_SELECT_CALLBAC
LDAP_IOF_SOCKET_CALLBAC
LDAP_IOF_SSL_ENABLE_CALLBAC
LDAP_IOF_WRITE_CALLBAC
ldap_io_fn
LDAPMemCach
LDAPMessag
LDAPMo
LDAP_REBINDPROC_CALLBAC
LDAPsortke
LDAP_TF_GET_ERRNO_CALLBAC
LDAP_TF_SET_ERRNO_CALLBAC
LDAP_TF_GET_LDERRNO_CALLBAC
LDAP_TF_SET_LDERRNO_CALLBAC
LDAP_TF_MUTEX_ALLOC_CALLBAC
LDAP_TF_MUTEX_FREE_CALLBAC
LDAP_TF_MUTEX_LOCK_CALLBAC
LDAP_TF_MUTEX_TRYLOCK_CALLBAC
LDAP_TF_MUTEX_UNLOCK_CALLBAC
LDAP_TF_SEMA_ALLOC_CALLBAC
LDAP_TF_SEMA_FREE_CALLBAC
LDAP_TF_SEMA_POST_CALLBAC
LDAP_TF_SEMA_WAIT_CALLBAC
LDAP_TF_THREADID_CALLBAC
ldap_thread_fn
LDAPURLDes
LDAP_VALCMP_CALLBAC
LDAPVersio
LDAPVirtualLis

Chapter 18 Function Reference

Functions (in alphabetical order)
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 LDAPv3 Controls
Working with LDAP URLs
Getting the Attribute Values for a Particular Language
Handling Errors
Freeing Memory

ber_bvfree(
ber_free(
ldap_abandon(
ldap_abandon_ext(
ldap_add(
ldap_add_ext(
ldap_add_ext_s(
ldap_add_s(
ldap_ber_free(
ldap_build_filter(
ldap_compare(
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_proxyauth_control(
ldap_create_sort_control(
ldap_create_sort_keylist(
ldap_create_virtuallist_control(
ldap_delete(
ldap_delete_ext(
ldap_delete_ext_s(
ldap_delete_s(
ldap_dn2ufn(
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_dn(
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(
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_memfree(
ldap_modify(
ldap_modify_ext(
ldap_modify_ext_s(
ldap_modify_s(
ldap_modrdn(
ldap_modrdn_s(
ldap_modrdn2(
ldap_modrdn2_s(
ldap_mods_free(
ldap_msgfree(
ldap_msgid(
ldap_msgtype(
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_perror(
ldap_rename(
ldap_rename_s(
ldap_result(
ldap_result2error(
ldap_sasl_bind(
ldap_sasl_bind_s(
ldap_search(
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(
ldap_unbind_s(
ldap_unbind_ext(
ldap_url_parse(
ldap_url_search(
ldap_url_search_s(
ldap_url_search_st(
ldap_value_free(
ldap_value_free_len(
ldap_version(
ldapssl_advclientauth_init(
ldapssl_client_init(
ldapssl_clientauth_init(
ldapssl_enable_clientauth(
ldapssl_err2string(
ldapssl_init(
ldapssl_install_routines(
ldapssl_pkcs_init(

Chapter 19 Result Codes

Result Codes Listed Alphabetically
Result Codes Listed in Numerical Order

LDAP_ADMINLIMIT_EXCEEDE
LDAP_AFFECTS_MULTIPLE_DSA
LDAP_ALIAS_DEREF_PROBLE
LDAP_ALIAS_PROBLE
LDAP_ALREADY_EXIST
LDAP_AUTH_UNKNOW
LDAP_BUS
LDAP_CLIENT_LOO
LDAP_COMPARE_FALS
LDAP_COMPARE_TRU
LDAP_CONFIDENTIALITY_REQUIRE
LDAP_CONNECT_ERRO
LDAP_CONSTRAINT_VIOLATIO
LDAP_CONTROL_NOT_FOUN
LDAP_DECODING_ERRO
LDAP_ENCODING_ERRO
LDAP_FILTER_ERRO
LDAP_INAPPROPRIATE_AUT
LDAP_INAPPROPRIATE_MATCHIN
LDAP_INDEX_RANGE_ERRO
LDAP_INSUFFICIENT_ACCES
LDAP_INVALID_CREDENTIAL
LDAP_INVALID_DN_SYNTA
LDAP_INVALID_SYNTA
LDAP_IS_LEA
LDAP_LOCAL_ERRO
LDAP_LOOP_DETEC
LDAP_MORE_RESULTS_TO_RETUR
LDAP_NAMING_VIOLATIO
LDAP_NO_MEMOR
LDAP_NO_OBJECT_CLASS_MOD
LDAP_NO_RESULTS_RETURNE
LDAP_NO_SUCH_ATTRIBUT
LDAP_NO_SUCH_OBJEC
LDAP_NOT_ALLOWED_ON_NONLEA
LDAP_NOT_ALLOWED_ON_RD
LDAP_NOT_SUPPORTE
LDAP_OBJECT_CLASS_VIOLATIO
LDAP_OPERATIONS_ERRO
LDAP_OTHE
LDAP_PARAM_ERRO
LDAP_PARTIAL_RESULT
LDAP_PROTOCOL_ERRO
LDAP_REFERRA
LDAP_REFERRAL_LIMIT_EXCEEDE
LDAP_RESULTS_TOO_LARG
LDAP_SASL_BIND_IN_PROGRES
LDAP_SERVER_DOW
LDAP_SIZELIMIT_EXCEEDE
LDAP_SORT_CONTROL_MISSIN
LDAP_STRONG_AUTH_NOT_SUPPORTE
LDAP_STRONG_AUTH_REQUIRE
LDAP_SUCCES
LDAP_TIMELIMIT_EXCEEDE
LDAP_TIMEOU
LDAP_TYPE_OR_VALUE_EXIST
LDAP_UNAVAILABL
LDAP_UNAVAILABLE_CRITICAL_EXTENSIO
LDAP_UNDEFINED_TYP
LDAP_UNWILLING_TO_PERFOR
LDAP_USER_CANCELLE

Glossary