You are currently viewing a snapshot of www.mozilla.org taken on April 21, 2008. Most of this content is highly out of date (some pages haven't been updated since the project began in 1998) and exists for historical purposes only. If there are any pages on this archive site that you think should be added back to www.mozilla.org, please file a bug.



Mozilla LDAP C SDK Programmer's Guide

Contents

Recent Changes (including errata)
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
Technical Documentation Provided By Netscape

Part 1 Getting Started

Chapter 1 - The Mozilla LDAP C SDK
The LDAP API
Files Provided With the LDAP C SDK
Directories Installed With the SDK
Include Files Supplied with the LDAP C SDK
Libraries Supplied with the LDAP C SDK
Tools Supplied With the LDAP C SDK
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 Mozilla LDAP C SDK

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 C SDK
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
berval
BerElement
FriendlyMap
LDAP
LDAP_CMP_CALLBACK
LDAPControl
LDAP_DNSFN_GETHOSTBYADDR
LDAP_DNSFN_GETHOSTBYNAME
ldap_dns_fns
ldap_extra_thread_fns
LDAPFiltDesc
LDAPFiltInfo
LDAPHostEnt
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_io_fns
LDAPMemCache
LDAPMessage
LDAPMod
LDAP_REBINDPROC_CALLBACK
LDAPsortkey
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_TF_THREADID_CALLBACK
ldap_thread_fns
LDAPURLDesc
LDAP_VALCMP_CALLBACK
LDAPVersion
LDAPVirtualList
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_EXCEEDED
LDAP_AFFECTS_MULTIPLE_DSAS
LDAP_ALIAS_DEREF_PROBLEM
LDAP_ALIAS_PROBLEM
LDAP_ALREADY_EXISTS
LDAP_AUTH_UNKNOWN
LDAP_BUSY
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_IS_LEAF
LDAP_LOCAL_ERROR
LDAP_LOOP_DETECT
LDAP_MORE_RESULTS_TO_RETURN
LDAP_NAMING_VIOLATION
LDAP_NO_MEMORY
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_OTHER
LDAP_PARAM_ERROR
LDAP_PARTIAL_RESULTS
LDAP_PROTOCOL_ERROR
LDAP_REFERRAL
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_SUCCESS
LDAP_TIMELIMIT_EXCEEDED
LDAP_TIMEOUT
LDAP_TYPE_OR_VALUE_EXISTS
LDAP_UNAVAILABLE
LDAP_UNAVAILABLE_CRITICAL_EXTENSION
LDAP_UNDEFINED_TYPE
LDAP_UNWILLING_TO_PERFORM
LDAP_USER_CANCELLED
Glossary