Netscape LDAP SDK for C LDAP SDK for C: Chapter 18 Function Reference

Previous Contents Index DocHome Next

Netscape LDAP SDK for C LDAP SDK for C

Chapter 18 Function Reference

This chapter contains a reference to the public functions of the LDAP SDK for C. Along with a detailed description of each function, the function reference details the function header file and syntax, the function parameters, and what the function returns. In many cases an example program is included with the description.
The beginning of this chapter lists the functions in the following two formats:

"Functions (in alphabetical order)."

"Summary of Functions by Task."

Functions (in alphabetical order)

The LDAP SDK for C includes the following functions (functions that require LDAPv3 support are noted):

ber_bvfree()

ber_free()

ldap_abandon()

ldap_abandon_ext() - LDAPv3 function

ldap_add()

ldap_add_ext() - LDAPv3 function

ldap_add_ext_s() - LDAPv3 function

ldap_add_s()

ldap_build_filter()

ldap_compare()

ldap_compare_ext() - LDAPv3 function

ldap_compare_ext_s() - LDAPv3 function

ldap_compare_s()

ldap_control_free() - LDAPv3 function

ldap_controls_free() - LDAPv3 function

ldap_count_entries()

ldap_count_messages() - LDAPv3 function

ldap_count_references() - LDAPv3 function

ldap_count_values()

ldap_count_values_len()

ldap_create_filter()

ldap_create_persistentsearch_control() - LDAPv3 function

ldap_create_proxyauth_control() - LDAPv3 function

ldap_create_sort_control() - LDAPv3 function

ldap_create_sort_keylist() - LDAPv3 function

ldap_create_virtuallist_control() - LDAPv3 function

ldap_delete()

ldap_delete_ext() - LDAPv3 function

ldap_delete_ext_s() - LDAPv3 function

ldap_delete_s()

ldap_dn2ufn()

ldap_err2string()

ldap_explode_dn()

ldap_explode_rdn()

ldap_extended_operation() - LDAPv3 function

ldap_extended_operation_s() - LDAPv3 function

ldap_first_attribute()

ldap_first_entry()

ldap_first_message() - LDAPv3 function

ldap_first_reference() - LDAPv3 function

ldap_free_friendlymap()

ldap_free_sort_keylist()

ldap_free_urldesc()

ldap_friendly_name()

ldap_get_dn()

ldap_get_entry_controls() - LDAPv3 function

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() - LDAPv3 function

ldap_modify_ext_s() - LDAPv3 function

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() - LDAPv3 function

ldap_next_reference() - LDAPv3 function

ldap_parse_entrychange_control() - LDAPv3 function

ldap_parse_extended_result() - LDAPv3 function

ldap_parse_reference() - LDAPv3 function

ldap_parse_result() - LDAPv3 function

ldap_parse_sasl_bind_result() - LDAPv3 function

ldap_parse_sort_control() - LDAPv3 function

ldap_parse_virtuallist_control() - LDAPv3 function

ldap_perror()

ldap_rename() - LDAPv3 function

ldap_rename_s() - LDAPv3 function

ldap_result()

ldap_result2error()

ldap_sasl_bind() - LDAPv3 function

ldap_sasl_bind_s() - LDAPv3 function

ldap_search()

ldap_search_ext() - LDAPv3 function

ldap_search_ext_s() - LDAPv3 function

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()

Summary of Functions by Task

This section summarizes the functions in the LDAP SDK for C into the following task categories:

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

Initializing and Ending LDAP Sessions

Call the following functions to initialize a session, set session options, and end a session.

Table 18-1    Functions to initialize and end an LDAP session

Function

Description

ldap_init()

Initialize an LDAP session.

ldapssl_init()

Initialize an LDAP session over SSL.

ldapssl_pkcs_init()

Initialize a thread-safe session over SSL.

ldap_set_option()

Set session preferences.

ldap_get_option()

Get session preferences.

ldap_unbind(), ldap_unbind_s(), or ldap_unbind_ext()

End an LDAP session.

Authenticating to an LDAP Server

Call the following functions to authenticate to an LDAP server.

Table 18-2    Functions to authenticate to an LDAP server

Function

Description

ldap_simple_bind() or ldap_simple_bind_s()

Authenticate to an LDAP server using a password.

ldap_sasl_bind() and ldap_parse_sasl_bind_result(), or ldap_sasl_bind_s()

Authenticate to an LDAP server using a SASL mechanism.

ldap_set_rebind_proc()

Specify the function used to get authentication information when following referrals.

Performing LDAP Operations

Call the following functions to perform LDAP operations on a server.

Table 18-3    Functions to perform operations on an LDAP server

Function

Description

ldap_add_ext() or
ldap_add_ext_s()

Add a new entry to the directory.

ldap_modify_ext() or ldap_modify_ext_s()

Modify an entry in the directory.

ldap_delete_ext() or ldap_delete_ext_s()

Delete an entry from the directory.

ldap_rename() or
ldap_rename_s()

Rename an entry in the directory.

ldap_search_ext() or ldap_search_ext_s()

Search the directory.

ldap_compare_ext() or ldap_compare_ext_s()

Compare entries in the directory.

ldap_extended_operation() or ldap_extended_operation_s()

Perform an LDAPv3 extended operation.

ldap_result()

Check the results of an asynchronous operation.

ldap_parse_extended_result()

Parse the results of an LDAPv3 extended operation.

ldap_msgfree()

Free the results from memory.

ldap_abandon_ext()

Cancel an asynchronous operation.

Getting Search Results

Call the following functions to retrieve search results.

Table 18-4    Functions to search entries on an LDAP server

Function

Description

ldap_first_message()

Get the first message (an entry or search reference) in a chain of search results.

ldap_next_message()

Get the next message (an entry or search reference) in a chain of search results.

ldap_count_messages()

Count the number of messages (entries and search references) in a chain of search results.

ldap_first_entry()

Get the first entry in a chain of search results.

ldap_next_entry()

Get the next entry in a chain of search results.

ldap_count_entries()

Count the number of entries in a chain of search results.

ldap_first_reference()

Get the first search reference in a chain of search results.

ldap_next_reference()

Get the next search reference in a chain of search results.

ldap_count_references()

Count the number of search references in a chain of search results.

ldap_get_dn()

Get the distinguished name for an entry.

ldap_first_attribute()

Get the name of the first attribute in an entry.

ldap_next_attribute()

Get the name of the next attribute in an entry.

ldap_get_values()

Get the string values of an attribute.

ldap_get_values_len()

Get the binary values of an attribute.

ldap_count_values()

Count the string values of an attribute.

ldap_count_values_len()

Count the binary values of an attribute.

ldap_get_lang_values()

Get the string values of the specified language subtype of an attribute.

ldap_get_lang_values_len()

Get the binary values of the specified language subtype of an attribute.

ldap_value_free()

Free the memory allocated for the string values of an attribute.

ldap_value_free_len()

Free the memory allocated for the binary values of an attribute.

Sorting Search Results

Call the following functions to sort search results.

Table 18-5    Functions that sort search results

Function

Description

ldap_sort_entries()

Have your client sort entries by distinguished name or by a single attribute.

ldap_multisort_entries()

Have your client sort entries by multiple attributes.

ldap_create_sort_keylist(), ldap_create_sort_control(), ldap_parse_sort_control()

Request that the server sort the search results before sending them to your client.

ldap_sort_values()

Sort the values of an attribute

ldap_sort_strcasecmp()

A case-insensitive comparison function that you can pass to ldap_sort_values().

Working with Search Filters

Call the following functions to initialize, retrieve, and build filters.

Table 18-6    Functions to initialize, retrieve, and build filters

Function

Description

ldap_init_getfilter()

Read a filter configuration file into memory.

ldap_init_getfilter_buf()

Read a filter configuration from a buffer.

ldap_set_filter_additions()

Specify the prefix and suffix to be added to all filters retrieved from the filter configuration.

ldap_getfirstfilter()

Retrieve the first matching filter from the filter configuration.

ldap_getnextfilter()

Retrieve the next matching filter from the filter configuration.

ldap_getfilter_free()

Free the filter configuration from memory.

ldap_create_filter()

Build a filter.

Working with Distinguished Names

Call the following functions to retrieve a distinguished name from an entry and to split a distinguished name into its component parts.

Table 18-7    Functions to retrieve distinguished names

Function

Description

ldap_get_dn()

Get the distinguished name for an entry.

ldap_explode_dn()

Split up a distinguished name into its components.

ldap_explode_rdn()

Split up a relative distinguished name into its components.

Working with LDAPv3 Controls

Call the following functions to work with LDAPv3 controls.

Table 18-8    Functions to work with LDAPv3 controls

Function

Description

ldap_create_persistentsearch_control()

Create a "persistent search" control to track changes in directory entries.

ldap_create_sort_keylist(), ldap_create_sort_control()

Create a "sorting" control to return sorted search results from the LDAP server.

ldap_create_proxyauth_control()

Create a "proxy authorization" control to allow an entry to act as a proxy for an alternate entry.

ldap_add_ext(), ldap_add_ext_s(), ldap_compare_ext(), ldap_compare_ext_s(), ldap_delete_ext(), ldap_delete_ext_s(), ldap_extended_operation(), ldap_extended_operation_s(), ldap_modify_ext(), ldap_modify_ext_s(), ldap_rename(), ldap_rename_s(), ldap_sasl_bind(), ldap_sasl_bind_s(), ldap_search_ext(), ldap_search_ext_s(), ldap_abandon_ext()

Pass LDAP controls to the server.

ldap_parse_result()

Parse LDAP server controls from results sent from the server.

ldap_get_entry_controls(), ldap_parse_entrychange_control()

Parse an "entry change notification" control from an entry and retrieve information from the control.

ldap_parse_sort_control()

Parse "sorting" controls from results sent from the server.

ldap_control_free()

Free the memory allocated for an LDAPControl structure.

ldap_controls_free()

Free the memory allocated for an array of LDAPControl structures.

ldap_unbind_ext()

Lets you specifically name a server or client control when unbinding from the server.

Working with LDAP URLs

Call the following functions to interpret LDAP URLs.

Table 18-9    Functions to interpret LDAP URLs

Function

Description

ldap_is_ldap_url()

Determine if a URL is an LDAP URL.

ldap_url_parse()

Split up an LDAP URL into its components.

ldap_url_search(), ldap_url_search_s(), or ldap_url_search_st()

Perform the search specified by an LDAP URL.

ldap_free_urldesc()

Free the memory allocated for a parsed URL.

Getting the Attribute Values for a Particular Language

Call the following functions to get the values from a particular language subtype in an attribute.

Table 18-10    Functions to get language subtypes

Function

Description

ldap_get_lang_values() or ldap_get_lang_values_len()

Get an attribute's value in a particular language.

Handling Errors

Call the following functions to handle errors returned by the LDAP API functions.

Table 18-11    Functions for error handling

Function

Description

ldap_parse_result()

Get the error code resulting from an asynchronous LDAP operation.

ldap_get_lderrno()

Get information about the last error that occurred.

ldap_set_lderrno()

Set information about an error.

ldap_err2string()

Get the error message for a specific error code.

ldapssl_err2string()

Get the error message for a specific SSL error code.

Freeing Memory

Call the following functions to free memory allocated by the LDAP API functions.

Table 18-12    Functions to free memory

Function

Description

ldap_memfree()

Free memory allocated by an LDAP API function call.

ldap_mods_free()

Free the structures allocated for adding or modifying entries in the directory.

ldap_msgfree()

Free the memory allocated for search results or other LDAP operation results.

ldap_value_free()

Free the memory allocated for the string values of an attribute.

ldap_value_free_len()

Free the memory allocated for the binary values of an attribute (an array of berval structures).

ber_bvfree()

Free the memory allocated for a berval structures.

ldap_getfilter_free()

Free the filter configuration from memory.

ldap_free_urldesc()

Free the memory allocated for a parsed URL.

ber_free()

Free the memory allocated for a BerElement structure.

ldap_control_free()

Free the memory allocated for an LDAPControl structure

ldap_controls_free()

Free the memory allocated for an array of LDAPControl structures.

ldap_free_sort_keylist()

Free the memory allocated for an array of LDAPsortkey structures.

ber_bvfree()
Frees a berval structure from memory.

Syntax
#include <lber.h>
void ber_bvfree( struct berval *bv );

Parameters
This function has the following parameters:

Table 18-13    ber_bvfree() function parameters

bv

Pointer to the berval structure that you want to free from memory.

Description
The ber_bvfree() function frees a berval structure from memory. Call this function to free berval arguments passed back from the ldap_extended_operation_s(), ldap_parse_extended_result(), ldap_sasl_bind_s(), and ldap_parse_sasl_bind_result() functions.

See Also
ldap_extended_operation_s(), ldap_parse_extended_result(), ldap_sasl_bind_s(), ldap_parse_sasl_bind_result().

ber_free()
The ber_free() function frees a BerElement structure from memory. Call this function to free any BerElement structures that you have allocated.

Syntax
#include <ldap.h>
void ber_free( BerElement *ber, int freebuf );

Parameters
This function has the following parameters:

Table 18-14    ber_free() function parameters

ber

Pointer to the BerElement structure that you want to free.

freebuf

Specifies whether or not to free the buffer in the BerElement structure.

Description
You can call this function to free BerElement structures allocated by ldap_first_attribute() function calls and by ldap_next_attribute() function calls.
When freeing structures allocated by these functions, you should specify 0 for the freebuf argument. (These functions do not allocate the extra buffer in the BerElement structure.)
For example, to retrieve attributes from a search result entry, you need to call the ldap_first_attribute() function. Calling this function allocates a BerElement structure, which is used to keep track of the current attribute. When you are done working with the attributes, you should free this structure from memory if the structure still exists.

Example
The following example frees the BerElement structure allocated by the ldap_first_attribute() function.

Code Example 18-1    ber_free() code example

LDAPMessage *a, *e;

BerElement *ber;

...

for ( a = ldap_first_attribute( ld, e, &ber ); a != NULL;

  a =ldap_next_attribute( ld, e, ber ) {

  ...

  /* Retrieve the value of each attribute */

  ...

}

/* Free the BerElement when done */

if ( ber != NULL ) {

  ber_free( ber, 0 );

}

...

See Also
ldap_first_attribute(), ldap_next_attribute().

ldap_abandon()
Cancels ("abandons") an asynchronous LDAP operation that is in progress.
Note that this is an older function that is included in the LDAP API for backward-compatibility. If you are writing a new LDAP client, use ldap_abandon_ext() instead.

Syntax
#include <ldap.h>
int ldap_abandon( LDAP *ld, int msgid );

Parameters
This function has the following parameters:

Table 18-15    ldap_abandon() function parameters

ld

Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.

msgid

Message ID of an LDAP operation.

Returns
One of the following values:

LDAP_SUCCESS if successful.

-1 if unsuccessful. The appropriate LDAP error code is also set in the LDAP structure. You can retrieve the error code by calling the ldap_get_lderrno() function.

Some of the possible LDAP result codes for this function include:

LDAP_PARAM_ERROR (if any of the arguments are invalid).

LDAP_ENCODING_ERROR (if an error occurred when BER-encoding the request).

LDAP_SERVER_DOWN (if the LDAP server did not receive the request or if the connection to the server was lost).

LDAP_NO_MEMORY (if memory cannot be allocated).

Description
The ldap_abandon() function cancels ("abandons") an asynchronous LDAP operation that is in progress.
A newer version of this function, ldap_abandon_ext(), is available in this release of the LDAP API. ldap_abandon() (the older version of the function) is included only for backward-compatibility. If you are writing a new LDAP client, use ldap_abandon_ext() instead of ldap_abandon().
If you want more information on ldap_abandon(), refer to the LDAP C SDK 1.0 Programmer's Guide.

Example
The following example cancels an ldap_url_search() operation, abandoning the results of the operation.

Code Example 18-2    Canceling an ldap_url_search() operation

LDAP *ld;

char *url = "ldap://ldap.itd.umich.edu/c=US?o,description? one?o=umich";

int msgid;

...

/* Initiate a search operation */

msgid = ldap_url_search( ld, url, 0 );

...

/* Abandon the search operation */

if ( ldap_abandon( ld, msgid ) != LDAP_SUCCESS ) {

  ldap_perror( ld, "ldap_abandon" );

  return( 1 );

}

...

See Also
ldap_abandon_ext().

ldap_abandon_ext()
Cancels ("abandons") an asynchronous LDAP operation that is in progress. For example, you can cancel an LDAP search operation that you started with ldap_search_ext().

Syntax
#include <ldap.h>
int ldap_abandon_ext( LDAP *ld, int msgid,
  LDAPControl **serverctrls, LDAPControl **clientctrls );

Parameters
This function has the following parameters:

Table 18-16    ldap_abandon_ext() function parameters

ld

Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.

msgid

Message ID of the LDAP operation that you want to cancel.

serverctrls

Pointer to an array of LDAPControl structures representing LDAP server controls that apply to this LDAP operation. If you do not want to pass any server controls, specify NULL for this argument.

clientctrls

Pointer to an array of LDAPControl structures representing LDAP client controls that apply to this LDAP operation. If you do not want to pass any client controls, specify NULL for this argument.

Returns
One of the following values:

LDAP_SUCCESS if successful.

LDAP_PARAM_ERROR if any of the arguments are invalid.

LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request.

LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.

LDAP_NO_MEMORY if memory cannot be allocated.

Description
The ldap_abandon() function cancels ("abandons") an asynchronous LDAP operation that is in progress. For example, if you called ldap_search_ext() to initiate an LDAP search operation on the server, you can call ldap_abandon_ext() to cancel the LDAP search operation.
This function is a new version of the ldap_abandon() function. If you are writing a new LDAP client, you should call this function instead of ldap_abandon().
When you call this function, your LDAP client sends a request to cancel an operation being processed by the LDAP server. To identify the operation to be cancelled, specify the message ID of the operation in the msgid argument.
(When you call an asynchronous function such as ldap_search_ext() and ldap_modify_ext(), the msgidp argument of the function returns a pointer to a message ID that identifies the operation. For example, when you call ldap_search_ext() to start an LDAP search operation on the server, the msgidp argument returns a pointer to a message ID identifying that LDAP search operation.)
When you call ldap_abandon_ext(), the function checks to see if the results of the operation have already been returned. If so, ldap_abandon_ext() deletes the message ID from the queue of pending messages. If the results have not been returned, ldap_abandon_ext() sends a request to abandon the operation on the LDAP server.
Once you cancel an operation, results of the operation will not be returned, even if you subsequently call ldap_result() to try to get the results.
For more information, see "Canceling an Operation in Progress."

Example
The following example cancels an ldap_url_search() operation, abandoning the results of the operation.

Code Example 18-3    ldap_abandon_ext() code example

char *url = "ldap://ldap.itd.umich.edu/c=US?o,description?one?o=umich";

int msgid;

LDAPControl **srvrctrls, **clntctrls;

...

/* Initiate a search operation */

msgid = ldap_url_search( ld, url, 0 );

...

/* Abandon the search operation */

if ( ldap_abandon_ext( ld, msgid, srvrctrls, clntctrls )

    != LDAP_SUCCESS ) {

  ldap_perror( ld, "ldap_abandon" );

  return( 1 );

}

...

See Also
ldap_add_ext(), ldap_compare_ext(), ldap_delete_ext(), ldap_extended_operation(), ldap_modify_ext(), ldap_rename(), ldap_sasl_bind(), ldap_search_ext(), ldap_simple_bind(), ldap_url_search().

ldap_add()
Adds a new entry to the directory asynchronously.
Note that this is an older function that is included in the LDAP API for backward-compatibility. If you are writing a new LDAP client, use ldap_add_ext() instead.

Syntax
#include <ldap.h>
int ldap_add( LDAP *ld, const char *dn, LDAPMod **attrs );

Parameters
This function has the following parameters:

Table 18-17    ldap_add() function parameters

ld

Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.

dn

Distinguished name (DN) of the entry to add. With the exception of the leftmost component, all components of the distinguished name (for example, o=organization or c=country) must already exist.

attrs

Pointer to a NULL-terminated array of pointers to LDAPMod structures representing the attributes of the new entry.

Returns
The message ID of the ldap_add() operation. To check the result of this operation, call ldap_result() and ldap_result2error(). See the result code documentation for the ldap_add_ext_s() function for a list of possible result codes for the LDAP add operation.

Description
The ldap_add() function adds a new entry to the directory asynchronously.
A newer version of this function, ldap_add_ext(), is available in this release of the LDAP API. ldap_add() (the older version of the function) is included only for backward-compatibility. If you are writing a new LDAP client, use ldap_add_ext() instead of ldap_add().
If you want more information on ldap_add(), refer to the LDAP C SDK 1.0 Programmer's Guide.

Example
The following example adds a new entry to the directory.

Code Example 18-4    ldap_add() code example

...

LDAP *ld;

LDAPMod *list_of_attrs[4];

LDAPMod attribute1, attribute2, attribute3;

LDAPMessage *result;

int msgid, rc;

struct timeval tv;

/* Distinguished name of the new entry. Note that "o=airius.com" and "ou=People, o=airius.com" must already exist in the directory. */

char *dn = "uid=bjensen, ou=People, o=airius.com";

/* To add a "person" entry, you must specify values for the sn, cn, and objectClass attributes. (These are required attributes.) */

char *sn_values[] = { "Jensen", NULL };

/* To specify multiple values for an attribute, add the different values to the array. */

char *cn_values[] = { "Barbara Jensen", "Babs Jensen", NULL };

/* The object class for a "person" entry is "inetOrgPerson", which is a subclass of "top", "person", and "organizationalPerson". You should add all of these classes as values of the objectClass attribute. */

char *objectClass_values[] = { "top", "person", "organizationalPerson", "inetOrgPerson", NULL };

...

/* Specify the value and type of each attribute in separate LDAPMod structures */

attribute1.mod_type = "sn";

attribute1.mod_values = sn_values;

attribute2.mod_type = "cn";

attribute2.mod_values = cn_values;

attribute3.mod_type = "objectClass";

attribute3.mod_values = objectClass_values;

/* Add the pointers to these LDAPMod structures to an array */

list_of_attrs[0] = &attribute1;

list_of_attrs[1] = &attribute2;

list_of_attrs[2] = &attribute3;

list_of_attrs[3] = NULL;

...

/* Set up the timeout period for adding the new entry */

tv.tv_sec = tv.tv_usec = 0;

/* Add the user "Barbara Jensen" */

if ( ( msgid = ldap_add( ld, dn, list_of_attrs ) ) == -1 ) {

  ldap_perror( ld, "ldap_add" );

  return( 1 );

}

/* Check to see if the operation has completed */

while ( ( rc = ldap_result( ld, msgid, 0, &tv, &result ) ) == 0 ) {

  ...

  /* do other work while waiting for the operation to complete */

  ...

}

/* Check the result to see if any errors occurred */

if (( rc = ldap_result2error( ld, result, 1 )) != LDAP_SUCCESS ) {

  printf( "Error while adding entry: %s\n", ldap_err2string( rc ));

}

...

See Also
ldap_add_ext().

ldap_add_ext()
Adds a new entry to the directory asynchronously.

Syntax
#include <ldap.h>
int ldap_add_ext( LDAP *ld, const char *dn, LDAPMod **attrs,
  LDAPControl **serverctrls, LDAPControl **clientctrls,
  int *msgidp );

Parameters
This function has the following parameters:

Table 18-18    ldap_add_ext() function parameters

ld

Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.

dn

Distinguished name (DN) of the entry to add. With the exception of the leftmost component, all components of the distinguished name (for example, o=organization or c=country) must already exist.

attrs

Pointer to a NULL-terminated array of pointers to LDAPMod structures representing the attributes of the new entry.

serverctrls

Pointer to an array of LDAPControl structures representing LDAP server controls that apply to this LDAP operation. If you do not want to pass any server controls, specify NULL for this argument.

clientctrls

Pointer to an array of LDAPControl structures representing LDAP client controls that apply to this LDAP operation. If you do not want to pass any client controls, specify NULL for this argument.

msgidp

Pointer to an integer that will be set to the message ID of the LDAP operation. To check the result of this operation, call ldap_result() and ldap_parse_result() functions.

Returns
One of the following values:

LDAP_SUCCESS if successful.

LDAP_PARAM_ERROR if any of the arguments are invalid.

LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request.

LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.

LDAP_NO_MEMORY if memory cannot be allocated.

LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAPv3 protocol. Make sure that you set the version of your LDAP client to version 3 before calling this function. (For details, see "Specifying the LDAP Version of Your Client.")

Description
The ldap_add_ext() adds a new entry to the directory asynchronously.
This function is a new version of the ldap_add() function. If you are writing a new LDAP client, you should call this function instead of ldap_add().
To add a new entry to the directory, you need to specify the following information:

A unique DN identifying the new entry.

Use the dn argument to specify the DN of the new entry. Note that the parents of the entry should already exist. For example, if you are adding the entry uid=bjensen, ou=People, o=airius.com, the entries ou=People, o=airius.com and o=airius.com should already exist in the directory.

A set of attributes for the new entry.

Create an LDAPMod structure for each attribute. Set the mod_op field to 0 if the attribute values are string values. To specify values that consist of binary data (such as a sound file or a JPEG file), set the mod_op field to LDAP_MOD_BVALUES.

Create an array of these LDAPMod structures and pass the array as the attrs argument.

ldap_add_ext() is an asynchronous function; it does not directly return results. If you want the results to be returned directly by the function, call the synchronous function ldap_add_ext_s() instead. (For more information on asynchronous and synchronous functions, see "Calling Synchronous and Asynchronous Functions.")
In order to get the results of the LDAP add operation, you need to call the ldap_result() function and the ldap_parse_result() function. (See "Calling Asynchronous Functions" for details.) For a list of possible result codes for an LDAP add operation, see the result code documentation for the ldap_add_ext_s() function.
For additional information on adding new entries to the directory, see "Adding a New Entry."

Example
See the example under "Example: Adding an Entry to the Directory (Asynchronous)."

See Also
ldap_add_ext_s(), ldap_result(), ldap_parse_result(), LDAPMod.

ldap_add_ext_s()
Adds a new entry to the directory synchronously.

Syntax
#include <ldap.h>
int ldap_add_ext_s( LDAP *ld, const char *dn, LDAPMod **attrs,
  LDAPControl **serverctrls, LDAPControl **clientctrls );

Parameters
This function has the following parameters:

Table 18-19    ldap_add_ext_s() function parameters

ld

Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.

dn

Distinguished name (DN) of the entry to add. With the exception of the leftmost component, all components of the distinguished name (for example, o=organization or c=country) must already exist.

attrs

Pointer to a NULL-terminated array of pointers to LDAPMod structures representing the attributes of the new entry.

serverctrls

Pointer to an array of LDAPControl structures representing LDAP server controls that apply to this LDAP operation. If you do not want to pass any server controls, specify NULL for this argument.

clientctrls

Pointer to an array of LDAPControl structures representing LDAP client controls that apply to this LDAP operation. If you do not want to pass any client controls, specify NULL for this argument.

Returns
One of the following values:

LDAP_SUCCESS if successful.

LDAP_PARAM_ERROR if any of the arguments are invalid.

LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request.

LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.

LDAP_NO_MEMORY if memory cannot be allocated.

LDAP_LOCAL_ERROR if an error occurred when receiving the results from the server.

LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded results from the server.

LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAPv3 protocol. Make sure that you set the version of your LDAP client to version 3 before calling this function. (For details, see "Specifying the LDAP Version of Your Client.")
The following result codes can be returned by the Netscape Directory Server when processing an LDAP add request. Other LDAP servers may send these result codes under different circumstances or may send different result codes back to your LDAP client.

LDAP_OPERATIONS_ERROR may be sent by the Netscape Directory Server for general errors encountered by the server when processing the request.

LDAP_PROTOCOL_ERROR if the add request sent by this function did not comply with the LDAP protocol (for example, if the server encountered an error when decoding your client's BER-encoded request).

LDAP_CONSTRAINT_VIOLATION may be sent by the Netscape Directory Server if the server is configured to require a minimum password length and the new entry includes a value for the userpassword attribute that is shorter than the minimum length.

The server may also send this result code if the value of the userpassword attribute is the same as the value of the uid, cn, sn, givenname, ou, or mail attributes. (Using a password that is the same as your user id or email address would make the password trivial and easy to crack.)

LDAP_TYPE_OR_VALUE_EXISTS may be sent by the Netscape Directory Server if the set of attributes specified by the attrs argument includes duplicate attribute values.

LDAP_INVALID_DN_SYNTAX may be sent by the Netscape Directory Server if the DN specified by the dn argument is not a valid DN.

LDAP_ALREADY_EXISTS may be sent by the Netscape Directory Server if the DN specified by the dn argument identifies an entry already in the directory.

LDAP_OBJECT_CLASS_VIOLATION may be sent by the Netscape Directory Server if the new entry does not comply with the Directory Server schema (for example, if one or more required attributes are not specified).

LDAP_NO_SUCH_OBJECT may be sent by the Netscape Directory Server if the parent of the entry does not exist and if you are not authenticated as the root DN (for example, if you attempt to add uid=bjensen, ou=People, o=airius.com and if ou=People, o=airius.com does not exist).

This result code may also be sent if the DN of the new entry has a suffix that is not handled by the current server and no referral URLs are available.

LDAP_REFERRAL may be sent by the Netscape Directory Server if the DN specified by the dn argument identifies an entry not handled by the current server and if referral URLs identify a different server to handle the entry. (For example, if the DN is uid=bjensen, ou=European Sales, o=airius.com, all entries under ou=European Sales might be handled by a different Directory Server.)

LDAP_UNWILLING_TO_PERFORM may be sent by the Netscape Directory Server if the server's database is set up to not allow write operations to the database (the database is read-only).

LDAP_INVALID_SYNTAX may be sent by the Netscape Directory Server if the entry or the entry's parent has an invalid ACL.

LDAP_INSUFFICIENT_ACCESS may be sent by the Netscape Directory Server in the following situations:

The ACL for the entry's parent does not allow you to add the entry.

The entry's parent has no ACL.

The entry has no parent and your client is not authenticated as the root DN.

Note that the Directory Server may send other result codes in addition to the codes described here (for example, the server may have loaded a custom plug-in that returns other result codes).

Description
The ldap_add_ext_s() function adds a new entry to the directory synchronously.
This function is a new version of the ldap_add_s() function. If you are writing a new LDAP client, you should call this function instead of ldap_add_s().
To add a new entry to the directory, you need to specify the following information:

A unique DN identifying the new entry.

Use the dn argument to specify the DN of the new entry. Note that the parents of the entry should already exist. For example, if you are adding the entry uid=bjensen, ou=People, o=airius.com, the entries ou=People, o=airius.com and o=airius.com should already exist in the directory.

A set of attributes for the new entry.

Create an LDAPMod structure for each attribute. Set the mod_op field to 0 if the attribute values are string values. To specify values that consist of binary data (such as a sound file or a JPEG file), set the mod_op field to LDAP_MOD_BVALUES.

Create an array of these LDAPMod structures and pass the array as the attrs argument.

ldap_add_ext_s() is a synchronous function, which directly returns the results of the operation. If you want to perform other operations while waiting for the results of this operation, call the asynchronous function ldap_add_ext() instead. (For more information on asynchronous and synchronous functions, see "Calling Synchronous and Asynchronous Functions.")
For additional information on adding new entries to the directory, see "Adding a New Entry."

Example
See the example under "Example: Adding an Entry to the Directory (Synchronous)."

See Also
ldap_add_ext(), LDAPMod.

ldap_add_s()
Adds a new entry to the directory synchronously.
Note that this is an older function that is included in the LDAP API for backward-compatibility. If you are writing a new LDAP client, use ldap_add_ext_s() instead.

Syntax
#include <ldap.h>
int ldap_add_s( LDAP *ld, const char *dn, LDAPMod **attrs );

Parameters
This function has the following parameters:

Table 18-20    ldap_add_s() function parameters

ld

Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.

dn

Distinguished name (DN) of the entry to add. With the exception of the leftmost component, all components of the distinguished name (for example, o=organization or c=country) must already exist.

attrs

Pointer to a NULL-terminated array of pointers to LDAPMod structures representing the attributes of the new entry.

Returns
See the result code documentation for the ldap_add_ext_s() function for a list of possible return codes for the LDAP add operation.

Description
The ldap_add_s() function adds a new entry to the directory synchronously.
A newer version of this function, ldap_add_ext_s(), is available in this release of the LDAP API. ldap_add_s() (the older version of the function) is included only for backward-compatibility. If you are writing a new LDAP client, use ldap_add_ext_s() instead of ldap_add_s().
If you want more information on ldap_add_s(), refer to the LDAP C SDK 1.0 Programmer's Guide.

Example
The following example adds a new entry to the directory.

Code Example 18-5    ldap_add_s code example

...

LDAP *ld;

LDAPMod *list_of_attrs[4];

LDAPMod attribute1, attribute2, attribute3;

/* Distinguished name of the new entry. Note that "o=airius.com" and "ou=People, o=airius.com" must already exist in the directory. */

char *dn = "uid=bjensen, ou=People, o=airius.com";

/* To add a "person" entry, you must specify values for the sn, cn, and objectClass attributes. (These are required attributes.) */

char *sn_values[] = { "Jensen", NULL };

/* To specify multiple values for an attribute, add the different values to the array. */

char *cn_values[] = { "Barbara Jensen", "Babs Jensen", NULL };

/* The object class for a "person" entry is "inetOrgPerson", which is a subclass of "top", "person", and "organizationalPerson". You should add all of these classes as values of the objectClass attribute. */

char *objectClass_values[] = { "top", "person", "organizationalPerson", "inetOrgPerson", NULL };

...

/* Specify the value and type of each attribute in separate LDAPMod structures */

attribute1.mod_type = "sn";

attribute1.mod_values = sn_values;

attribute2.mod_type = "cn";

attribute2.mod_values = cn_values;

attribute3.mod_type = "objectClass";

attribute3.mod_values = objectClass_values;

/* Add the pointers to these LDAPMod structures to an array */

list_of_attrs[0] = &attribute1;

list_of_attrs[1] = &attribute2;

list_of_attrs[2] = &attribute3;

list_of_attrs[3] = NULL;

...

/* Add the user "Barbara Jensen" */

if ( ldap_add_s( ld, dn, list_of_attrs ) != LDAP_SUCCESS ) {

  ldap_perror( ld, "ldap_add_s" );

  return( 1 );

}

...

See Also
ldap_add_ext_s().

ldap_ber_free()
This function is documented here only for backward compatibility; you should use the ber_free() function in its place since this function will be phased out over time. Except in name, the function ldap_ber_free() is idendical to ber_free().

Syntax
#include <ldap.h>
void ldap_ber_free( BerElement *ber, int freebuf );

Parameters
This function has the following parameters:

Table 18-21    ldap_ber_free() function parameters

ber

Pointer to the BerElement structure that you want to free.

freebuf

Specifies whether or not to free the buffer in the BerElement structure.

ldap_build_filter()
The ldap_build_filter() function is a deprecated function. Use the ldap_create_filter() function instead.

ldap_compare()
Asynchronously determines if an attribute of an entry contains a specified value.
Note that this is an older function that is included in the LDAP API for backward-compatibility. If you are writing a new LDAP client, use ldap_compare_ext() instead.

Syntax
#include <ldap.h>
int ldap_compare( LDAP *ld, const char *dn, const char *attr,
  const char *value );

Parameters
This function has the following parameters:

Table 18-22    ldap_compare() function parameters

ld

Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.

dn

Distinguished name (DN) of the entry used in the comparison.

attr

Attribute type that you want to check the value against.

value

Value that you want to compare against the attribute values.

Returns
Returns the message ID of the ldap_compare() operation. To check the result of this operation, call ldap_result() and ldap_result2error(). For a list of possible return codes for the LDAP compare operation, see the result code documentation for the ldap_compare_ext_s() function.

Description
The ldap_compare() function compares a value with the value of an attribute in an entry.
A newer version of this function, ldap_compare_ext(), is available in this release of the LDAP API. ldap_compare() (the older version of the function) is included only for backward-compatibility. If you are writing a new LDAP client, use ldap_compare_ext() instead of ldap_compare().
If you want more information on ldap_compare(), refer to the LDAP C SDK 1.0 Programmer's Guide.

Example
The following section of code checks to see if Barbara Jensen has the e-mail address "bjensen@airius.com".

Code Example 18-6    Using ldap_compare()

#include <stdio.h>

#include <ldap.h>

...

LDAP *ld;

char *dn = "uid=bjensen, ou=People, o=airius.com";

int msgid;

...

msg_id = ldap_compare( ld, dn, "mail", "bjensen@airius.com" );

...

See Also
ldap_compare_ext().

ldap_compare_ext()
Asynchronously determines if an attribute of an entry contains a specified value.

Syntax
#include <ldap.h>
int ldap_compare_ext( LDAP *ld, const char *dn,
  const char *attr, struct berval *bvalue,
  LDAPControl **serverctrls, LDAPControl **clientctrls,
  int *msgidp );

Parameters
This function has the following parameters:

Table 18-23    ldap_compare_ext() function parameters

ld

Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.

dn

Distinguished name (DN) of the entry used in the comparison.

attr

Attribute type that you want to check the value against.

value

Value that you want to compare against the attribute values.

serverctrls

Pointer to an array of LDAPControl structures representing LDAP server controls that apply to this LDAP operation. If you do not want to pass any server controls, specify NULL for this argument.

clientctrls

Pointer to an array of LDAPControl structures representing LDAP client controls that apply to this LDAP operation. If you do not want to pass any client controls, specify NULL for this argument.

msgidp

Pointer to an integer that will be set to the message ID of the LDAP operation. To check the result of this operation, call the ldap_result() and ldap_parse_result() functions.

Returns
One of the following values:

LDAP_SUCCESS if successful.

LDAP_PARAM_ERROR if any of the arguments are invalid.

LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request.

LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.

LDAP_NO_MEMORY if memory cannot be allocated.

LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAPv3 protocol. Make sure that you set the version of your LDAP client to version 3 before calling this function. (For details, see "Specifying the LDAP Version of Your Client.")

Description
The ldap_compare_ext() function asynchronously compares the value of an attribute in an entry against a specified value.
This function is a new version of the ldap_compare() function. If you are writing a new LDAP client, you should call this function instead of ldap_compare().
ldap_compare_ext() is an asynchronous function; it does not directly return results. If you want the results to be returned directly by the function, call the synchronous function ldap_compare_ext_s() instead. (For more information on asynchronous and synchronous functions, see "Calling Synchronous and Asynchronous Functions.")
In order to get the results of the LDAP compare operation, you need to call the ldap_result() function and the ldap_parse_result() function. (See "Calling Asynchronous Functions" for details.) For a list of possible result codes for an LDAP compare operation, see the result code documentation for the ldap_compare_ext_s() function.
For additional information on comparing attribute values in an entry, see "Comparing the Value of an Attribute."

Example
See the example under "Example: Comparing a Value in an Entry (Asynchronous)."

See Also
ldap_compare_ext_s(), ldap_result(), ldap_parse_result().

ldap_compare_ext_s()
Synchronously determines if an attribute of an entry contains a specified value.

Syntax
#include <ldap.h>
int ldap_compare_ext_s( LDAP *ld, const char *dn,
  const char *attr, struct berval *bvalue,
  LDAPControl **serverctrls, LDAPControl **clientctrls );

Parameters
This function has the following parameters:

Table 18-24    ldap_compare_ext_s() function parameters

ld

Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.

dn

Distinguished name (DN) of the entry used in the comparison.

attr

Attribute type that you want to check the value against.

value

Value that you want to compare against the attribute values.

serverctrls

Pointer to an array of LDAPControl structures representing LDAP server controls that apply to this LDAP operation. If you do not want to pass any server controls, specify NULL for this argument.

clientctrls

Pointer to an array of LDAPControl structures representing LDAP client controls that apply to this LDAP operation. If you do not want to pass any client controls, specify NULL for this argument.

Returns
One of the following values:

LDAP_COMPARE_TRUE if the entry contains the attribute value.

LDAP_COMPARE_FALSE if the entry does not contain the attribute value.

LDAP_PARAM_ERROR if any of the arguments are invalid.

LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request.

LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.

LDAP_NO_MEMORY if memory cannot be allocated.

LDAP_LOCAL_ERROR if an error occurred when receiving the results from the server.

LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded results from the server.

LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAPv3 protocol. Make sure that you set the version of your LDAP client to version 3 before calling this function. (For details, see "Specifying the LDAP Version of Your Client.")
The following result codes can be returned by the Netscape Directory Server when processing an LDAP compare request. Other LDAP servers may send these result codes under different circumstances or may send different result codes back to your LDAP client.

LDAP_OPERATIONS_ERROR may be sent by the Netscape Directory Server for general errors encountered by the server when processing the request.

LDAP_PROTOCOL_ERROR if the compare request sent by this function did not comply with the LDAP protocol (for example, if the server encountered an error when decoding your client's BER-encoded request).

LDAP_NO_SUCH_OBJECT may be sent by the Netscape Directory Server if the specified entry has a suffix that is not handled by the current server and no referral URLs are available.

LDAP_REFERRAL may be sent by the Netscape Directory Server if the DN specified by the dn argument identifies an entry not handled by the current server and if referral URLs identify a different server to handle the entry. (For example, if the DN is uid=bjensen, ou=European Sales, o=airius.com, all entries under ou=European Sales might be handled by a different Directory Server.)

LDAP_INSUFFICIENT_ACCESS may be sent by the Netscape Directory Server if your client does not have the access right to compare this entry.

LDAP_INVALID_SYNTAX may be sent by the Netscape Directory Server if the entry or the entry's parent has an invalid ACL.

LDAP_NO_SUCH_ATTRIBUTE may be sent by the Netscape Directory Server if the entry does not contain the attribute specified by the attr argument.
Note that the Netscape Directory Server may send other result codes in addition to the codes described here (for example, the server may have loaded a custom plug-in that returns other result codes).

Description
The ldap_compare_ext_s() function synchronously compares the value of an attribute in an entry against a specified value.
This function is a new version of the ldap_compare_s() function. If you are writing a new LDAP client, you should call this function instead of ldap_compare_s().
ldap_compare_ext_s() is a synchronous function, which directly returns the results of the operation. If you want to perform other operations while waiting for the results of this operation, call the asynchronous function ldap_compare_ext() instead. (For more information on asynchronous and synchronous functions, see "Calling Synchronous and Asynchronous Functions.")
For additional information on comparing attribute values in an entry, see "Comparing the Value of an Attribute."

Example
See the example under "Example: Comparing a Value in an Entry (Synchronous)."

See Also
ldap_compare_ext().

ldap_compare_s()
Synchronously determines if an attribute of an entry contains a specified value.
Note that this is an older function that is included in the LDAP API for backward-compatibility. If you are writing a new LDAP client, use ldap_compare_ext_s() instead.

Syntax
#include <ldap.h>
int ldap_compare_s( LDAP *ld, const char *dn,
  const char *attr, const char *value );

Parameters
This function has the following parameters:

Table 18-25    ldap_compare_s() function parameters

ld

Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.

dn

Distinguished name (DN) of the entry used in the comparison.

attr

Attribute type that you want to check the value against.

value

Value that you want to compare against the attribute values.

Returns
For a list of the possible result codes for an LDAP compare operation, see the result code documentation for the ldap_compare_ext_s() function.

Description
The ldap_compare_s() function compares a value with the value of an attribute in an entry.
A newer version of this function, ldap_compare_ext_s(), is available in this release of the LDAP API. ldap_compare_s() (the older version of the function) is included only for backward-compatibility. If you are writing a new LDAP client, use ldap_compare_ext_s() instead of ldap_compare_s().
If you want more information on ldap_compare_s(), refer to the LDAP C SDK 1.0 Programmer's Guide.

Example
The following section of code checks to see if Barbara Jensen has the e-mail address "bjensen@airius.com".

Code Example 18-7    ldap_compare_s() code example

#include <ldap.h>

LDAP *ld;

char *dn = "uid=bjensen, ou=People, o=airius.com";

int has_value;

...

has_value = ldap_compare_s( ld, dn, "mail", "bjensen@airius.com" );

switch ( has_value ) {

  case LDAP_COMPARE_TRUE:

    printf( "The mail attribute contains bjensen@airius.com.\n");

    break;

  case LDAP_COMPARE_FALSE:

    printf( "The mail attribute does not contain bjensen@airius.com.\n");

    break;

  default:

    ldap_perror( ld, "ldap_compare_s" );

    return( 1 );

}

...

See Also
ldap_compare_ext_s().

ldap_control_free()
Frees an LDAPControl structure from memory.

Syntax
#include <ldap.h>
void ldap_control_free( LDAPControl *ctrl );

Parameters
This function has the following parameters:

Table 18-26    ldap_control_free() function parameters

ctrl

Pointer to an LDAPControl structure that you want to free from memory.

Description
The ldap_control_free() function frees an LDAPControl structure from memory.
You should call this function to free controls that you create (for example, if you call the ldap_create_sort_control() function).

See Also
ldap_controls_free().

ldap_controls_free()
Frees an array of LDAPControl structures from memory.

Syntax
#include <ldap.h>
void ldap_controls_free( LDAPControl **ctrls );

Parameters
This function has the following parameters:

Table 18-27    ldap_controls_free() function parameters

ctrls

Pointer to an array of LDAPControl structures that you want to free from memory.

Description
The ldap_controls_free() function frees an array of LDAPControl structures from memory.
You should call this function to free arrays of controls that you create or any arrays returned by ldap_parse_result().

See Also
ldap_control_free().

ldap_count_entries()
Returns the number of LDAPMessage structures representing directory entries in a chain of search results.

Syntax
#include <ldap.h>
int ldap_count_entries( LDAP *ld, LDAPMessage *result );

Parameters
This function has the following parameters:

Table 18-28    ldap_count_entries() function parameters

ld

Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.

result

Chain of search results, represented by the pointer to an LDAPMessage structure.

Returns
One of the following values:

The number of LDAPMessage structures of the type LDAP_RES_SEARCH_ENTRY in a chain of search results, if successful. (If there are no structures of this type, returns 0.)

-1 if ld is not a valid connection handle.

Description
The ldap_count_entries() function returns the number of LDAPMessage structures representing directory entries in a chain of search results. These messages have the type LDAP_RES_SEARCH_ENTRY.
Note that if you pass in a pointer to an LDAPMessage structure in the middle of the chain of results, the function counts only the entries between that structure and the last structure in the chain. In this type of situation, the function does not return the count of all entries in the chain.
For more information on using this function, see "Iterating Through a Chain of Results."

Example
See the examples under ldap_search_ext() and ldap_search_ext_s().

See Also
ldap_result(), ldap_search_ext(), ldap_search_ext_s(), ldap_first_entry(), ldap_next_entry(), ldap_first_message(), ldap_next_message().

ldap_count_messages()
Returns the number of LDAPMessage structures in a chain of search results.

Syntax
#include <ldap.h>
int ldap_count_messages( LDAP *ld, LDAPMessage *res );

Parameters
This function has the following parameters:

Table 18-29    ldap_count_messages() function parameters

ld

Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.

result

Chain of search results, represented by the pointer to an LDAPMessage structure.

Returns
One of the following values:

The number of LDAPMessage structures in a chain of search results, if successful. (If there are no structures, returns 0.)

-1 if ld is not a valid connection handle.

Description
The ldap_count_messages() function returns the number of LDAPMessage structures in a chain of search results.
Note that if you pass in a pointer to an LDAPMessage structure in the middle of the chain of results, the function counts only between that structure and the last structure in the chain. In this type of situation, the function does not return the count of all structures in the chain.
For more information on using this function, see "Iterating Through a Chain of Results."

Example
See the examples under ldap_search_ext() and ldap_search_ext_s().

See Also
ldap_result(), ldap_search_ext(), ldap_search_ext_s(), ldap_first_message(), ldap_next_message().

ldap_count_references()
Returns the number of LDAPMessage structures representing search references in a chain of search results.

Syntax
#include <ldap.h>
int ldap_count_references( LDAP *ld, LDAPMessage *res );

Parameters
This function has the following parameters:

Table 18-30    ldap_count_references() function parameters

ld

Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.

result

Chain of search results, represented by the pointer to an LDAPMessage structure.

Returns
One of the following values:

The number of LDAPMessage structures of the type LDAP_RES_SEARCH_REFERENCE in a chain of search results, if successful. (If there are no structures of this type, returns 0.)

-1 if ld is not a valid connection handle.

Description
The ldap_count_references() function returns the number of LDAPMessage structures representing search references in a chain of search results. These messages have the type LDAP_RES_SEARCH_REFERENCE.
Note that if you pass in a pointer to an LDAPMessage structure in the middle of the chain of results, the function counts only the references between that structure and the last structure in the chain. In this type of situation, the function does not return the count of all references in the chain.
For more information on using this function, see "Iterating Through a Chain of Results."

Example
See the examples under ldap_search_ext() and ldap_search_ext_s().

See Also
ldap_result(), ldap_search_ext(), ldap_search_ext_s(), ldap_first_reference(), ldap_next_reference().

ldap_count_values()
The ldap_count_values() function returns the number of values in an array of strings. Use the ldap_count_values_len() function instead of this function if the array contains berval structures.
For additional information, see "Getting the Values of an Attribute."

Syntax
#include <ldap.h>
int ldap_count_values( char **values );

Parameters
This function has the following parameters:

Table 18-31    ldap_count_values() function parameters

values

Array of values.

Returns
One of the following values:

The number of values in the array, if successful.

-1 if unsuccessful. (See Chapter 19 "Result Codes" for a complete listing.)

Example
The following section of code counts the number of values assigned to an attribute.

Code Example 18-8    ldap_count_values() code example

#include <ldap.h>

...

LDAP *ld;

LDAPMessage *e;

char *a="cn";

char **vals;

int count;

...

/* Get the values of the cn attribute */

vals = ldap_get_values( ld, e, a );

/* Count the values of the attribute */

count = ldap_count_values( vals );

...

See Also
ldap_count_values_len(), ldap_get_values().

ldap_count_values_len()
The ldap_count_values_len() function returns the number of values in an array of berval structures. Use the ldap_count_values() function instead of this function if the array contains strings.
For additional information, see "Getting the Values of an Attribute."

Syntax
#include <ldap.h>
int ldap_count_values_len( struct berval **vals );

Parameters
This function has the following parameters:

Table 18-32    ldap_count_values_len() function parameters

values

Array of berval structures.

Returns
One of the following values:

The number of values in the array, if successful.

-1 if unsuccessful. (See Chapter 19 "Result Codes" for a complete listing.)

Example
The following section of code counts the number of values assigned to an attribute.

Code Example 18-9    ldap_count_values_len() code example

#include <ldap.h>

LDAP *ld;

LDAPMessage *e;

char *a="jpegPhoto";

struct berval **bvals;

int count;

...

/* Get the values of the jpegPhoto attribute */

bvals = ldap_get_values_len( ld, e, a );

/* Count the values of the attribute */

count = ldap_count_values_len( vals );

...

See Also
ldap_count_values(), ldap_get_values_len().

ldap_create_filter()
The ldap_create_filter() routine constructs an LDAP search filter. For more information about filters, see "Creating Filters Programmatically."

Syntax
#include <ldap.h>
int ldap_create_filter( char *buf, unsigned long buflen,
  char *pattern, char *prefix, char *suffix, char *attr,
  char *value, char **valwords );

Parameters
This function has the following parameters:

Table 18-33    ldap_create_filter() function parameters

buf

Buffer to contain the constructed filter.

buflen

Size of the buffer.

pattern

Pattern for the filter.

prefix

Prefix to prepend to the filter (NULL if not used).

suffix

Suffix to append to the filter (NULL if not used).

attr

Replaces %a in the pattern.

value

Replaces %v in the pattern.

valwords

Replaces %vM through %vN in the pattern.

Returns
One of the following values:

LDAP_SUCCESS if successful.

LDAP_SIZELIMIT_EXCEEDED if the created filter exceeds the size of the buffer.

LDAP_PARAM_ERROR if an invalid parameter was passed to the function.

Example
The following section of code builds the filter (mail=bjensen@airius.com).

Code Example 18-10    Creating a filter with ldap_create_filter()

char buf[LDAP_FILT_MAXSIZ];

char *pattern = "(%a=%v)";

char *attr = "mail";

char *value = "bjensen@airius.com";

...

ldap_create_filter( buf, LDAP_FILT_MAXSIZ, pattern, NULL,

  NULL, attr, value, NULL );

...

See Also
ldap_init_getfilter(), ldap_init_getfilter_buf(), ldap_getfirstfilter(), ldap_getnextfilter(), ldap_set_filter_additions().

ldap_create_persistentsearch_control()
Creates a control that allows your client to perform a persistent search of an LDAP v3 server, which allows the search operation to continue without termination until your client abandons the search.
This function implements an extension to the LDAPv3 protocol. Persistent search is an optional LDAP server feature; it may not be supported on all LDAP servers. Call this function when interacting with LDAP servers that support this LDAPv3 extension.

Syntax
#include <ldap.h>
int ldap_create_persistentsearch_control( LDAP *ld,
  int changetypes, int changesonly, int return_echg_ctls,
  char ctl_iscritical, LDAPControl **ctrlp );

Parameters
This function has the following parameters:

Table 18-34    ldap_create_persistentsearch_control() function parameters

ld

Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.

changetypes

Specifies the types of changes that you want to keep track of. This field can have one or more of the following values (you can OR the values together to specify multiple types):

LDAP_CHANGETYPE_ADD specifies that you want to keep track of entries added to the directory.

LDAP_CHANGETYPE_DELETE specifies that you want to keep track of entries deleted from the directory.

LDAP_CHANGETYPE_MODIFY specifies that you want to keep track of entries that are modified.

LDAP_CHANGETYPE_MODDN specifies that you want to keep track of entries that are renamed.

LDAP_CHANGETYPE_ANY specifies that you want to keep track of all of the above changes to the directory.

changesonly

Specifies whether or not you want skip the initial search and only get the latest changes as they occur:

If non-zero, the initial search is skipped and only entries that have changed after the initial search are returned.

If 0, the results of the initial search are returned first.

return_echg_ctls

Specifies whether or not entry change notification controls are included with each entry returned to your client:

If non-zero, an entry change notification control is included with each entry.

If 0, entry change notification controls are not included with the entries returned from the server.

ctl_iscritical

Specifies whether or not the persistent search control is critical to the search operation:

If non-zero, the control is critical to the search operation. If the server does not support persistent searches, the server will return the error LDAP_UNAVAILABLE_CRITICAL_EXTENSION.

If 0, the control is not critical to the search operation. Even if the server does not support persistent searches, the search operation is still performed.

ctrlp

Pointer to a pointer to an LDAPControl structure that will be created by this function. When you are done using this control, you should free it by calling the ldap_control_free() function.

Returns
One of the following values:

LDAP_SUCCESS if successful.

LDAP_PARAM_ERROR if an invalid parameter was passed to the function.

LDAP_NO_MEMORY if memory cannot be allocated.

LDAP_ENCODING_ERROR if an error occurred when BER-encoding the control.

Description
The ldap_create_persistentsearch_control() function allows you to perform persistent searches. A persistent search provides the means to track changes to a set of entries that match the search criteria. After the initial search is performed, the server keeps track of the search criteria and sends back information when any entry that matches the criteria is added, deleted, modified, or renamed.
Calling this function creates an LDAP server control that you can pass to the ldap_search_ext() function.
In order for the control to work, the LDAP server that you are connecting to must support the server control for persistent searches (OID 2.16.840.1.113730.3.4.3, or LDAP_CONTROL_PERSISTENTSEARCH, as defined in the ldap.h header file). See "Determining the Controls Supported By the Server" for information on determining the controls supported by a server.
After you create the control, you can pass it to the LDAP server during a search operation. (Pass the server control when calling the ldap_search_ext() function.) If you specify that you want "entry change notification" controls sent back (that is, if you specify a non-zero value for the return_echg_ctls argument), the server includes controls with each changed entry it sends back.
To retrieve the "entry change notification control" from each entry, call the ldap_get_entry_controls() function. To get data about the changes made to the entry from the control, call the ldap_parse_entrychange_control() function.
When you are done with the search, you can cancel the persistent search by calling the ldap_abandon_ext() function. You should also free the control from memory by calling the ldap_control_free() function.

See Also
ldap_search_ext(), ldap_abandon_ext(), ldap_get_entry_controls(), ldap_parse_entrychange_control(), ldap_control_free().

ldap_create_proxyauth_control()
You use ldap_create_proxyauth_control() to create an LDAPv3 control that allows a bound entity to assume the identity of another directory entry.
This function implements the proxy authorization extension of the LDAPv3 protocol. Proxy authorization is an optional LDAP server feature and it may not be supported on all LDAP servers.

Syntax
#include <ldap.h>
int ldap_create_proxyauth_control( LDAP *ld, char *DN,
  char ctl_iscritical, LDAPControl **ctrlp);

Parameters
This function has the following parameters:

Table 18-35

ld

Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.

DN

String representing the distinguished name of the entry who's identity the client will be assuming.

ctl_iscritical

Specifies whether the persistent search control is critical to the search operation. For proxy authorization controls, this should be set to a non-zero value.
If non-zero, the control is critical to the directory operation. If the server does not support proxy authentication, the server will return an LDAP_UNAVAILABLE_CRITICAL_EXTENSION error.
If 0, the control is not critical to the directory operation. Even if the server does not support proxied authorization, the operation is still attempted and the proxied authorization control is ignored.

ctrlp

Pointer to a pointer to an LDAPControl structure that is created by this function. When you are done using this control, you should free it by calling the ldap_control_free() function.

Returns
One of the following values:

LDAP_SUCCESS if successful.

LDAP_PARAM_ERROR if an invalid parameter was passed to the function.

LDAP_NO_MEMORY if memory cannot be allocated.

LDAP_ENCODING_ERROR if an error occurred when BER-encoding the control.

LDAP_UNAVAILABLE_CRITICAL_EXTENSION if the server does not support proxied authorization and ctl_iscritical is set to a non-zero value.

See Also
ldap_control_free()

ldap_create_sort_control()
Creates a control that specifies the order in which you want search results returned.
This function implements an extension to the LDAPv3 protocol. Server-side sorting is an optional LDAP server feature; it may not be supported on all LDAP servers. Call this function when interacting with LDAP servers that support this LDAPv3 extension.

Syntax
#include <ldap.h>
int ldap_create_sort_control( LDAP *ld,
  LDAPsortkey **sortKeyList, const char ctl_iscritical,
  LDAPControl **ctrlp );

Parameters
This function has the following parameters:

Table 18-36    ldap_create_sort_control() function parameters

ld

Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.

sortKeyList

Pointer to an array of LDAPsortkey structures that specify the attribute types or matching rules used for sorting and the order (ascending or descending) in which to sort the results.

ctl_iscritical

Specifies whether or not the control is critical to the search operation. This field can have one of the following values:

A nonzero value specifies that the control is critical to the operation.

0 specifies that the control is not critical to the operation.

ctrlp

Pointer to a pointer to an LDAPControl structure that will be created by this function. When you are done using this control, you should free it by calling the ldap_control_free() function.

Returns
One of the following values:

LDAP_SUCCESS if successful.

LDAP_PARAM_ERROR if an invalid parameter was passed to the function.

LDAP_NO_MEMORY if memory cannot be allocated.

LDAP_ENCODING_ERROR if an error occurred when BER-encoding the control.

Description
The ldap_create_sort_control() function allows you to specify the order in which you want to receive data from the server. Calling this function creates an LDAP control that you can pass to the ldap_search_ext() and ldap_search_ext_s() functions.
In order for the control to work, the LDAP server that you are connecting to must support the server control for sorting search results (OID 1.2.840.113556.1.4.473, or LDAP_CONTROL_SORTREQUEST as defined in ldap.h). See "Determining the Controls Supported By the Server" for information on determining the controls supported by a server.
To specify the attributes to use for sorting the results, you can call ldap_create_sort_keylist() to create an array of LDAPsortkey structures and pass the array as the sortKeyList argument.
When you are done with the search, you should free the control and the array of LDAPsortkey structures by calling the ldap_control_free() function and the ldap_free_sort_keylist() function.

See Also
ldap_create_sort_keylist(), ldap_search_ext(), ldap_search_ext_s(), ldap_control_free().

ldap_create_sort_keylist()
Creates an array of LDAPsortkey structures from a string representation of a set of sort keys.

Syntax
#include <ldap.h>
int ldap_create_sort_keylist(LDAPsortkey ***sortKeyList,
  const char *string_rep);

Parameters
This function has the following parameters:

Table 18-37    ldap_create_sort_keylist() function parameters

sortKeyList

Pointer to an array of LDAPsortkey structures that specify the attribute types or matching rules used for sorting and the order (ascending or descending) in which to sort the results.

string_rep

String representation of a set of sort keys.

Returns
One of the following values:

LDAP_SUCCESS if successful.

LDAP_PARAM_ERROR if an invalid parameter was passed to the function.

LDAP_NO_MEMORY if memory cannot be allocated.

-1 if an error occurred

Description
The ldap_create_sort_keylist() function allows you to create an array of LDAPsortkey structures from a string representation of a set of sort keys. Calling this function creates an array of LDAPsortkey structures that you can pass to the ldap_create_sort_control() function.
The string representation specified by the string_rep argument should specify the name of the attribute that you want to sort by.

To sort in reverse order, precede the attribute name with a hyphen ("-").

To use a matching rule for sorting, append a colon to the attribute name and specify the object identifier (OID) of a matching rule after the colon.
For example:

cn (sort by the cn attribute)

-cn (sort by the cn attribute in reverse order)

-cn:1.2.3.4 (sort by the cn attribute in reverse order and use the matching rule identified by the OID 1.2.3.4)
When you are done sorting the results, you should free the array of LDAPsortkey structures by calling the ldap_free_sort_keylist() function.

See Also
ldap_create_sort_control(), ldap_free_sort_keylist().

ldap_create_virtuallist_control()
Creates a control that requests a subset of search results for use in a virtual list box.
This function implements an extension to the LDAPv3 protocol. This control is supported by the Netscape Directory Server, version 4.0 and later; and all iPlanet Directory Server versions. For information on determining if a server supports this or other LDAPv3 controls, see "Determining If the Server Supports LDAPv3".

Syntax
#include <ldap.h>
int ldap_create_virtuallist_control( LDAP *ld,
  LDAPVirtualList *ldvlistp, LDAPControl **ctrlp );

Parameters
This function has the following parameters:

Table 18-38    ldap_create_virtuallist_control() function parameters

ld

Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.

ldvlistp

Pointer to an LDAPVirtualList structure that specifies the subset of entries that you want retrieved from the server and the selected entry.

ctrlp

Pointer to a pointer to an LDAPControl structure that will be created by this function. When you are done using this control, you should free it by calling the ldap_control_free() function.

Returns
One of the following values:

LDAP_SUCCESS if successful.

LDAP_PARAM_ERROR if an invalid parameter was passed to the function.

LDAP_NO_MEMORY if memory cannot be allocated.

LDAP_ENCODING_ERROR if an error occurred when BER-encoding the control

Description
The ldap_create_virtuallist_control() function allows you to retrieve a subset of entries from the server for use in a virtual list box. Calling this function creates an LDAP control that you can pass to the ldap_search_ext() and ldap_search_ext_s() functions.
Note that you also need to pass a server-side sorting control to the search functions. You can call the ldap_create_sort_keylist() and ldap_create_sort_control() functions to create a server-side sorting control.
In order for the virtual list view control to work, the LDAP server that you are connecting to must support the server control for sorting search results (OID 2.16.840.1.113730.3.4.9, or LDAP_CONTROL_VLVREQUEST, as defined in ldap.h).
At this point in time, no server supports this control. (The Netscape Directory Server 3.x does not support this control, although future releases of the Directory Server plan to support it.) For information on determining if a server supports this or other LDAPv3 controls, see "Determining If the Server Supports LDAPv3".
To specify the subset of entries that you want to retrieve, create an LDAPVirtualList structure and pass in a pointer to this structure as the ldvlistp argument.
When you are done with the search, you should free the control by calling the ldap_control_free() function.
For more information about this control, see "Using the Virtual List View Control."

See Also
LDAPVirtualList, ldap_parse_virtuallist_control(), ldap_search_ext(), ldap_search_ext_s(), ldap_control_free().

ldap_delete()
Deletes an entry from the directory asynchronously.
Note that this is an older function that is included in the LDAP API for backward-compatibility. If you are writing a new LDAP client, use ldap_delete_ext() instead.

Syntax
#include <ldap.h>
int ldap_delete( LDAP *ld, const char *dn );

Parameters
This function has the following parameters:

Table 18-39    ldap_delete() function parameters

ld

Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.

dn

Distinguished name (DN) of the entry to remove.

Returns
Returns the message ID of the ldap_delete() operation. To check the result of this operation, call ldap_result() and ldap_result2error(). For a list of the possible result codes for an LDAP delete operation, see the result code documentation for the ldap_delete_ext_s() function.

Description
The ldap_delete() function removes an entry from the directory.
A newer version of this function, ldap_delete_ext(), is available in this release of the LDAP API. ldap_delete() (the older version of the function) is included only for backward-compatibility. If you are writing a new LDAP client, use ldap_delete_ext() instead of ldap_delete().
If you want more information on ldap_delete(), refer to the LDAP C SDK 1.0 Programmer's Guide.

Example
The following section of code uses the asynchronous ldap_delete() function to remove the entry for "Barbara Jensen" from the directory.

Code Example 18-11    ldap_delete() code example

#include <ldap.h>

...

LDAP *ld;

LDAPMessage *result;

int msgid, rc;

struct timeval tv;

/* Distinguished name of the entry that you want to delete. */

char *dn = "uid=bjensen, ou=People, o=airius.com";

...

/* Set up the timeout period to wait for the "modify" operation */

tv.tv_sec = tv.tv_usec = 0;

/* Delete the entry */

if ( ( msgid = ldap_delete( ld, dn ) ) == -1 ) {

  ldap_perror( ld, "ldap_delete" );

  return( 1 );

}

/* Check to see if the operation has completed */

while ( ( rc = ldap_result( ld, msgid, 0, &tv, &result ) ) == 0 ) {

  ...

  /* do other work while waiting for the operation to complete */

  ...

}

/* Check the result to see if any errors occurred */

ldap_result2error( ld, result, 1 );

ldap_perror( ld, "ldap_delete" );

...

See Also
ldap_delete_ext().

ldap_delete_ext()
Deletes an entry from the directory asynchronously.

Syntax
#include <ldap.h>
int ldap_delete_ext( LDAP *ld, const char *dn,
  LDAPControl **serverctrls, LDAPControl **clientctrls,
  int *msgidp );

Parameters
This function has the following parameters:

Table 18-40    ldap_delete_ext() function parameters

ld

Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.

dn

Distinguished name (DN) of the entry to remove.

serverctrls

Pointer to an array of LDAPControl structures representing LDAP server controls that apply to this LDAP operation. If you do not want to pass any server controls, specify NULL for this argument.

clientctrls

Pointer to an array of LDAPControl structures representing LDAP client controls that apply to this LDAP operation. If you do not want to pass any client controls, specify NULL for this argument.

msgidp

Pointer to an integer that will be set to the message ID of the LDAP operation. To check the result of this operation, call the ldap_result() and ldap_parse_result() functions.

Returns
One of the following values:

LDAP_SUCCESS if successful.

LDAP_PARAM_ERROR if any of the arguments are invalid.

LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request.

LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.

LDAP_NO_MEMORY if memory cannot be allocated.

LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAPv3 protocol. Make sure that you set the version of your LDAP client to version 3 before calling this function. (For details, see "Specifying the LDAP Version of Your Client.")

Description
The ldap_delete_ext() function deletes an entry from the directory asynchronously. Use the dn argument to specify the entry that you want to delete.
This function is a new version of the ldap_delete() function. If you are writing a new LDAP client, you should call this function instead of ldap_delete().
ldap_delete_ext() is an asynchronous function; it does not directly return results. If you want the results to be returned directly by the function, call the synchronous function ldap_delete_ext_s() instead. (For more information on asynchronous and synchronous functions, see "Calling Synchronous and Asynchronous Functions.")
In order to get the results of the LDAP delete operation, you need to call the ldap_result() function and the ldap_parse_result() function. (See "Calling Asynchronous Functions" for details.) For a list of possible result codes for an LDAP delete operation, see the result code documentation for the ldap_delete_ext_s() function.
For additional information on deleting entries from the directory, see "Deleting an Entry."

Example
See the example under "Example: Deleting an Entry from the Directory (Asynchronous)."

See Also
ldap_delete_ext_s(), ldap_result(), ldap_parse_result().

ldap_delete_ext_s()
Deletes an entry from the directory synchronously.

Syntax
#include <ldap.h>
int ldap_delete_ext_s( LDAP *ld, const char *dn,
  LDAPControl **serverctrls, LDAPControl **clientctrls );

Parameters
This function has the following parameters:

Table 18-41    ldap_delete_ext_s() function parameters

ld

Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.

dn

Distinguished name (DN) of the entry to remove.

serverctrls

Pointer to an array of LDAPControl structures representing LDAP server controls that apply to this LDAP operation. If you do not want to pass any server controls, specify NULL for this argument.

clientctrls

Pointer to an array of LDAPControl structures representing LDAP client controls that apply to this LDAP operation. If you do not want to pass any client controls, specify NULL for this argument.

Returns
One of the following values:

LDAP_SUCCESS if successful.

LDAP_PARAM_ERROR if any of the arguments are invalid.

LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request.

LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.

LDAP_NO_MEMORY if memory cannot be allocated.

LDAP_LOCAL_ERROR if an error occurred when receiving the results from the server.

LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded results from the server.

LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAPv3 protocol. Make sure that you set the version of your LDAP client to version 3 before calling this function. (For details, see "Specifying the LDAP Version of Your Client.")
The following result codes can be returned by the Directory Server when processing an LDAP delete request. Other LDAP servers may send these result codes under different circumstances or may send different result codes back to your LDAP client.

LDAP_OPERATIONS_ERROR may be sent by the Directory Server for general errors encountered by the server when processing the request.

LDAP_PROTOCOL_ERROR if the delete request did not comply with the LDAP protocol. The Directory Server may set this error code in the results for a variety of reasons. Some of these reasons include:

The server encountered an error when decoding your client's BER-encoded request.

LDAP_UNWILLING_TO_PERFORM may be sent by the Directory Server in the following situations:

The entry to be deleted is a DSE (DSA-specific entry, where DSA is the Directory Server Agent).

The server's database is read-only.

LDAP_NO_SUCH_OBJECT may be sent by the Directory Server if the entry that you want deleted does not exist and if no referral URLs are available.

LDAP_REFERRAL may be sent by the Directory Server if the DN specified by the dn argument identifies an entry not handled by the current server and if referral URLs identify a different server to handle the entry. (For example, if the DN is uid=bjensen, ou=European Sales, o=airius.com, all entries under ou=European Sales might be handled by a different Directory Server.)

LDAP_NOT_ALLOWED_ON_NONLEAF may be sent by the Directory Server if the entry that you want deleted has entries beneath it in the directory tree (in other words, if this entry is a parent entry to other entries).

LDAP_INSUFFICIENT_ACCESS may be sent by the Directory Server if the DN that your client is authenticated as does not have the access rights to write to the entry.
Note that the Directory Server may send other result codes in addition to the codes described here (for example, the server may have loaded a custom plug-in that returns other result codes).

Description
The ldap_delete_ext_s() function deletes an entry from the directory synchronously. Use the dn argument to specify the entry that you want to delete.
This function is a new version of the ldap_delete_s() function. If you are writing a new LDAP client, you should call this function instead of ldap_delete_s().
ldap_delete_ext_s() is a synchronous function, which directly returns the results of the operation. If you want to perform other operations while waiting for the results of this operation, call the asynchronous function ldap_delete_ext() instead. (For more information on asynchronous and synchronous functions, see "Calling Synchronous and Asynchronous Functions.")
For additional information on deleting entries from the directory, see "Deleting an Entry."

Example
See the example under "Example: Deleting an Entry from the Directory (Synchronous)."

See Also
ldap_delete_ext().

ldap_delete_s()
Deletes an entry from the directory synchronously.
Note that this is an older function that is included in the LDAP API for backward-compatibility. If you are writing a new LDAP client, use ldap_delete_ext_s() instead.

Syntax
#include <ldap.h>
int ldap_delete_s(LDAP *ld, const char *dn);

Parameters
This function has the following parameters:

Table 18-42    ldap_delete_s() function parameters

ld

Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.

dn

Distinguished name (DN) of the entry to remove.

Returns
For a list of possible result codes for an LDAP delete operation, see the result code documentation for the ldap_delete_ext_s() function.

Description
The ldap_delete_s() function removes an entry from the directory.
A newer version of this function, ldap_delete_ext_s(), is available in this release of the LDAP API. ldap_delete_s() (the older version of the function) is included only for backward-compatibility. If you are writing a new LDAP client, use ldap_delete_ext_s() instead of ldap_delete_s().
If you want more information on ldap_delete_s(), refer to the LDAP C SDK 1.0 Programmer's Guide.

Example
The following section of code uses the synchronous ldap_delete_s() function to delete the entry for Barbara Jensen from the directory.

Code Example 18-12    ldap_delete_s() code example

LDAP *ld;

/* Distinguished name of the entry that you want to delete. */

char *dn = "uid=bjensen, ou=People, o=airius.com";

...

/* Delete the entry */

if ( ldap_delete_s( ld, dn ) != LDAP_SUCCESS ) {

  ldap_perror( ld, "ldap_delete_s" );

  return( 1 );

}

...

See Also
ldap_delete_ext_s().

ldap_dn2ufn()
The ldap_dn2ufn() function converts a distinguished name (DN) into a "friendlier" form by stripping off the cryptic type names.

Syntax
#include <ldap.h>
char * ldap_dn2ufn( const char *dn );

Parameters
This function has the following parameters:

Table 18-43    ldap_dn2ufn() function parameters

dn

Distinguished name (DN) that you want converted to a friendlier form.

Returns
One of the following values:

If successful, returns the DN in its friendlier form.

If unsuccessful, returns NULL.

ldap_err2string()
The ldap_err2string() function returns the corresponding error message for an error code. For more information, see "Getting the Error Message."

Syntax
#include <ldap.h>
char * ldap_err2string( int err );

Parameters
This function has the following parameters:

Table 18-44    ldap_err2string() function parameters

err

Error code that you want interpreted into an error message.

Returns
One of the following values:

If successful, returns the corresponding error message for the error code.

If unsuccessful (for example, if the error code is not a valid LDAP API error code), returns "Unknown error".

Example
The following section of code sets the variable err_msg to the error message corresponding to the error code returned by the ldap_simple_bind_s() function.

Code Example 18-13    ldap_err2string() code example

...

LDAP *ld;

char *dn = "uid=bjensen, ou=People, o=airius.com";

char *pw = "hifalutin";

char *err_msg;

...

err_msg = ldap_err2string( ldap_simple_bind_s( ld, dn, pw ) );

...

See Also
ldap_get_lderrno(), ldap_perror(), ldap_result2error(), ldap_set_lderrno(), ldapssl_err2string().

ldap_explode_dn()
The ldap_explode_dn() function converts a distinguished name (DN) into its component parts. For more information, see "Getting the Components of a Distinguished Name."

Syntax
#include <ldap.h>
char ** ldap_explode_dn( const char *dn, int notypes );

Parameters
This function has the following parameters:

Table 18-45    ldap_explode_dn() function parameters

dn

Distinguished name (DN) that you want separated into components.

notypes

Specifies whether or not type names in the distinguished name are returned. This parameter can have the following possible values:

0 specifies that type names are returned.

A non-zero value specifies that type names are not returned.

Returns
One of the following values:

If successful, returns a NULL-terminated array containing the components of the distinguished name (DN).

If unsuccessful, returns a NULL.

Example
The following function call:
ldap_explode_dn( "uid=bjensen, ou=People, o=airius.com", 0 )
returns this array:
{ "uid=bjensen", "ou=People", "ou=airius.com", NULL }
If you change the notypes parameter from 0 to 1:
ldap_explode_dn( "uid=bjensen, ou=People, o=airius.com", 1 )
the component names are not returned in the array:
{ "bjensen", "People", "airius.com", NULL }

See Also
ldap_explode_rdn(), ldap_get_dn().

ldap_explode_rdn()
The ldap_explode_rdn() function converts a relative distinguished name (RDN) into its component parts. For more information, see "Getting the Components of a Distinguished Name."

Syntax
#include <ldap.h>
char ** ldap_explode_rdn( const char *dn, int notypes );

Parameters
This function has the following parameters:

Table 18-46    ldap_explode_rdn() function parameters

dn

Relative distinguished name (RDN) that you want separated into components.

notypes

Specifies whether or not type names in the relative distinguished name are returned. This parameter can have the following possible values:

0 specifies that type names are returned.

A non-zero value specifies that type names are not returned.

Returns
One of the following values:

If successful, returns a NULL-terminated array containing the components of the relative distinguished name (RDN).

If unsuccessful, returns a NULL.

Example
The following function call:
ldap_explode_rdn( "ou=Sales + cn=Barbara Jensen", 0 );
returns this array:
{ "ou=Sales", "cn=Barbara Jensen", NULL }

See Also
ldap_explode_dn(), ldap_get_dn().

ldap_extended_operation()
Sends a request to the server to perform an extended operation asynchronously.

Syntax
#include <ldap.h>
int ldap_extended_operation( LDAP *ld, const char *requestoid,
  struct berval *requestdata, LDAPControl **serverctrls,
  LDAPControl **clientctrls, int *msgidp );

Parameters
This function has the following parameters:

Table 18-47    ldap_extended_operation() function parameters

ld

Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.

requestoid

Object identifier (OID) of the extended operation that you want the server to perform.

requestdata

Pointer to a berval structure containing the data that you want passed to the server to perform the extended operation.

serverctrls

Pointer to an array of LDAPControl structures representing LDAP server controls that apply to this LDAP operation. If you do not want to pass any server controls, specify NULL for this argument.

clientctrls

Pointer to an array of LDAPControl structures representing LDAP client controls that apply to this LDAP operation. If you do not want to pass any client controls, specify NULL for this argument.

msgidp

Pointer to an integer that will be set to the message ID of the LDAP operation. To check the result of this operation, call the ldap_result() and ldap_parse_result() functions.

Returns
One of the following values:

LDAP_SUCCESS if successful.

LDAP_PARAM_ERROR if any of the arguments are invalid.

LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request.

LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.

LDAP_NO_MEMORY if memory cannot be allocated.

LDAP_NOT_SUPPORTED if your LDAP client does not specify that it is using the LDAPv3 protocol. Make sure that you set the version of your LDAP client to version 3 before calling this function. (For details, see "Specifying the LDAP Version of Your Client.")

Description
The ldap_extended_operation() function sends a request to the server to perform an LDAPv3 extended operation synchronously.
The LDAP server must support the extended operation. The Netscape Directory Server 3.0 supports a server plug-in interface that you can use to add support for extended operations to the server. For details, see the Netscape Directory Server 3.0 Programmer's Guide.
For information on determining the extended operations supported by a server, see "Determining the Extended Operations Supported."
After processing an LDAPv3 extended operation, an LDAP server can return an object identifier and data in the result. To parse the OID and data from the result, call the ldap_parse_extended_result() function.
ldap_extended_operation() is an asynchronous function; it does not directly return results. If you want the results to be returned directly by the function, call the synchronous function ldap_extended_operation_s() instead. (For more information on asynchronous and synchronous functions, see "Calling Synchronous and Asynchronous Functions.")
In order to get the results of the LDAP extended operation, you need to call the ldap_result() function, the ldap_parse_extended_result() function, and the ldap_get_lderrno() function. (See "Performing an Asynchronous Extended Operation" for details.) For a list of possible result codes for an LDAP extended operation, see the result code documentation for the ldap_extended_operation_s() function.

See Also
ldap_extended_operation_s(), ldap_result(), ldap_parse_extended_result(), ldap_get_lderrno().

ldap_extended_operation_s()
Sends a request to the server to perform an extended operation synchronously.

Syntax
#include <ldap.h>
int ldap_extended_operation_s( LDAP *ld, const char *requestoid,
  struct berval *requestdata, LDAPControl **serverctrls,
  LDAPControl **clientctrls, char **retoidp,
  struct berval **retdatap );

Parameters
This function has the following parameters:

Table 18-48    ldap_extended_operation_s() function parameters

ld

Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.

requestoid

Object identifier (OID) of the extended operation that you want the server to perform.

requestdata

Pointer to a berval structure containing the data that you want passed to the server to perform the extended operation.

serverctrls

Pointer to an array of LDAPControl structures representing LDAP server controls that apply to this LDAP operation. If you do not want to pass any server controls, specify NULL for this argument.

clientctrls

Pointer to an array of LDAPControl structures representing LDAP client controls that apply to this LDAP operation. If you do not want to pass any client controls, specify NULL for this argument.

retoidp

Pointer to the object identifier (OID) returned by the server after performing the extended operation.
When done, you can free this by calling the ldap_memfree() function.

retdatap

Pointer to the pointer to a berval structure containing the data returned by the server after performing the extended operation.
When done, you can free this by calling the ber_bvfree() function.

Returns
One of the following values:

LDAP_SUCCESS if successful.

LDAP_PARAM_ERROR if any of the arguments are invalid.

LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request.

LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.

LDAP_NO_MEMORY if memory cannot be allocated.

LDAP_LOCAL_ERROR if an error occurred when receiving the results from the server.

LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded results from the server.

LDAP_NOT_SUPPORTED if your LDAP client does not specify that it is using the LDAPv3 protocol. Make sure that you set the version of your LDAP client to version 3 before calling this function. (For details, see "Specifying the LDAP Version of Your Client.")
The following result codes can be returned by the Netscape Directory Server when processing an LDAP extended operation request. Other LDAP servers may send these result codes under different circumstances or may send different result codes back to your LDAP client.

LDAP_OPERATIONS_ERROR may be sent by the Netscape Directory Server for general errors encountered by the server when processing the request.

LDAP_PROTOCOL_ERROR if the extended operation request did not comply with the LDAP protocol. The Netscape Directory Server may set this error code in the results for a variety of reasons. Some of these reasons include:

The server encountered an error when decoding your client's BER-encoded request.

The extended operation specified by the requestoid argument is not supported by the server.

Depending on the extended operation requested, the Netscape Directory Server may send other result codes in addition to the codes described here. In the Netscape Directory Server, the people deploying the server are responsible for implementing the mechanisms for handling extended operations. Check with your server administrator for additional result codes returned to the client.

Description
The ldap_extended_operation_s() function sends a request to the server to perform an LDAPv3 extended operation synchronously.
The LDAP server must support the extended operation. The Netscape Directory Server 3.0 supports a server plug-in interface that you can use to add support for extended operations to the server. For details, see the Netscape Directory Server 3.0 Programmer's Guide.
For information on determining the extended operations supported by a server, see "Determining the Extended Operations Supported."
After processing an LDAPv3 extended operation, an LDAP server can return an object identifier and data in the results. The retoidp and retdatap arguments point to these values.
ldap_extended_operation_s() is a synchronous function, which directly returns the results of the operation. If you want to perform other operations while waiting for the results of this operation, call the asynchronous function ldap_extended_operation() instead. (For more information on asynchronous and synchronous functions, see "Calling Synchronous and Asynchronous Functions.")

See Also
ldap_extended_operation().

ldap_first_attribute()
The ldap_first_attribute() function returns the name of the first attribute in a entry returned by the ldap_first_entry() function, the ldap_next_entry() function, or the ldap_result() function.
For more information, see "Getting Attributes from an Entry."

Syntax
#include <ldap.h>
char * ldap_first_attribute( LDAP *ld, LDAPMessage *entry,
  BerElement **ber );

Parameters
This function has the following parameters:

Table 18-49    ldap_first_attribute() function parameters

ld

Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.

entry

Pointer to the LDAPMessage structure representing the entry returned by the ldap_first_entry() or ldap_next_entry() function.

ber

A pointer to a BerElement allocated to keep track of its current position. Pass this pointer to subsequent calls to ldap_next_attribute() to step through the entry's attributes.

Returns
One of the following values:

If successful, returns the pointer to the name of the first attribute in an entry. When you are done using this data, you should free the memory by calling the ldap_memfree() function.

If unsuccessful, returns a NULL and sets the appropriate error code in the LDAP structure. To get the error code, call the ldap_get_lderrno() function. (See Chapter 19 "Result Codes for a complete listing of error codes.)

Example
The following section of code retrieves each attribute for an entry.

Code Example 18-14    ldap_first_attribute() code example

#include <ldap.h>

...

LDAP *ld;

LDAPMessage *result, *e;

BerElement *ber;

char *a;

char *my_searchbase = "o=airius.com";

char *my_filter = "(sn=Jensen)"

...

/* Search the directory */

if ( ldap_search_s( ld, my_searchbase, LDAP_SCOPE_SUBTREE, \
  my_filter, NULL, 0, &result ) != LDAP_SUCCESS ) {

  ldap_perror( ld, "ldap_search_s" );

  return( 1 );

}

/* Get the first matching entry.*/

e = ldap_first_entry( ld, result );

/* Retrieve the attributes the entry */

  for ( a = ldap_first_attribute( ld, e, &ber ); a != NULL;

   a = ldap_next_attribute( ld, e, ber ) ) {

    ...

    /* Code to get and manipulate attribute values */

    ...

    }

    ldap_memfree( a );

  }

  /* Free the BerElement from memory when done */

  if ( ber != NULL ) {

    ldap_ber_free( ber, 0 );

  }

...

See Also
ldap_first_entry(), ldap_next_entry(), ldap_next_attribute().

ldap_first_entry()
Returns a pointer to the LDAPMessage structure representing the first directory entry in a chain of search results.

Syntax
#include <ldap.h>
LDAPMessage * ldap_first_entry( LDAP *ld, LDAPMessage *result );

Parameters
This function has the following parameters:

Table 18-50    ldap_first_entry() function parameters

ld

Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.

result

Chain of search results, which are represented by a pointer to the LDAPMessage structure.

Returns
One of the following values:

If successful, returns the pointer to the first LDAPMessage structure of the type LDAP_RES_SEARCH_ENTRY in the chain of search results.

If no LDAPMessage structures of the type LDAP_RES_SEARCH_ENTRY are in the chain of the search results or if the function is unsuccessful, returns a NULLMSG.

Description
The ldap_first_entry() function returns a pointer to the LDAPMessage structure representing the first directory entry in a chain of search results. Search result entries are in messages of the type LDAP_RES_SEARCH_ENTRY.
You can use this function in conjunction with the ldap_next_entry() function to iterate through the directory entries in a chain of search results. These functions skip over any messages in the chain that do not have the type LDAP_RES_SEARCH_ENTRY.
Do not free the LDAPMessage structure returned by this function. Because this is a structure within a chain of search results, freeing this structure will free part of the chain of search results. When you are done working with the search results, you can free the chain itself, rather than individual structures within the chain.
For more information, see "Iterating Through a Chain of Results."

See Also
ldap_result(), ldap_search_ext(), ldap_search_ext_s(), ldap_next_entry().

ldap_first_message()
Returns a pointer to the first LDAPMessage structure in a chain of search results.

Syntax
#include <ldap.h>
LDAPMessage * ldap_first_message( LDAP *ld, LDAPMessage *res );

Parameters
This function has the following parameters:

Table 18-51    ldap_first_message() function parameters

ld

Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.

res

Chain of search results, represented by a pointer to the LDAPMessage structure.

Returns
One of the following values:

If successful, returns the pointer to the first LDAPMessage structure in the chain of search results.

If no LDAPMessage structures are in the chain or if the function is unsuccessful, returns a NULLMSG.

Description
The ldap_first_message() function returns a pointer to the first LDAPMessage structure in a chain of search results.
You can use this function in conjunction with the ldap_next_message() function to iterate through the chain of search results. You can call the ldap_msgtype() function to determine if each message contains a matching entry (a message of the type LDAP_RES_SEARCH_ENTRY) or a search reference (a message of the type LDAP_RES_SEARCH_REFERENCE).
Do not free the LDAPMessage structure returned by this function. Because this is the first structure within a chain of search results, freeing this structure will free the chain of search results. When you are done working with the search results, you can free the chain itself, rather than individual structures within the chain.
For more information, see "Iterating Through a Chain of Results."

Example
See the examples under "Example: Searching the Directory (Asynchronous)" and "Example: Searching the Directory (Synchronous)."

See Also
ldap_result(), ldap_search_ext(), ldap_search_ext_s(), ldap_next_message().

ldap_first_reference()
Returns a pointer to the LDAPMessage structure representing the first search reference in a chain of search results.

Syntax
#include <ldap.h>
LDAPMessage * ldap_first_reference(LDAP *ld, LDAPMessage *res );

Parameters
This function has the following parameters:

Table 18-52    ldap_first_reference() function parameters

ld

Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.

res

Chain of search results, which are represented by a pointer to the LDAPMessage structure.

Returns
One of the following values:

If successful, returns the pointer to the first LDAPMessage structure of the type LDAP_RES_SEARCH_REFERENCE in the chain of search results.

If no LDAPMessage structures of the type LDAP_RES_SEARCH_REFERENCE are in the chain of the search results or if the function is unsuccessful, returns a NULLMSG.

Description
The ldap_first_reference() function returns a pointer to the LDAPMessage structure representing the first search reference in a chain of search results. Search references are in messages of the type LDAP_RES_SEARCH_REFERENCE.
You can use this function in conjunction with the ldap_next_reference() function to iterate through the search references in a chain of search results. These functions skip over any messages in the chain that do not have the type LDAP_RES_SEARCH_REFERENCE.
Do not free the LDAPMessage structure returned by this function. Because this is a structure within a chain of search results, freeing this structure will free part of the chain of search results. When you are done working with the search results, you can free the chain itself, rather than individual structures within the chain.
For more information, see "Iterating Through a Chain of Results."

See Also
ldap_result(), ldap_search_ext(), ldap_search_ext_s(), ldap_next_reference().

ldap_free_friendlymap()
The ldap_free_friendlymap() function frees the structures allocated by the ldap_friendly_name() function.

Syntax
#include <ldap.h>
void ldap_free_friendlymap( FriendlyMap *map );

Parameters
This function has the following parameters:

Table 18-53    ldap_free_friendlymap() function parameters

map

Pointer to the mapping structure in memory.

Example
The following section of code frees memory allocated by the ldap_friendly_name() function.

Code Example 18-15    ldap_free_friendlymap() code example

...

FriendlyMap *map;

...

ldap_free_friendlymap( map );

...

See Also
ldap_friendly_name().

ldap_free_sort_keylist()
Frees the structures allocated by the ldap_create_sort_keylist() function.

Syntax
#include <ldap.h>
void ldap_free_sort_keylist (LDAPsortkey **sortKeyList);

Parameters
This function has the following parameters:

Table 18-54    ldap_free_sort_keylist() function parameters

sortKeyList

Array of LDAPsortkey structures that you want to free from memory.

Description
The ldap_free_sort_keylist() function frees the array of LDAPsortkey structures allocated by the ldap_create_sort_keylist() function.
When you are done sorting results, you can call this function to free the memory that you have allocated.

See Also
ldap_create_sort_keylist().

ldap_free_urldesc()
The ldap_free_urldesc() function frees memory allocated by the ldap_url_parse() function. For more information, see "Freeing the Components of an LDAP URL."

Syntax
#include <ldap.h>
void ldap_free_urldesc( LDAPURLDesc *ludp );

Parameters
This function has the following parameters:

Table 18-55    ldap_free_urldesc() function parameters

ludp

Pointer to a LDAPURLDesc structure.

Example
The following section of code parses an LDAP URL and then frees the LDAPURLDesc structure from memory after verifying that the LDAP URL is valid.

Code Example 18-16    ldap_free_urldesc() code example

#include <stdio.h>

#include <ldap.h>

...

char *my_url = "ldap://ldap.netscape.com:5000/o=airius.com?cn,mail,telephoneNumber?sub? \

  (sn=Jensen)";

LDAPURLDesc *ludpp;

int res, i;

...

if ( ( res = ldap_url_parse( my_url, &ludpp ) ) != 0 ) {

  switch( res ){

    case LDAP_URL_ERR_NOTLDAP:

      printf( "URL does not begin with \"ldap://\"\n" );

      break;

    case LDAP_URL_ERR_NODN:

      printf( "URL does not contain a distinguished name\n" );

      break;

    case LDAP_URL_ERR_BADSCOPE:

      printf( "URL contains an invalid scope\n" );

      break;

    case LDAP_URL_ERR_MEM:

      printf( "Not enough memory\n" );

      break;

    default:

      printf( "Unknown error\n" );

  }

  return( 1 );

}

printf( "URL is a valid LDAP URL\n" );

ldap_free_urldesc( ludpp );

...

See Also
ldap_url_parse().

ldap_friendly_name()
The ldap_friendly_name() function maps a set of "unfriendly names" (for example, a two-letter country code such as "IS") to "friendly names" (for example, the full names of countries, such as "Iceland").
This function relies on the existence of a file mapping "unfriendly names" to "friendly names". The names in the file are tab-delimited, as shown in the example file below:
unfriendly_name>        <friendly_name>
AD        Andorra
AE        United Arab Emirates
AF        Afghanistan
AG        Antigua and Barbuda
AI        Anguilla

Syntax
#include <ldap.h>
char * ldap_friendly_name( char *filename, char *uname,
  FriendlyMap *map );

Parameters
This function has the following parameters:

Table 18-56    ldap_friendly_name() function parameters

filename

Name of the map file listing the "unfriendly names" and "friendly names."

uname

"Unfriendly name" for which you want to find the "friendly name."

map

Pointer to the mapping in memory. Initialize this pointer to NULL on the first call, then use the pointer during subsequent calls so that the mapping file does not need to be read again.

Returns
One of the following values:

If successful, returns the "friendly name" for the specified "unfriendly name".

If unsuccessful (for example, if the file cannot be read, if the file is in a bad format, or if the map parameter is set to NULL), returns the original name (the name you passed as the uname parameter).

Example
The following section of code reads in a map of friendly names and prints the name corresponding to the unfriendly name "IS".

Code Example 18-17    ldap_friendly_name() code example

#include <stdio.h>

...

FriendlyMap map = NULL;

char *map_file = "/u/mozilla/ldapsdk/examples/ldapfriendly";

char *unfriendly_name = "IS";

char *friendly_name;

...

/* Read the ldapfriendly file into the map in memory */

friendly_name = ldap_friendly_name( map_file, unfriendly_name, &map );

printf( "Friendly Name for %s: %s\n", unfriendly_name, friendly_name );

/* Since the file is in memory now, no need to reference it in subsequent calls */

friendly_name = ldap_friendly_name( NULL, "VI", &map );

printf( "Friendly Name for VI: %s\n", friendly_name );

...

See Also
ldap_free_friendlymap().

ldap_get_dn()
The ldap_get_dn() routine returns the distinguished name (DN) for an entry in a chain of search results. You can get an entry from a chain of search results by calling the ldap_first_entry() and ldap_next_entry() functions. For more information, see "Getting Distinguished Names for Each Entry."

Syntax
#include <ldap.h>
char * ldap_get_dn( LDAP *ld, LDAPMessage *entry );

Parameters
This function has the following parameters:

Table 18-57    ldap_get_dn() function parameters

ld

Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.

entry

Pointer to an entry in a chain of search results, as returned by the ldap_first_entry() and ldap_next_entry() functions.

Returns
One of the following values:

If successful, returns the distinguished name (DN) for the specified entry.

If unsuccessful, returns a NULL and sets the appropriate error code in the LDAP structure. To get the error code, call the ldap_get_lderrno() function. (See Chapter 19 "Result Codes" for a complete listing of error codes.)

Example
The following section of code prints the distinguished name for each entry found in a search.

Code Example 18-18    ldap_get_dn() code example

#include <stdio.h>

#include <ldap.h>

...

LDAP *ld;

LDAPMessage *result, *e;

char *dn;

char *my_searchbase = "o=airius.com";

char *my_filter = "(sn=Jensen)";

...

/* Search the directory */

if ( ldap_search_s( ld, my_searchbase, LDAP_SCOPE_SUBTREE, my_filter,

  NULL, 0, &result ) != LDAP_SUCCESS ) {

  ldap_perror( ld, "ldap_search_s" );

  return( 1 );

}

/* For each matching entry found, print out the name of the entry.*/

for ( e = ldap_first_entry( ld, result ); e != NULL;

  e = ldap_next_entry( ld, e ) ) {

  if ( ( dn = ldap_get_dn( ld, e ) ) != NULL ) {

    printf( "dn: %s\n", dn );

    /* Free the memory used for the DN when done */

    ldap_memfree( dn );

  }

}

/* Free the result from memory when done. */

ldap_msgfree( result );

...

See Also
ldap_first_entry(), ldap_next_entry().

ldap_get_entry_controls()
Gets the LDAP controls included with a directory entry in a set of search results.

Syntax
#include <ldap.h>
int ldap_get_entry_controls( LDAP *ld, LDAPMessage *entry,
  LDAPControl ***serverctrlsp );

Parameters
This function has the following parameters:

Table 18-58    ldap_get_entry_controls() function parameters

ld

Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.

entry

Pointer to an LDAPMessage structure representing an entry in a chain of search results.

serverctrlsp

Pointer to an array of LDAPControl structures, which represent the LDAPv3 server controls returned by the server.

Returns
One of the following values:

LDAP_SUCCESS if the LDAP controls were successfully retrieved.

LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded message.

LDAP_PARAM_ERROR if an invalid parameter was passed to the function.

LDAP_NO_MEMORY if memory cannot be allocated.

Description
The ldap_get_entry_controls() function retrieves the LDAPv3 controls included in a directory entry in a chain of search results.
The LDAP controls are specified in an array of LDAPControl structures. (Each LDAPControl structure represents an LDAP control.)
At this point in time, the entry notification controls (which are used with persistent search controls) are the only controls that are returned with individual entries. Other controls are returned with results sent from the server. You can call ldap_parse_result() to retrieve those controls.

ldap_getfilter_free()
The ldap_getfilter_free() function frees the memory used by a filter set. Once you call this routine, the LDAPFiltDesc structure is no longer valid and cannot be used again. For more information, see "Freeing Filters from Memory."

Syntax
#include <ldap.h>
void ldap_getfilter_free( LDAPFiltDesc *lfdp );

Parameters
This function has the following parameters:

Table 18-59    ldap_getfilter_free() function parameters

lfdp

Pointer to a LDAPFiltDesc structure.

Example
The following section of code frees the LDAPFiltDesc structure from memory after all searches are completed.

Code Example 18-19    ldap_getfilter_free code example

#include <ldap.h>

...

LDAPFiltDesc *lfdp;

char *filter_file = "myfilters.conf";

...

/* Read the filter configuration file into an LDAPFiltDesc structure */

lfdp = ldap_init_getfilter( filter_file );

...

/* Retrieve filters and perform searches */

...

/* Free the configuration file (the LDAPFiltDesc structure) */

ldap_getfilter_free( lfdp );

...

See Also
ldap_init_getfilter(), ldap_init_getfilter_buf().

ldap_getfirstfilter()
The ldap_getfirstfilter() function retrieves the first filter that is appropriate for a given value. For more information, see "Retrieving Filters."

Syntax
#include <ldap.h>
LDAPFiltInfo * ldap_getfirstfilter( LDAPFiltDesc *lfdp,
  char *tagpat, char *value );

Parameters
This function has the following parameters:

Table 18-60    ldap_getfirstfilter() function parameters

lfdp

Pointer to an LDAPFiltDesc structure.

tagpat

Regular expression for a tag in the filter configuration.

value

Value for which to find the first appropriate filter.

Returns
One of the following values:

If successful, returns a pointer to an LDAPFiltInfo structure.

If no more filters can be returned, returns a NULL.

If unsuccessful, returns a NULL.

Example
The following section of code is based on the getfilt command-line program example provided with the LDAP SDK for C. The program prompts the user to enter search criteria. Based on the criteria entered, the program retrieves filters that match the search criteria. The example uses the filter configuration file shown in "Understanding the Configuration File Syntax."

Code Example 18-20    ldap_getfirstfilter() code example

#include <stdio.h>

#include <ldap.h>

...

LDAP *ld;

LDAPMessage *result, *e;

BerElement *ber;

char *a, *dn;

char **vals;

int i;

LDAPFiltDesc *ldfp;

LDAPFiltInfo *ldfi;

char buf[ 80 ]; /* Contains the search criteria */

int found;

...

/* Load the filter configuration file into an LDAPFiltDesc structure */

if ( ( ldfp = ldap_init_getfilter( "myfilters.conf" ) ) == NULL ) {

  perror( "Cannot open filter configuration file" );

  return( 1 );

}

/* Read a string to search for */

printf( "Enter a string to search for: " );

gets( buf );

if ( strlen( buf ) == 0 ) {

  fprintf( stderr, "usage: %s search-string\n", argv[ 0 ]);

  return( 1 );

}

/* Select a filter to use when searching for the value in buf */

found = 0;

for ( ldfi = ldap_getfirstfilter( ldfp, "people", buf ); ldfi != NULL; ldfi = ldap_getnextfilter( ldfp ) ) {

  /* Use the selected filter to search the directory */

  if ( ldap_search_s( ld, "o=airius.com, ldfi->lfi_scope,

   ldfi->lfi_filter, NULL, 0, &result ) != LDAP_SUCCESS ) {

    ldap_perror( ld, "ldap_search_s" );

    return( 1 );

  } else {

    /* Once a filter gets results back, stop iterating through the different filters */

    if ( ( found = ldap_count_entries( ld, result ) > 0 ) ) {

      break;

    } else {

      ldap_msgfree( result );

    }

  }

}

if ( found == 0 ) {

  printf( "No matching entries found.\n" );

} else {

  printf( "Found %d %s match%s for \"%s\"\n\n", found,

   ldfi->lfi_desc, found == 1 ? "" : "es", buf );

}

ldap_msgfree( result );

ldap_getfilter_free( ldfp );

...

See Also
ldap_init_getfilter(), ldap_init_getfilter_buf(), ldap_getnextfilter().

ldap_get_lang_values()
The ldap_get_lang_values() function returns a NULL-terminated array of an attribute's string values that match a specified language subtype.
If you want to retrieve binary data from an attribute, call the ldap_get_lang_values_len() function instead.

Syntax
#include <ldap.h>
char ** ldap_get_lang_values( LDAP *ld, LDAPMessage *entry,
  const char *target, char **type );

Parameters
This function has the following parameters:

Table 18-61    ldap_get_lang_values() function parameters

ld

Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.

entry

Entry retrieved from the directory.

target

Attribute type (including an optional language subtype) that you want to retrieve the values of.

type

Pointer to a buffer that returns the attribute type retrieved by this function.

Returns
One of the following values:

If successful, returns a NULL-terminated array of the attribute's values.

If unsuccessful or if no such attribute exists in the entry, returns a NULL and sets the appropriate error code in the LDAP structure. To get the error code, call the ldap_get_lderrno() function. (See Chapter 19 "Result Codes" for a complete listing of error codes.)

Description
Unlike the ldap_get_values() function, if a language subtype is specified, this function first attempts to find and return values that match that subtype (for example, cn;lang-en).

See Also
ldap_first_entry(), ldap_next_entry(), ldap_first_attribute(), ldap_next_attribute(), ldap_get_lang_values_len(), ldap_get_values().

ldap_get_lang_values_len()
The ldap_get_lang_values_len() function returns a NULL-terminated array of pointers to berval structures, each containing the length and pointer to a binary value of an attribute for a given entry. Use the ldap_get_lang_values() routine instead of this routine if the attribute values are string values.
For more information, see "Getting the Values of an Attribute."

Syntax
#include <ldap.h>
struct berval ** ldap_get_lang_values_len( LDAP *ld,
  LDAPMessage *entry, const char *target, char **type );

Parameters
This function has the following parameters:

Table 18-62    ldap_get_lang_values_len() function parameters

ld

Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.

entry

Result returned by the ldap_result() or ldap_search_s() function.

target

Attribute returned by ldap_first_attribute() or ldap_next_attribute(), or the attribute as a literal string, such as "jpegPhoto" or "audio".

type

Pointer to a buffer that returns the attribute type retrieved by this function.

Returns
One of the following values:

If successful, returns a NULL-terminated array of pointers to berval structures, which in turn contain pointers to the attribute's binary values.

If unsuccessful or if no such attribute exists in the entry, returns a NULL and sets the appropriate error code in the LDAP structure. To get the error code, call the ldap_get_lderrno() function. (See Chapter 19 "Result Codes" for a complete listing of error codes.)

See Also
ldap_first_entry(), ldap_next_entry(), ldap_first_attribute(), ldap_next_attribute(), ldap_get_lang_values(), ldap_get_values_len().

ldap_get_lderrno()
The ldap_get_lderrno() function gets information about the last error that occurred for an LDAP operation. You can also call this function to get error codes for functions that do not return errors (such as ldap_next_attribute()).
For more information, see "Getting Information About the Error."

Syntax
#include <ldap.h>
int ldap_get_lderrno( LDAP *ld, char **m, char **s );

Parameters
This function has the following parameters:

Table 18-63    ldap_get_lderrno() function parameters

ld

Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.

m

In the event of an LDAP_NO_SUCH_OBJECT error return, this parameter contains the portion of the DN that identifies an existing entry. (See "Receiving the Portion of the DN Matching an Entry.")

s

The text of the error message.

Returns
The LDAP error code for the last operation. (See Chapter 19 "Result Codes" for a complete listing of error codes.)

Example
The following section of code attempts to add a new user to the directory. If the entry identified by a DN does not exist, the server sends the client a portion of the DN that find an existing entry. This DN is returned to the client as the variable matched. (See "Receiving the Portion of the DN Matching an Entry" for details.)

Code Example 18-21    ldap_get_lderrno() code example

LDAP *ld;

char *dn = "uid=bjensen, ou=People, o=airius.com";

LDAPMod **list_of_attrs;

char *matched;

int rc;

...

if ( ldap_add_s( ld, dn, list_of_attrs ) != LDAP_SUCCESS ) {

  rc = ldap_get_lderrno( ld, &matched, NULL );

  return( rc );

}

...

In the example above, if no organizational unit named New Department exists, the matched variable is set to:
o=airius.com

See Also
ldap_err2string(), ldap_perror(), ldap_result2error(), ldap_set_lderrno().

ldap_getnextfilter()
The ldap_getnextfilter() function retrieves the next filter that is appropriate for a given value. Call this function to get subsequent filters after calling ldap_getfirstfilter(). For more information, see "Retrieving Filters."

Syntax
#include <ldap.h>
LDAPFiltInfo * ldap_getnextfilter( LDAPFiltDesc *lfdp );

Parameters
This function has the following parameters:

Table 18-64    ldap_getnextfilter() function parameters

lfdp

Pointer to an LDAPFiltDesc structure.

Returns
One of the following values:

If successful, returns a pointer to an LDAPFiltInfo structure.

If no more filters can be returned, returns a NULL.

If unsuccessful, returns a NULL.

Example
See the example under ldap_getfirstfilter().

See Also
ldap_getfirstfilter().

ldap_get_option()
The function ldap_get_option() gets session preferences from an LDAP structure. For information on the options you can retrieve with this function, see ldap_set_option().

Syntax
#include <ldap.h>
int ldap_get_option( LDAP *ld, int option, void *optdata );

Parameters
This function has the following parameters:

Table 18-65    ldap_get_option() function parameters

ld

Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.

option

Option that you want to retrieve.
The option parameter must be set to one of the option values, as detailed in Table 18-117, page 491, which describes the function parameters for ldap_set_option().

optdata

Pointer to the buffer in which the value of the option will be put.

The following table describes the options that you can retrieve with ldap_get_option().

Table 18-66    Options for the ldap_get_options() function

LDAP_OPT_API_FEATURE_INFO

Retrieves information about the revision of a supported LDAP feature.

LDAP_OPT_API_INFO

Retrieves information the API and the extensions supported, including the supported API version, protocol version, the names of the supported API extensions with their vendor name version. For details on the structure returned, refer to the ldap.h header file.

LDAP_OPT_CLIENT_CONTROLS

Pointer to an array of LDAPControl structures representing the LDAPv3 client controls you want sent with every request by default.
The data type for the optdata parameter is (LDAPControl ***).

LDAP_OPT_DESC

Socket descriptor underlying the main LDAP connection.
The data type for the optdata parameter is
(LBER_SOCKET *). The LBER_SOCKET data type depends on the platform that you are using:

int in UNIX.

SOCKET in Windows.

LDAP_OPT_DEREF

Determines how aliases work during a search.
The data type for the optdata parameter is (int *).
optdata can be one of the following values:

LDAP_DEREF_NEVER specifies that aliases are never dereferenced.

LDAP_DEREF_SEARCHING specifies that aliases are dereferenced when searching under the base object (but not when finding the base object).

LDAP_DEREF_FINDING specifies that aliases are dereferenced when finding the base object (but not when searching under the base object).

LDAP_DEREF_ALWAYS specifies that aliases are always dereferenced when finding and searching under the base object.

LDAP_OPT_DNS_FN_PTRS

Lets you use alternate DNS functions for getting the host entry of the LDAP server.
The data type for the optdata parameter is (struct ldap_dns_fns *).

LDAP_OPT_ERROR_NUMBER

Result code for the most recent LDAP error that occurred for this session.
The data type for the optdata parameter is (int *).

LDAP_OPT_ERROR_STRING

Error message returned with the result code for the most recent LDAP error that occurred for this session.
The data type for the optdata parameter is (char **).

LDAP_OPT_EXTRA_THREAD_FN_PTRS

Lets you specify the locking and semaphore functions that you want called when getting results from the server. (See Chapter 16 "Writing Multithreaded Clients" for details.)
The data type for the optdata parameter is (struct ldap_extra_thread_fns *).

LDAP_OPT_IO_FN_PTRS

Lets you use alternate communication stacks.
The data type for the optdata parameter is (struct ldap_io_fns *).

LDAP_OPT_MATCHED_DN

Gets the matched DN value returned with the most recent LDAP error that occurred for this session.

LDAP_OPT_MEMALLOC_FN_PTRS

Gets a pointer to the callback structure which you previously set.
The data type for the optdata parameter is (struct ldap_memalloc_fnsldap_io_fns *).

LDAP_OPT_PROTOCOL_VERSION

Version of the protocol supported by your client.
The data type for the optdata parameter is (int *).
You can specify either LDAP_VERSION2 or LDAP_VERSION3. If no version is set, the default is LDAP_VERSION2.
In order to use LDAPv3 features, you need to set the protocol version to LDAP_VERSION3.

LDAP_OPT_REBIND_ARG

Lets you set the last argument passed to the routine specified by LDAP_OPT_REBIND_FN.
You can also set this option by calling the ldap_set_rebind_proc() function.
The data type for the optdata parameter is (void *).

LDAP_OPT_REBIND_FN

Lets you set the routine to be called when you need to authenticate a connection with another LDAP server (for example, during the course of following a referral).
You can also set this option by calling the ldap_set_rebind_proc() function.
The data type for the optdata parameter is (LDAP_REBINDPROC_CALLBACK *).

LDAP_OPT_RECONNECT

If the connection to the server is lost, determines whether or not the same connection handle should be used to reconnect to the server.
The data type for the optdata parameter is (int *).
optdata can be one of the following values:

LDAP_OPT_ON specifies that the same connection handle can be used to reconnect to the server.

LDAP_OPT_OFF specifies that you want to create a new connection handle to connect to the server.

By default, this option is off.
For details, see "Handling Failover."

LDAP_OPT_REFERRALS

Determines whether or not the client should follow referrals.
The data type for the optdata parameter is (int *).
optdata can be one of the following values:

LDAP_OPT_ON specifies that the server should follow referrals.

LDAP_OPT_OFF specifies that the server should not follow referrals.

By default, the client follows referrals.

LDAP_OPT_REFERRAL_HOP_LIMIT

Maximum number of referrals the client should follow in a sequence (in other words, the client can only be referred this number of times before it gives up).
The data type for the optdata parameter is (int *).
By default, the maximum number of referrals that the client can follow in a sequence is 5 for the initial connection.
Note that this limit does not apply to individual requests that generate multiple referrals in parallel.

LDAP_OPT_RESTART

Determines whether or not LDAP I/O operations should be restarted automatically if they are prematurely aborted.
The data type for the optdata parameter is (int *).
optdata can be one of the following values:

LDAP_OPT_ON specifies that I/O operations should be restarted automatically.

LDAP_OPT_OFF specifies that I/O operations should not be restarted automatically.

LDAP_OPT_SERVER_CONTROLS

Pointer to an array of LDAPControl structures representing the LDAPv3 server controls you want sent with every request by default.
Typically, since controls are specific to the type of request, you may want to pass the controls using operation-specific functions (such as ldap_add_ext()) instead.
The data type for the optdata parameter is
(LDAPControl ***).

LDAP_OPT_SIZELIMIT

Maximum number of entries that should be returned by the server in search results.
The data type for the optdata parameter is (int *).
Note that the LDAP server may impose a smaller size limit than the limit you specify. (The server administrator has the ability to set this limit.)

LDAP_OPT_SSL

Determines whether or not SSL is enabled.
The data type for the optdata parameter is (int *).
optdata can be one of the following values:

LDAP_OPT_ON specifies that SSL is enabled.

LDAP_OPT_OFF specifies that SSL is disabled.

LDAP_OPT_THREAD_FN_PTRS

Lets you specify the thread function pointers. (See Chapter 16 "Writing Multithreaded Clients" for details.)
The data type for the optdata parameter is
(struct ldap_thread_fns *).

LDAP_OPT_TIMELIMIT

Maximum number of seconds that should be spent by the server when answering a search request.
The data type for the optdata parameter is (int *).
Note that the LDAP server may impose a shorter time limit than the limit you specify. (The server administrator has the ability to set this limit.)

Returns
One of the following values:

LDAP_SUCCESS if successful.

-1 if unsuccessful.

Examples
The following example gets the session preference for the maximum number of entries to be returned from search operations.

Code Example 18-22    ldap_get_option() code example

...

LDAP *ld;

int max_ret;

...

/* Get the maximum number of entries returned */

if (ldap_get_option, LDAP_OPT_SIZELIMIT, &max_ret) != LDAP_SUCCESS) {

  ldap_perror( ld, "ldap_get_option" );

  return( 1 );

}

Here are two small sections of code that show how to use the LDAP_OPT_API_FEATURE_INFO and the LDAP_OPT_API_INFO options, respectively:

ldfi.ldapaif_info_version = LDAP_FEATURE_INFO_VERSION;

ldfi.ldapaif_name = "VIRTUAL_LIST_VIEW";

if (ldap_get_option(NULL, LDAP_OPT_API_FEATURE_INFO, &ldfi)==0) {

/* use the info here */ }

LDAPIInfo ldai;

ldai.ldapiai_info_version = LDAP_API_INFO_VERSION;

if (ldap_get_option( NULL, LDAP_OPT_API_INFO, &ldia ) == 0) {

/* use the ldai info here */

}

See Also
ldap_init(), ldap_set_option().

ldap_get_values()
The ldap_get_values() function returns a NULL-terminated array of an attribute's string values for a given entry. Use the ldap_get_values_len() function instead of this function if the attribute values are binary.
For more information, see "Getting the Values of an Attribute."

Syntax
#include <ldap.h>
char ** ldap_get_values( LDAP *ld, LDAPMessage *entry,
  const char *target );

Parameters
This function has the following parameters:

Table 18-67    ldap_get_values() function parameters

ld

Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.

entry

Result returned by the ldap_result() or ldap_search_s() function.

target

Attribute returned by ldap_first_attribute() or ldap_next_attribute(), or the attribute as a literal string, such as "jpegPhoto" or "audio".

Returns
One of the following values:

If successful, returns a NULL-terminated array of the attribute's values.

If unsuccessful or if no such attribute exists in the entry, returns a NULL and sets the appropriate error code in the LDAP structure. To get the error code, call the ldap_get_lderrno() function. (See Chapter 19 "Result Codes" for a complete listing of error codes.)

Example
The following section of code gets and prints the values of an attribute in an entry. This example assumes that all attributes have string values.

Code Example 18-23    ldap_get_values() code example

#include <ldap.h>

...

LDAP *ld;

LDAPMessage *result, *e;

BerElement *ber;

char *a;

Function	Description
ldap_init()	Initialize an LDAP session.
ldapssl_init()	Initialize an LDAP session over SSL.
ldapssl_pkcs_init()	Initialize a thread-safe session over SSL.
ldap_set_option()	Set session preferences.
ldap_get_option()	Get session preferences.
ldap_unbind(), ldap_unbind_s(), or ldap_unbind_ext()	End an LDAP session.

Function	Description
ldap_simple_bind() or ldap_simple_bind_s()	Authenticate to an LDAP server using a password.
ldap_sasl_bind() and ldap_parse_sasl_bind_result(), or ldap_sasl_bind_s()	Authenticate to an LDAP server using a SASL mechanism.
ldap_set_rebind_proc()	Specify the function used to get authentication information when following referrals.

Function	Description
ldap_add_ext() or ldap_add_ext_s()	Add a new entry to the directory.
ldap_modify_ext() or ldap_modify_ext_s()	Modify an entry in the directory.
ldap_delete_ext() or ldap_delete_ext_s()	Delete an entry from the directory.
ldap_rename() or ldap_rename_s()	Rename an entry in the directory.
ldap_search_ext() or ldap_search_ext_s()	Search the directory.
ldap_compare_ext() or ldap_compare_ext_s()	Compare entries in the directory.
ldap_extended_operation() or ldap_extended_operation_s()	Perform an LDAPv3 extended operation.
ldap_result()	Check the results of an asynchronous operation.
ldap_parse_extended_result()	Parse the results of an LDAPv3 extended operation.
ldap_msgfree()	Free the results from memory.
ldap_abandon_ext()	Cancel an asynchronous operation.

Function	Description
ldap_first_message()	Get the first message (an entry or search reference) in a chain of search results.
ldap_next_message()	Get the next message (an entry or search reference) in a chain of search results.
ldap_count_messages()	Count the number of messages (entries and search references) in a chain of search results.
ldap_first_entry()	Get the first entry in a chain of search results.
ldap_next_entry()	Get the next entry in a chain of search results.
ldap_count_entries()	Count the number of entries in a chain of search results.
ldap_first_reference()	Get the first search reference in a chain of search results.
ldap_next_reference()	Get the next search reference in a chain of search results.
ldap_count_references()	Count the number of search references in a chain of search results.
ldap_get_dn()	Get the distinguished name for an entry.
ldap_first_attribute()	Get the name of the first attribute in an entry.
ldap_next_attribute()	Get the name of the next attribute in an entry.
ldap_get_values()	Get the string values of an attribute.
ldap_get_values_len()	Get the binary values of an attribute.
ldap_count_values()	Count the string values of an attribute.
ldap_count_values_len()	Count the binary values of an attribute.
ldap_get_lang_values()	Get the string values of the specified language subtype of an attribute.
ldap_get_lang_values_len()	Get the binary values of the specified language subtype of an attribute.
ldap_value_free()	Free the memory allocated for the string values of an attribute.
ldap_value_free_len()	Free the memory allocated for the binary values of an attribute.

Function	Description
ldap_sort_entries()	Have your client sort entries by distinguished name or by a single attribute.
ldap_multisort_entries()	Have your client sort entries by multiple attributes.
ldap_create_sort_keylist(), ldap_create_sort_control(), ldap_parse_sort_control()	Request that the server sort the search results before sending them to your client.
ldap_sort_values()	Sort the values of an attribute
ldap_sort_strcasecmp()	A case-insensitive comparison function that you can pass to ldap_sort_values().

Function	Description
ldap_init_getfilter()	Read a filter configuration file into memory.
ldap_init_getfilter_buf()	Read a filter configuration from a buffer.
ldap_set_filter_additions()	Specify the prefix and suffix to be added to all filters retrieved from the filter configuration.
ldap_getfirstfilter()	Retrieve the first matching filter from the filter configuration.
ldap_getnextfilter()	Retrieve the next matching filter from the filter configuration.
ldap_getfilter_free()	Free the filter configuration from memory.
ldap_create_filter()	Build a filter.

Function	Description
ldap_get_dn()	Get the distinguished name for an entry.
ldap_explode_dn()	Split up a distinguished name into its components.
ldap_explode_rdn()	Split up a relative distinguished name into its components.

Function	Description
ldap_create_persistentsearch_control()	Create a "persistent search" control to track changes in directory entries.
ldap_create_sort_keylist(), ldap_create_sort_control()	Create a "sorting" control to return sorted search results from the LDAP server.
ldap_create_proxyauth_control()	Create a "proxy authorization" control to allow an entry to act as a proxy for an alternate entry.
ldap_add_ext(), ldap_add_ext_s(), ldap_compare_ext(), ldap_compare_ext_s(), ldap_delete_ext(), ldap_delete_ext_s(), ldap_extended_operation(), ldap_extended_operation_s(), ldap_modify_ext(), ldap_modify_ext_s(), ldap_rename(), ldap_rename_s(), ldap_sasl_bind(), ldap_sasl_bind_s(), ldap_search_ext(), ldap_search_ext_s(), ldap_abandon_ext()	Pass LDAP controls to the server.
ldap_parse_result()	Parse LDAP server controls from results sent from the server.
ldap_get_entry_controls(), ldap_parse_entrychange_control()	Parse an "entry change notification" control from an entry and retrieve information from the control.
ldap_parse_sort_control()	Parse "sorting" controls from results sent from the server.
ldap_control_free()	Free the memory allocated for an LDAPControl structure.
ldap_controls_free()	Free the memory allocated for an array of LDAPControl structures.
ldap_unbind_ext()	Lets you specifically name a server or client control when unbinding from the server.

Function	Description
ldap_is_ldap_url()	Determine if a URL is an LDAP URL.
ldap_url_parse()	Split up an LDAP URL into its components.
ldap_url_search(), ldap_url_search_s(), or ldap_url_search_st()	Perform the search specified by an LDAP URL.
ldap_free_urldesc()	Free the memory allocated for a parsed URL.

Function	Description
ldap_parse_result()	Get the error code resulting from an asynchronous LDAP operation.
ldap_get_lderrno()	Get information about the last error that occurred.
ldap_set_lderrno()	Set information about an error.
ldap_err2string()	Get the error message for a specific error code.
ldapssl_err2string()	Get the error message for a specific SSL error code.

Function	Description
ldap_memfree()	Free memory allocated by an LDAP API function call.
ldap_mods_free()	Free the structures allocated for adding or modifying entries in the directory.
ldap_msgfree()	Free the memory allocated for search results or other LDAP operation results.
ldap_value_free()	Free the memory allocated for the string values of an attribute.
ldap_value_free_len()	Free the memory allocated for the binary values of an attribute (an array of berval structures).
ber_bvfree()	Free the memory allocated for a berval structures.
ldap_getfilter_free()	Free the filter configuration from memory.
ldap_free_urldesc()	Free the memory allocated for a parsed URL.
ber_free()	Free the memory allocated for a BerElement structure.
ldap_control_free()	Free the memory allocated for an LDAPControl structure
ldap_controls_free()	Free the memory allocated for an array of LDAPControl structures.
ldap_free_sort_keylist()	Free the memory allocated for an array of LDAPsortkey structures.

ber	Pointer to the BerElement structure that you want to free.
freebuf	Specifies whether or not to free the buffer in the BerElement structure.

ld	Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.
msgid	Message ID of an LDAP operation.

ld	Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.
msgid	Message ID of the LDAP operation that you want to cancel.
serverctrls	Pointer to an array of LDAPControl structures representing LDAP server controls that apply to this LDAP operation. If you do not want to pass any server controls, specify NULL for this argument.
clientctrls	Pointer to an array of LDAPControl structures representing LDAP client controls that apply to this LDAP operation. If you do not want to pass any client controls, specify NULL for this argument.

ld	Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.
dn	Distinguished name (DN) of the entry to add. With the exception of the leftmost component, all components of the distinguished name (for example, o=organization or c=country) must already exist.
attrs	Pointer to a NULL-terminated array of pointers to LDAPMod structures representing the attributes of the new entry.

ld	Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.
dn	Distinguished name (DN) of the entry used in the comparison.
attr	Attribute type that you want to check the value against.
value	Value that you want to compare against the attribute values.

ld	Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.
result	Chain of search results, represented by the pointer to an LDAPMessage structure.

buf	Buffer to contain the constructed filter.
buflen	Size of the buffer.
pattern	Pattern for the filter.
prefix	Prefix to prepend to the filter (NULL if not used).
suffix	Suffix to append to the filter (NULL if not used).
attr	Replaces %a in the pattern.
value	Replaces %v in the pattern.
valwords	Replaces %vM through %vN in the pattern.

ld	Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.
changetypes	Specifies the types of changes that you want to keep track of. This field can have one or more of the following values (you can OR the values together to specify multiple types): LDAP_CHANGETYPE_ADD specifies that you want to keep track of entries added to the directory. LDAP_CHANGETYPE_DELETE specifies that you want to keep track of entries deleted from the directory. LDAP_CHANGETYPE_MODIFY specifies that you want to keep track of entries that are modified. LDAP_CHANGETYPE_MODDN specifies that you want to keep track of entries that are renamed. LDAP_CHANGETYPE_ANY specifies that you want to keep track of all of the above changes to the directory.
changesonly	Specifies whether or not you want skip the initial search and only get the latest changes as they occur: If non-zero, the initial search is skipped and only entries that have changed after the initial search are returned. If 0, the results of the initial search are returned first.
return_echg_ctls	Specifies whether or not entry change notification controls are included with each entry returned to your client: If non-zero, an entry change notification control is included with each entry. If 0, entry change notification controls are not included with the entries returned from the server.
ctl_iscritical	Specifies whether or not the persistent search control is critical to the search operation: If non-zero, the control is critical to the search operation. If the server does not support persistent searches, the server will return the error LDAP_UNAVAILABLE_CRITICAL_EXTENSION. If 0, the control is not critical to the search operation. Even if the server does not support persistent searches, the search operation is still performed.
ctrlp	Pointer to a pointer to an LDAPControl structure that will be created by this function. When you are done using this control, you should free it by calling the ldap_control_free() function.

ld	Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.
DN	String representing the distinguished name of the entry who's identity the client will be assuming.
ctl_iscritical	Specifies whether the persistent search control is critical to the search operation. For proxy authorization controls, this should be set to a non-zero value. If non-zero, the control is critical to the directory operation. If the server does not support proxy authentication, the server will return an LDAP_UNAVAILABLE_CRITICAL_EXTENSION error. If 0, the control is not critical to the directory operation. Even if the server does not support proxied authorization, the operation is still attempted and the proxied authorization control is ignored.
ctrlp	Pointer to a pointer to an LDAPControl structure that is created by this function. When you are done using this control, you should free it by calling the ldap_control_free() function.

ld	Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.
sortKeyList	Pointer to an array of LDAPsortkey structures that specify the attribute types or matching rules used for sorting and the order (ascending or descending) in which to sort the results.
ctl_iscritical	Specifies whether or not the control is critical to the search operation. This field can have one of the following values: A nonzero value specifies that the control is critical to the operation. 0 specifies that the control is not critical to the operation.
ctrlp	Pointer to a pointer to an LDAPControl structure that will be created by this function. When you are done using this control, you should free it by calling the ldap_control_free() function.

sortKeyList	Pointer to an array of LDAPsortkey structures that specify the attribute types or matching rules used for sorting and the order (ascending or descending) in which to sort the results.
string_rep	String representation of a set of sort keys.

ld	Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.
ldvlistp	Pointer to an LDAPVirtualList structure that specifies the subset of entries that you want retrieved from the server and the selected entry.
ctrlp	Pointer to a pointer to an LDAPControl structure that will be created by this function. When you are done using this control, you should free it by calling the ldap_control_free() function.

dn	Distinguished name (DN) that you want separated into components.
notypes	Specifies whether or not type names in the distinguished name are returned. This parameter can have the following possible values: 0 specifies that type names are returned. A non-zero value specifies that type names are not returned.

dn	Relative distinguished name (RDN) that you want separated into components.
notypes	Specifies whether or not type names in the relative distinguished name are returned. This parameter can have the following possible values: 0 specifies that type names are returned. A non-zero value specifies that type names are not returned.

ld	Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.
requestoid	Object identifier (OID) of the extended operation that you want the server to perform.
requestdata	Pointer to a berval structure containing the data that you want passed to the server to perform the extended operation.
serverctrls	Pointer to an array of LDAPControl structures representing LDAP server controls that apply to this LDAP operation. If you do not want to pass any server controls, specify NULL for this argument.
clientctrls	Pointer to an array of LDAPControl structures representing LDAP client controls that apply to this LDAP operation. If you do not want to pass any client controls, specify NULL for this argument.
msgidp	Pointer to an integer that will be set to the message ID of the LDAP operation. To check the result of this operation, call the ldap_result() and ldap_parse_result() functions.

ld	Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.
entry	Pointer to the LDAPMessage structure representing the entry returned by the ldap_first_entry() or ldap_next_entry() function.
ber	A pointer to a BerElement allocated to keep track of its current position. Pass this pointer to subsequent calls to ldap_next_attribute() to step through the entry's attributes.

ld	Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.
result	Chain of search results, which are represented by a pointer to the LDAPMessage structure.

filename	Name of the map file listing the "unfriendly names" and "friendly names."
uname	"Unfriendly name" for which you want to find the "friendly name."
map	Pointer to the mapping in memory. Initialize this pointer to NULL on the first call, then use the pointer during subsequent calls so that the mapping file does not need to be read again.

ld	Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.
entry	Pointer to an entry in a chain of search results, as returned by the ldap_first_entry() and ldap_next_entry() functions.