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;

char **vals;

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

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

int i;

...

/* 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 );

/* Get the first matching attribute */

a = ldap_first_attribute( ld, e, &ber );

/* Get the values of the attribute */

if ( ( vals = ldap_get_values( ld, e, a ) ) != NULL ) {

  for ( i = 0; vals[i] != NULL; i++ ) {

    /* Print the name of the attribute and each value */

    printf( "%s: %s\n", a, vals[i] );

  }

  /* Free the attribute values from memory when done. */

  ldap_value_free( vals );

}

...

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

ldap_get_values_len()
The ldap_get_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_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_values_len( LDAP *ld,
  LDAPMessage *entry, const char *target );

Parameters
This function has the following parameters:

Table 18-68    ldap_get_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".

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

Example
The following section of code gets the first value of the jpegPhoto attribute and saves the JPEG data to a file.

Code Example 18-24    ldap_get_values_len() code example

#include <ldap.h>

...

LDAP *ld;

LDAPMessage *result, *e;

BerElement *ber;

struct berval photo_data;

struct berval **list_of_photos;

FILE *out;

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

/* Get the value of the jpegPhoto attribute */

if ( ( list_of_photos = ldap_get_values_len( ld, e, "jpegPhoto" ) ) != NULL ) {

  /* Prepare to write the JPEG data to a file */

  if ( ( out = fopen( "photo.jpg", "wb" ) ) == NULL ) {

    perror( "fopen" );

    return( 1 );

  }

  /* Get the first JPEG */

  photo_data = *list_of_photos[0];

  /* Write the JPEG data to a file */

  fwrite( photo_data.bv_val, photo_data.bv_len, 1, out );

  fclose( out );

  /* Free the attribute values from memory when done. */

  ldap_value_free_len( list_of_photos );

}

...

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

ldap_init()
Initializes a session with an LDAP server and returns an LDAP structure that represents the context of the connection to that server.

Syntax
#include <ldap.h>
LDAP * ldap_init( const char *defhost, int defport );

Parameters
This function has the following parameters:

Table 18-69    ldap_init() function parameters

defhost

Space-delimited list of one or more host names (or IP address in dotted notation, such as "141.211.83.36") of the LDAP servers that you want the LDAP client to connect to.
The names can be in hostname:portnumber format (in which case, portnumber overrides the port number specified by the defport argument.

defport

Default port number of the LDAP server. To specify the standard LDAP port (port 389), use LDAP_PORT as the value for this parameter.

Returns
One of the following values:

If successful, returns a pointer to an LDAP structure.

If unsuccessful, returns a NULL.

Description
The ldap_init() function initializes a session with an LDAP server. ldap_init() allocates an LDAP structure containing information about the session, including the host name and port of the LDAP server, preferences for the session (such as the maximum number of entries to return in a search), and the error code of the last LDAP operation performed.
You can specify a list of LDAP servers that you want to attempt to connect to. Your client will attempt to connect to the first LDAP server in the list. If the attempt fails, your client will attempt to connect to the next LDAP server in the list.
You can specify the list of LDAP servers by passing a space-delimited list of the host names as the host argument. For example:
...
LDAP *ld
...
ld = ldap_init( "ld1.netscape.com ld2.netscape.com \
  ld3.netscape.com", LDAP_PORT );
In the example above, the LDAP client will attempt to connect to the LDAP server on ld1.netscape.com, port 389. If that server does not respond, the client will attempt to connect to the LDAP server on ld2.netscape.com, port 389. If that server does not respond, the client will use the server on ld3.netscape.com, port 389.
If any of the servers do not use the default port specified by the defport argument, use the host:port format to specify the server name. For example:
...
LDAP *ld
...
ld = ldap_init( "ld1.netscape.com ld2.netscape.com:38900", \   LDAP_PORT );
In the example above, the LDAP client will attempt to connect to the LDAP server on ld1.netscape.com, port 389. If that server does not respond, the client will attempt to connect to the LDAP server on ld2.netscape.com, port 38900.
Once you initialize a session, you need to call the ldap_simple_bind() or ldap_simple_bind_s() function to connect and authenticate to the LDAP server.
For more information, see "Initializing an LDAP Session."
Note that if you are connecting to a secure LDAP server over SSL, you should be calling the ldapssl_init() function instead. For details, see Chapter 12 "Connecting Over SSL."

Example
The following section of code initializes a session with the LDAP server at ldap.netscape.com:389.

Code Example 18-25    ldap_init() code example

#include <ldap.h>

...

LDAP *ld;

/* Specify the host name of the LDAP server. */

char *ldap_host = "ldap.netscape.com";

/* Because the LDAP server is running on the standard LDAP port (port 389), you can use LDAP_PORT to identify the port number. */

int ldap_port = LDAP_PORT;

...

/* Initialize the session with ldap.netscape.com:389 */

if ( ( ld = ldap_init( ldap_host, ldap_port ) ) == NULL ) {

  perror( "ldap_init" );

  return( 1 );

}

...

/* Subsequent calls that authenticate to the LDAP server. */

...

See Also
ldap_unbind(), ldap_unbind_s().

ldap_init_getfilter()
The ldap_init_getfilter() function reads a valid LDAP filter configuration file (such as ldapfilter.conf) and returns a pointer to an LDAPFiltDesc structure.
For more information, see "Loading a Filter Configuration File."

Syntax
#include <ldap.h>
LDAPFiltDesc * ldap_init_getfilter( char *fname );

Parameters
This function has the following parameters:

Table 18-70    ldap_init_getfilter() function parameters

fname

Name of the LDAP filter configuration file to use.

Returns
One of the following values:

If successful, returns a pointer to an LDAPFiltDesc structure.

If unsuccessful (for example, if there is an error reading the file), returns a NULL.

Example
The following section of code loads the filter configuration file named myfilters.conf into memory.

Code Example 18-26    Loading a filter configuration file

#include <ldap.h>

...

LDAPFiltDesc *lfdp;

char *filter_file = "myfilters.conf";

...

lfdp = ldap_init_getfilter( filter_file );

...

See Also
ldap_init_getfilter_buf(), ldap_getfilter_free().

ldap_init_getfilter_buf()
The ldap_init_getfilter_buf() function reads LDAP filter configuration information from a buffer and returns a pointer to an LDAPFiltDesc structure. The configuration information in the buffer must use the correct syntax, as specified in "Understanding the Configuration File Syntax."
For more information, see "Loading a Filter Configuration File."

Syntax
#include <ldap.h>
LDAPFiltDesc * ldap_init_getfilter_buf(char *buf, long buflen );

Parameters
This function has the following parameters:

Table 18-71    ldap_init_getfilter_buf() function parameters

buf

Buffer containing LDAP filter configuration information.

buflen

Size of the buffer

Returns
One of the following values:

If successful, returns a pointer to an LDAPFiltDesc structure.

If unsuccessful (for example, if there is an error reading the file), returns a NULL.

Example
The following section of code copies the following filter configuration to a buffer in memory.
"ldap-example"
  "@"      " "    "(mail=%v)"            "email address"
            "(mail=%v*)"            "start of email address"
The example uses this buffer to fill an LDAPFiltDesc structure.

Code Example 18-27    ldap_init_getfilter() code example

#include <ldap.h>

...

LDAPFiltDesc *lfdp;

char filtbuf[ 1024 ];

...

/* Create the filter config buffer */

strcpy( filtbuf, "\"ldap-example\"\n" );

strcat( filtbuf, " \"@\"\t\" \"\t\"(mail=%v)\"\t\"email address\"\n" );

strcat( filtbuf, " \t\t\"(mail=%v*)\"\t\"start of email address\"\n" );

lfdp = ldap_init_getfilter( filtbuf, strlen( filtbuf ) );

...

See Also
ldap_init_getfilter(), ldap_getfilter_free().

ldap_is_ldap_url()
The ldap_is_ldap_url() function determines whether or not a URL is an LDAP URL. An LDAP URL is a URL with the protocol set to ldap:// (or ldaps://, if the server is communicating over an SSL connection).
For more information, see "Determining If a URL is an LDAP URL."

Syntax
#include <ldap.h>
int ldap_is_ldap_url( const char *url );

Parameters
This function has the following parameters:

Table 18-72    ldap_is_ldap_url() function parameters

url

The URL that you want to check.

Returns
One of the following values:

1 if the URL is an LDAP URL.

0 if the URL is not an LDAP URL.

Example
The following section of code determines if a URL is an LDAP URL.

Code Example 18-28    ldap_is_ldap_url() code example

#include <ldap.h>

...

char *my_url = "ldap://ldap.netscape.com/o=airius.com";

...

if ( ldap_is_ldap_url( my_url ) != 0 ) {

  printf( "%s is an LDAP URL.\n", my_url );

} else {

  printf( "%s is not an LDAP URL.\n", my_url );

}

...

See Also
ldap_url_parse().

ldap_memcache_destroy()
Frees an LDAPMemCache structure from memory.

Syntax
#include <ldap.h>
void ldap_memcache_destroy( LDAPMemCache *cache );

Parameters
This function has the following parameters:

Table 18-73    ldap_memcache_destroy() function parameters

cache

Pointer to the LDAPMemCache structure that you want freed from memory.

Description
The ldap_memcache_destroy() function frees the specified LDAPMemCache structure from memory. Call this function after you are done working with a cache.

See Also
ldap_memcache_init().

ldap_memcache_flush()
Flushes items from the specified cache.

Syntax
#include <ldap.h>
void ldap_memcache_flush( LDAPMemCache *cache, char *dn,
  int scope );

Parameters
This function has the following parameters:

Table 18-74    ldap_memcache_flush() function parameters

cache

Pointer to the LDAPMemCache structure that you want to flush entries from.

dn

Base DN identifying the search requests that you want flushed from the cache. If the base DN of a search request is within the scope specified by this DN and the scope argument, the search request is flushed from the cache.
If this argument is NULL, the entire cache is flushed.

scope

Scope that (together with the dn argument) identifies the search requests that you want flushed from the cache. If the base DN of the request is within the scope specified by this argument and the dn argument, the request is flushed from the cache.
This argument can have one of the following values:

LDAP_SCOPE_BASE

LDAP_SCOPE_ONELEVEL

LDAP_SCOPE_SUBTREE

Description
The ldap_memcache_flush() function flushes search requests from the cache. If the base DN of a search request is within the scope specified by the dn and scope arguments, the search request is flushed from the cache.
If no DN is specified, the entire cache is flushed.

ldap_memcache_get()
Gets the in-memory cache associated with an LDAP connection handle.

Syntax
#include <ldap.h>
int ldap_memcache_get( LDAP *ld, LDAPMemCache **cachep );

Parameters
This function has the following parameters:

Table 18-75    ldap_memcache_get() function parameters

ld

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

cachep

When you call this function, the function sets this parameter to the pointer to the LDAPMemCache structure associated with the connection handle.

Returns
One of the following values:

LDAP_SUCCESS if the cache for the specified connection handle was retrieved successfully.

LDAP_PARAM_ERROR if an invalid parameter was passed to the function.

Description
The ldap_memcache_get() function gets the cache associated with the specified connection handle (LDAP structure). This cache is used by all search requests made through that connection.
You can call this function if you want to associate a cache with multiple LDAP connection handles. For example, you can call this function to get the cache associated with one connection, then you can call the ldap_memcache_set() function to associate the cache with another connection.

See Also
ldap_memcache_set().

ldap_memcache_init()
Creates an in-memory cache for your LDAP client that you can associate with an LDAP connection.

Syntax
#include <ldap.h>
int ldap_memcache_init( unsigned long ttl, unsigned long size,
  char **baseDNs, struct ldap_thread_fns *thread_fns,
  LDAPMemCache **cachep );

Parameters
This function has the following parameters:

Table 18-76    ldap_memcache_init() function parameters

ttl

The maximum amount of time (in seconds) that an item can be cached.
If 0, there is no limit to the amount of time that an item can be cached.

size

Maximum amount of memory (in bytes) that the cache will consume.
If 0, the cache has no size limit.

baseDNs

An array of the base DN strings representing the base DNs of the search requests you want cached.

If not NULL, only the search requests with the specified base DNs will be cached.

If NULL, all search requests are cached.

thread_fns

An ldap_thread_fns structure specifying the functions that you want used to ensure that the cache is thread-safe.
You should specify this if you have multiple threads that are using the same connection handle and cache.
If you are not using multiple threads, pass NULL for this parameter.

cachep

When you call this function, the function sets this parameter to the pointer to the newly created LDAPMemCache structure.

Returns
One of the following values:

LDAP_SUCCESS if the cache was successfully created.

LDAP_PARAM_ERROR if an invalid parameter was passed to the function

LDAP_NO_MEMORY if memory cannot be allocated.

LDAP_SIZELIMIT_EXCEEDED if the initial size of the cache (specified by the size argument) is too small.

Description
The ldap_memcache_init() function creates an in-memory, client-side cache that you can use to cache search requests.
The function passes back a pointer to an LDAPMemCache structure, which represents the cache. You should call the ldap_memcache_set() function to associate this cache with an LDAP connection handle (an LDAP structure).
On Windows NT, if the ldap_memcache_init() function returns an LDAP_PARAM_ERROR result code, verify that your client is using the version of the nsldap32v30.dll file provided with the Netscape LDAP SDK for C, v4.1. (Some of the Netscape servers, such as the Netscape Directory Server 3.0, install an older version of the nsldap32v30.dll file in the Windows system32 directory.) For example, you may want to copy the nsldap32v30.dll file provided with the Netscape LDAP SDK for C, v4.1 to your client's directory.
The cache uses search criteria as the key to cached items. When you send a search request, the cache checks the search criteria to determine if that request has been cached previously. If the request was cached, the search results are read from the cache.
To flush the cache, call the ldap_memcache_flush() function.
When you are done with the cache, you can free it from memory by calling the ldap_memcache_destroy() function.

See Also
LDAPMemCache, ldap_memcache_set(), , ldap_memcache_update(), ldap_memcache_flush(), ldap_memcache_destroy().

ldap_memcache_set()
Associates an in-memory cache with an LDAP connection handle.

Syntax
#include <ldap.h>
int ldap_memcache_set( LDAP *ld, LDAPMemCache *cache );

Parameters
This function has the following parameters:

Table 18-77    ldap_memcache_set() function parameters

ld

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

cache

Pointer to an LDAPMemCache structure, which represents the cache that you want used for this connection.

Returns
One of the following values:

LDAP_SUCCESS if the cache was successfully associated with the connection handle.

LDAP_PARAM_ERROR if an invalid parameter was passed to the function.

LDAP_SIZELIMIT_EXCEEDED if the size of the cache is too small.

Description
The ldap_memcache_set() function associates a cache that you have created (by calling the ldap_memcache_init() function) with an LDAP connection handle.
After you call this function, search requests made over the specified LDAP connection will use this cache. Note that calling the ldap_unbind() function or the ldap_unbind() function will disassociate the cache from the LDAP connection handle.
You can call this function if you want to associate a cache with multiple LDAP connection handles. For example, you can call the ldap_memcache_get() function to get the cache associated with one connection, then you can call this function associate the cache with another connection.

See Also
ldap_memcache_init(), ldap_memcache_get().

ldap_memcache_update()
Checks the cache for items that have expired and removes them.

Syntax
#include <ldap.h>
void ldap_memcache_update( LDAPMemCache *cache );

Parameters
This function has the following parameters:

Table 18-78    ldap_memcache_update() function parameters

cache

Pointer to an LDAPMemCache structure, which represents the cache that you want to updated.

Description
The ldap_memcache_update() function checks the cache for items that have expired and removes them. This check is typically done as part of the way the cache normally works. You do not need to call this function unless you want to update the cache at this point in time.
This function is only useful in a multithreaded application, since it will not return until the cache is destroyed.

See Also
ldap_memcache_flush().

ldap_memfree()
ldap_memfree() frees memory allocated by an LDAP API function call. For more information, see "Managing Memory."

Syntax
#include <ldap.h>
void ldap_memfree( void *p );

Parameters
This function has the following parameters:

Table 18-79    ldap_memfree() function parameter

p

Pointer to memory used by the LDAP library.

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

Code Example 18-29    ldap_memfree() code example

...

LDAP *ld;

char *dn;

LDAPMessage *entry;

...

/* Get the distinguished name (DN) for an entry */

dn = ldap_get_dn( ld, entry );

...

/* When you are finished working with the DN, free the memory allocated for the DN */

ldap_memfree( dn );

...

See Also
ldap_free_friendlymap(), ldap_free_urldesc(), ldap_msgfree(), ldap_value_free(), ldap_value_free_len().

ldap_modify()
Modifies an existing entry in 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_modify_ext() instead.

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

Parameters
This function has the following parameters:

Table 18-80    ldap_modify() 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 modify.

mods

Pointer to a NULL-terminated array of pointers to LDAPMod structures representing the attributes that you want to modify.

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

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

Example
The following section of code uses the asynchronous ldap_modify() function to modify the entry for "Barbara Jensen" in the directory. The example makes the following changes to the entry:

Adds the homePhone attribute.

Changes the telephoneNumber attribute.

Removes the facsimileTelephoneNumber attribute.

Code Example 18-30    ldap_modify() code example

#include <ldap.h>

...

LDAP *ld;

LDAPMod *list_of_attrs[4];

LDAPMod attribute1, attribute2, attribute3;

LDAPMessage *result;

int msgid, rc;

struct timeval tv;

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

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

/* Values to add or change */

char *homePhone_values[] = { "555-1212", NULL };

char *telephoneNumber_values[] = { "869-5309", NULL };

...

/* Specify each change in separate LDAPMod structures */

attribute1.mod_type = "homePhone";

attribute1.mod_op = LDAP_MOD_ADD;

attribute1.mod_values = homePhone_values;

attribute2.mod_type = "telephoneNumber";

attribute2.mod_op = LDAP_MOD_REPLACE;

attribute2.mod_values = telephoneNumber_values;

attribute3.mod_type = "facsimileTelephoneNumber";

attribute3.mod_op = LDAP_MOD_DELETE;

attribute3.mod_values = NULL;

/* NOTE: When removing entire attributes, you need to specify a NULL value for the mod_values field. */

/* 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 to wait for the "modify" operation */

tv.tv_sec = tv.tv_usec = 0;

/* Change the entry */

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

  ldap_perror( ld, "ldap_modify" );

  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_modify" );

...

See Also
ldap_modify_ext().

ldap_modify_ext()
Modifies an existing entry in the directory asynchronously.

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

Parameters
This function has the following parameters:

Table 18-81    ldap_modify_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 modify.

mods

Pointer to a NULL-terminated array of pointers to LDAPMod structures representing the attributes that you want to modify.

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_modify_ext() modifies an entry in the directory asynchronously.
This function is a new version of the ldap_modify() function. If you are writing a new LDAP client, you should call this function instead of ldap_modify().
To make changes to an 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 entry that you want to modify.

A set of attributes for the new entry.

Create an LDAPMod structure for change that you want to make to an attribute. Create an array of these LDAPMod structures and pass the array as the mods argument.

For information on using the LDAPMod structure to specify a change, see LDAPMod.

The function ldap_modify_ext() is asynchronous; it does not directly return results. If you want the results to be returned directly by the function, call the synchronous function ldap_modify_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 modify 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 modify operation, see the result code documentation for the ldap_modify_ext_s() function.
For more information on modifying entries in the directory, see "Modifying an Entry."

Example
See the example under "Example: Modifying an Entry in the Directory (Asynchronous)."

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

ldap_modify_ext_s()
Modifies an existing entry in the directory synchronously.

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

Parameters
This function has the following parameters:

Table 18-82    ldap_modify_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 modify.

mods

Pointer to a NULL-terminated array of pointers to LDAPMod structures for the attributes you want modified.

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 modify 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 modify 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.

An unknown modification operator (other that LDAP_MOD_ADD, LDAP_MOD_DELETE, and LDAP_MOD_REPLACE) is specified in the request.

The modification operator is LDAP_MOD_ADD and no values are specified.

No modifications are specified.

LDAP_CONSTRAINT_VIOLATION may be sent by the Directory Server if your client is attempting to modify the userpassword attribute in the following situations:

The server is configured to require a minimum password length and the new value of the userpassword attribute is shorter than the minimum length.

The server is configured to keep track of previous passwords, and the new value of the userpassword attribute is the same as a previous value of that attribute.

The new 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_UNWILLING_TO_PERFORM may be sent by the Directory Server in the following situations:

Your client is attempting to modify the aci attribute and an error occurs.

The value of the userpassword attribute needs to be changed. (The password has expired.)

Your client is attempting to add attributes to the configuration DSE (DSA-specific entry, where DSA stands for Directory-Specific Agent).

Your client is attempting to replace attributes in the schema DSE.

The server's database is read-only.

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_NO_SUCH_ATTRIBUTE may be sent by the Directory Server if the attribute that you want to modify (add, replace, or delete) does not exist.

LDAP_INVALID_SYNTAX may be sent by the Directory Server if your client is modifying the schema DSE and no object class or attribute type is specified.

LDAP_NO_SUCH_OBJECT may be sent by the Directory Server if the entry that you want modified does not exist.

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 modify the entry.

LDAP_TYPE_OR_VALUE_EXISTS may be sent by the Directory Server if your client is attempting to add an attribute to an entry and the attribute values already exist in the entry.

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

LDAP_NOT_ALLOWED_ON_RDN may be sent by the Directory Server if the modified entry no longer contains attributes for each DN component.
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_modify_ext_s() modifies an entry in the directory synchronously.
This function is a new version of the ldap_modify_s() function. If you are writing a new LDAP client, you should call this function instead of ldap_modify_s().
To make changes to an 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 entry that you want to modify.

A set of attributes for the new entry.

Create an LDAPMod structure for change that you want to make to an attribute. Create an array of these LDAPMod structures and pass the array as the mods argument.

For information on using the LDAPMod structure to specify a change, see LDAPMod.

ldap_modify_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_modify_ext() instead. (For more information on asynchronous and synchronous functions, see "Calling Synchronous and Asynchronous Functions.")
For more information on modifying entries in the directory, see "Modifying an Entry."

Example
See the example under "Example: Modifying an Entry in the Directory (Synchronous)."

See Also
ldap_modify_ext(), LDAPMod.

ldap_modify_s()
Modifies an existing entry in 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_modify_ext_s() instead.

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

Parameters
This function has the following parameters:

Table 18-83    ldap_modify_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 modify.

mods

Pointer to a NULL-terminated array of pointers to LDAPMod structures for the attributes you want modified.

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

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

Example
The following section of code uses the synchronous ldap_modify_s() function to makes the following changes to the "Barbara Jensen" entry:

Adds the homePhone attribute.

Changes the telephoneNumber attribute.

Removes the facsimileTelephoneNumber attribute.

Code Example 18-31    ldap_modify_s() code example

#include <ldap.h>

...

LDAP *ld;

LDAPMod *list_of_attrs[4];

LDAPMod attribute1, attribute2, attribute3;

LDAPControl **srvrctrls, **clntctrls;

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

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

/* Values to add or change */

char *homePhone_values[] = { "555-1212", NULL };

char *telephoneNumber_values[] = { "869-5309", NULL };

...

/* Specify each change in separate LDAPMod structures */

attribute1.mod_type = "homePhone";

attribute1.mod_op = LDAP_MOD_ADD;

attribute1.mod_values = homePhone_values;

attribute2.mod_type = "telephoneNumber";

attribute2.mod_op = LDAP_MOD_REPLACE;

attribute2.mod_values = telephoneNumber_values;

attribute3.mod_type = "facsimileTelephoneNumber";

attribute3.mod_op = LDAP_MOD_DELETE;

attribute3.mod_values = NULL;

/* NOTE: When removing entire attributes, you need to specify a NULL value for the mod_values or mod_bvalues field. */

/* 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;

...

/* Change the entry */

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

  ldap_perror( ld, "ldap_modify_s" );

  return( 1 );

}

...

See Also
ldap_modify_ext_s().

ldap_modrdn()
The ldap_modrdn() function is a deprecated function. Use the ldap_rename() or ldap_modrdn2() functions instead.

ldap_modrdn_s()
The ldap_modrdn_s() function is a deprecated function. Use the ldap_rename_s() or ldap_modrdn2_s() functions instead.

ldap_modrdn2()
Changes the relative distinguished name (RDN) of an entry in 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_rename() instead.

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

Parameters
This function has the following parameters:

Table 18-84    ldap_modrdn2() 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 modify.

newrdn

New relative distinguished name (RDN) to assign to the entry.

deleteoldrdn

If this is a non-zero value, the old RDN is not retained as a value in the modified entry. If 0, the old RDN is retained as an attribute in the modified entry.

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

Description
The ldap_modrdn2() function modifies the relative distinguished name (RDN) of an entry in a directory and lets you specify whether or not the old RDN is retained as an attribute of the entry.
A newer version of this function, ldap_rename(), is available in this release of the LDAP API. ldap_modrdn2() (the older version of the function) is included only for backward-compatibility. If you are writing a new LDAP client, use ldap_rename() instead of ldap_modrdn2().
If you want more information on ldap_modrdn2(), refer to the LDAP C SDK 1.0 Programmer's Guide.

Example
The following section of code uses the asynchronous ldap_modrdn2() function to change the RDN of an entry from "uid=bjensen" to "uid=babs". The code removes the existing RDN "bjensen" from the uid attribute of the entry.

Code Example 18-32    ldap_modrdn2() code example

...

LDAP *ld;

LDAPMessage *result;

int msgid, rc;

struct timeval tv;

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

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

/* New relative distinguished name (RDN) of the entry */

char *rdn = "uid=babs";

...

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

tv.tv_sec = tv.tv_usec = 0;

/* Rename the entry */

if ( ( msgid = ldap_modrdn2( ld, dn, rdn, 1 ) ) == -1 ) {

  ldap_perror( ld, "ldap_modrdn2" );

  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_modrdn2" );

...

See Also
ldap_rename().

ldap_modrdn2_s()
Changes the relative distinguished name (RDN) of an entry in 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_rename_s() instead.

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

Parameters
This function has the following parameters:

Table 18-85    ldap_modrdn2_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 modify.

newrdn

New relative distinguished name (RDN) to assign to the entry.

deleteoldrdn

If this is a non-zero value, the old RDN is not retained as a value in the modified entry. If 0, the old RDN is retained as an attribute in the modified entry.

Returns
For a list of possible result codes, see the result code documentation for the ldap_rename_s() function.

Description
The ldap_modrdn2_s() function modifies the relative distinguished name (RDN) of an entry in a directory and lets you specify whether or not the old RDN is retained as an attribute of the entry.
A newer version of this function, ldap_rename_s(), is available in this release of the LDAP API. ldap_modrdn2_s() (the older version of the function) is included only for backward-compatibility. If you are writing a new LDAP client, use ldap_rename_s() instead of ldap_modrdn2_s().
If you want more information on ldap_modrdn2_s(), refer to the LDAP C SDK 1.0 Programmer's Guide.

Example
The following section of code uses the synchronous ldap_modrdn2_s() function to change the RDN of an entry from "uid=bjensen" to "uid=babs". The code removes the existing RDN "babs" from the uid attribute of the entry.

Code Example 18-33    ldap_modrdn2_s() code example

...

LDAP *ld;

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

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

/* New relative distinguished name (RDN) of the entry */

char *rdn = "uid=babs";

...

/* Rename the entry */

if ( ldap_modrdn2_s( ld, dn, rdn, 1 ) != LDAP_SUCCESS ) {

  ldap_perror( ld, "ldap_modrdn2_s" );

  return( 1 );

}

...

See Also
ldap_rename_s().

ldap_mods_free()
The ldap_mods_free() function frees the LDAPMod structures that you've allocated to add or modify entries. You need to call this function only if you've allocated memory for these structures yourself.

Syntax
#include <ldap.h>
void ldap_mods_free( LDAPMod **mods, int freemods );

Parameters
This function has the following parameters:

Table 18-86    ldap_mods_free() function parameters

mods

Pointer to a NULL-terminated array of pointers to LDAPMod structures.

freemods

If this is a non-zero value, frees the array of pointers as well as the LDAPMod structures. If 0, just frees the LDAPMod structures.

Example
The following example allocates memory for LDAPMod structures and frees them when done.

Code Example 18-34    ldap_mods_free() code example

#include <ldap.h>

...

LDAP *ld;

char *dn;

int i, msgid;

LDAPMod **mods;

...

/* Construct the array of values to add */

mods = ( LDAPMod ** ) malloc(( NMODS + 1 ) * sizeof( LDAPMod * ));

if ( mods == NULL ) {

  fprintf( stderr, "Cannot allocate memory for mods array\n" );

}

for ( i = 0; i < NMODS; i++ ) {

  if (( mods[ i ] = ( LDAPMod * ) malloc( sizeof( LDAPMod ))) == NULL) {

    fprintf( stderr, "Cannot allocate memory for mods element\n" );

    exit( 1 );

  }

}

...

/* Code for filling the structures goes here. */

...

/* Initiate the add operation */

if (( msgid = ldap_add( ld, dn, mods )) < 0 ) {

  ldap_perror( ld, "ldap_add" );

  ldap_mods_free( mods, 1 );

  return( 1 );

}

...

ldap_msgfree()
The ldap_msgfree() function frees the memory allocated for a result by ldap_result() or ldap_search_s(). For more information, see "Freeing the Results of a Search."

Syntax
#include <ldap.h>
int ldap_msgfree( LDAPMessage *lm );

Parameters
This function has the following parameters:

Table 18-87    ldap_msgfree() function parameters

lm

ID of the result to be freed from memory.

Returns
One of the following values:

If successful, returns the type of result freed. Possible types of results are listed below.

Table 18-88    ldap_msgfree() return codes

LDAP_RES_BIND

Results from an LDAP bind operation.

LDAP_RES_SEARCH_ENTRY

Entry returned by an LDAP search operation.

LDAP_RES_SEARCH_RESULT

Results from an LDAP search operation.

LDAP_RES_MODIFY

Results from an LDAP modify operation.

LDAP_RES_ADD

Results from an LDAP add operation.

LDAP_RES_DELETE

Results from an LDAP delete operation.

LDAP_RES_MODRDN, LDAP_RES_RENAME

Results from an LDAP modify DN operation.

LDAP_RES_COMPARE

Results from an LDAP compare operation.

LDAP_RES_SEARCH_REFERENCE

Search reference returned by an LDAP search operation.

LDAP_RES_EXTENDED

Results from an LDAP extended operation.

LDAP_RES_ANY

Results from any asynchronous LDAP operation.

If unsuccessful, returns the LDAP error code for the operation. (See Chapter 19 "Result Codes" for a complete listing.)

If the operation times out, returns LDAP_SUCCESS.

Example
The following example frees the results of a search.

Code Example 18-35    ldap_msgfree() code example

#include <ldap.h>

...

LDAP *ld;

LDAPMessage *result;

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

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

char *get_attr[] = { "cn", "mail", NULL };

...

/* Search the directory */

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

  ldap_perror( ld, "ldap_search_s" );

  return( 1 );

}

...

/* Free the results when done */

ldap_msgfree( result );

...

See Also
ldap_result(), ldap_search_s().

ldap_msgid()
The ldap_msgid() function determines the message ID of a result obtained by calling ldap_result() or ldap_search_s().

Syntax
#include <ldap.h>
int ldap_msgid( LDAPMessage *lm );

Parameters
This function has the following parameters:

Table 18-89    ldap_msgid() function parameters

lm

ID of the result to check.

Returns
One of the following values:

The message ID if successful.

-1 if unsuccessful.

Example
The following example prints the message ID from the result obtained from a synchronous LDAP search operation.

Code Example 18-36    ldap_msgid() code example

#include <ldap.h>

...

LDAP *ld;

LDAPMessage *result;

...

/* Perform a search */

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 and print the message ID */

if ( ldap_msgid( result ) != -1 ) {

  printf( "Message ID: %d\n" );

} else {

  printf( "An error occurred.\n" );

}

...

See Also
ldap_msgtype(), ldap_result(), ldap_search_s().

ldap_msgtype()
The ldap_msgtype() function determines the type of result obtained by calling ldap_result() or ldap_search_s().

Syntax
#include <ldap.h>
int ldap_msgtype( LDAPMessage *lm );

Parameters
This function has the following parameters:

Table 18-90    ldap_msgtype() function parameters

lm

ID of the result to check.

Returns
One of the following values:

LDAP_RES_BIND indicates that the LDAPMessage structure contains the result of an LDAP bind operation.

LDAP_RES_SEARCH_ENTRY indicates that the LDAPMessage structure contains an entry found during an LDAP search operation.

LDAP_RES_SEARCH_REFERENCE indicates that the LDAPMessage structure contains an LDAPv3 search reference (a referral to another LDAP server) found during an LDAP search operation.

LDAP_RES_SEARCH_RESULT indicates that the LDAPMessage structure contains the result of an LDAP search operation.

LDAP_RES_MODIFY ndicates that the LDAPMessage structure contains the result of an LDAP modify operation.

LDAP_RES_ADD indicates that the LDAPMessage structure contains the result of an LDAP add operation.

LDAP_RES_DELETE indicates that the LDAPMessage structure contains the result of an LDAP delete operation.

LDAP_RES_MODRDN or LDAP_RES_RENAME indicates that the LDAPMessage structure contains the result of an LDAP modify DN operation.

LDAP_RES_COMPARE indicates that the LDAPMessage structure contains the result of an LDAP compare operation.

LDAP_RES_EXTENDED indicates that the LDAPMessage structure contains the result of an LDAPv3 extended operation.

-1 indicates that the lm argument is not a pointer to a valid LDAPMessage structure.

Example
The following example prints the message type for a result obtained from a synchronous LDAP search operation.

Code Example 18-37    ldap_msgtype() code example

#include <ldap.h>

...

LDAP *ld;

LDAPMessage *result;

int msgtype;

...

/* Perform a search */

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 and print the message type */

msgtype = ldap_msgtype( result );

if ( msgtype != -1 ) {

  printf( "Message type: %d\n", msgtype );

} else {

  printf( "An error occurred.\n" );

}

...

See Also
ldap_msgid(), ldap_result(), ldap_search_s().

ldap_multisort_entries()
The ldap_multisort_entries() function sorts a chain of entries retrieved from an LDAP search call (ldap_search_s() or ldap_result()) by a specified set of attributes in the entries (or by DN if you don't specify a set of attributes).
For additional information, see "Sorting the Search Results."

Syntax
#include <ldap.h>
int ldap_multisort_entries( LDAP *ld, LDAPMessage **chain,
  char **attr, LDAP_CMP_CALLBACK *cmp );

Parameters
This function has the following parameters:

Table 18-91    ldap_multisort_entries() function parameters

ld

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

chain

Chain of entries returned by the ldap_result() or ldap_search_s() function.

attr

Array of attributes to use when sorting the results. If NULL, results are sorted by distinguished name (DN).

cmp

Comparison function used when sorting the values.

Returns
One of the following values:

0 if successful.

-1 if memory cannot be allocated by this function. (The error code LDAP_NO_MEMORY is set in the LDAP structure. To get the error code, call the ldap_get_lderrno() function.)

LDAP_PARAM_ERROR if an invalid parameter was passed to the function

Example
The following section of code sorts entries first by the roomNumber attribute, then by the telephoneNumber attribute.

Code Example 18-38    ldap_multisort_entries() code example

#include <stdio.h>

#include <string.h>

#include <ldap.h>

...

LDAP *ld;

LDAPMessage *result;

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

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

char *attrs[3];

attrs[0] = "roomNumber";

attrs[1] = "telephoneNumber";

attrs[2] = NULL;

...

/* 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 );

}

/* Sort the results, using strcasecmp */

if ( ldap_multisort_entries( ld, &result, attrs, strcasecmp ) != LDAP_SUCCESS ) {

  ldap_perror( ld, "ldap_multisort_entries" );

  return( 1 );

}

...

See Also
ldap_result(), ldap_search_s(), ldap_sort_entries().

ldap_next_attribute()
The ldap_next_attribute() function returns the name of the next attribute in a entry returned by ldap_first_entry() or ldap_next_entry().
The ldap_first_attribute() function returns a pointer to a BerElement. You use this pointer with ldap_next_attribute() to iterate through the list of elements. After the last call to ldap_next_element(), you should free the BerElement pointer using ldap_ber_free(). When calling ldap_ber_free(), make sure to specify that the buffer is not freed (pass 0 for the freebuf parameter).
For more information, see "Getting Attributes from an Entry."

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

Parameters
This function has the following parameters:

Table 18-92    ldap_next_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 name of the next attribute in an entry. When you are done using this data, you should free the memory by calling the ldap_memfree() function.

If no more attributes exist in the entry, returns a NULL.

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
See the example under ldap_first_attribute().

See Also
ldap_first_attribute(), ldap_getfirstfilter(), ldap_next_entry().

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

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

Parameters
This function has the following parameters:

Table 18-93    ldap_next_entry() 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 in a chain of search results.

Returns
One of the following values:

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

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

Description
The ldap_next_entry() function returns a pointer to the LDAPMessage structure representing the next directory entry in a chain of search results. Messages containing directory entries have the type LDAP_RES_SEARCH_ENTRY.
You can use this function in conjunction with the ldap_first_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.
For more information, see "Iterating Through a Chain of Results."

See Also
ldap_first_entry().

ldap_next_message()
Returns a pointer to the next LDAPMessage structure in a chain of search results.

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

Parameters
This function has the following parameters:

Table 18-94    ldap_next_message() function parameters

ld

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

msg

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

Returns
One of the following values:

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

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

Description
The ldap_next_message() function returns a pointer to the next LDAPMessage structure in a chain of search results.
You can use this function in conjunction with the ldap_first_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).
For more information, see "Iterating Through a Chain of Results."

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

See Also
ldap_first_message().

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

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

Parameters
This function has the following parameters:

Table 18-95    ldap_next_reference() function parameters

ld

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

msg

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

Returns
One of the following values:

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

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

Description
The ldap_next_reference() function returns a pointer to the LDAPMessage structure representing the next search reference in a chain of search results. Messages containing search references have the type LDAP_RES_SEARCH_REFERENCE.
You can use this function in conjunction with the ldap_first_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.
For more information, see "Iterating Through a Chain of Results."

See Also
ldap_first_reference().

ldap_parse_entrychange_control()
Examines a list of controls returned from a persistent search operation, retrieves an entry change control, and parses that control for information (such as the type of change made to the entry and the change number).
This function implements an extension to the LDAPv3 protocol. Entry change notification 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_parse_entrychange_control( LDAP *ld,
  LDAPControl **ctrls, int *chgtypep, char **prevdnp,
  int *chgnumpresentp, long *chgnump );

Parameters
This function has the following parameters:

Table 18-96    ldap_parse_entrychange_control() function parameters

ld

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

ctrlp

An array of controls returned by the server. You obtain these controls by calling the ldap_get_entry_controls() function on an entry returned by the server.

changetypes

Pointer to an integer specifying the type of change made to the entry. This field can have one of the following values:

LDAP_CHANGETYPE_ADD specifies that the entry was added to the directory.

LDAP_CHANGETYPE_DELETE specifies that the entry was deleted from the directory.

LDAP_CHANGETYPE_MODIFY specifies that the entry was modified.

LDAP_CHANGETYPE_MODDN specifies that the DN or RDN of the entry was changed (a modify RDN or modify DN operation was performed).

prevdnp

Pointer to the previous DN of the entry, if the changetypes argument is LDAP_CHANGETYPE_MODDN. (If the changetypes argument has a different value, this argument is set to NULL.)
When done, you can free this by calling the ldap_memfree() function.

chgnumpresentp

Pointer to an integer specifying whether or not to the change number is included in the control. The parameter can have the following possible values:

0 specifies that the change number is not included.

A non-zero value specifies that the change number is included and is available as the chgnump argument.

chgnump

Pointer to the change number identifying the change made to the entry, if chgnumpresentp points to a non-zero value.

Returns
One of the following values:

LDAP_SUCCESS if successful.

LDAP_NO_MEMORY if memory cannot be allocated.

LDAP_DECODING_ERROR if an error occurred when BER-decoding the control.

Description
Call the ldap_parse_entrychange_control() function to parse an entry returned from a persistent search operation and retrieve an entry change control.
Call this function after receiving an entry from a persistent search and retrieving the controls from the entry (call ldap_get_entry_controls() to get the controls).

See Also
ldap_create_persistentsearch_control(), ldap_get_entry_controls().

ldap_parse_extended_result()
Parses the results of an LDAP extended operation and retrieves the OID and data returned by the server.
This function implements an extension to the LDAPv3 protocol. Extended operations might not be supported on all LDAP servers. Call this function when interacting with LDAP servers that support this LDAPv3 extension. See "Determining the Extended Operations Supported" to determine if the server supports extended operations.

Syntax
#include <ldap.h>
int ldap_parse_extended_result( LDAP *ld, LDAPMessage *res,
  char **retoidp, struct berval **retdatap, int freeit );

Parameters
This function has the following parameters:

Table 18-97    ldap_parse_extended_result() function parameters

ld

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

res

Pointer to the LDAPMessage structure containing the results of an LDAP operation.

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.

freeit

Specifies whether or not to free the results of the operation (the LDAPMessage structure specified by the res argument). The parameter can have the following possible values:

0 specifies that the result should not be freed.

A non-zero value specifies that the result should be freed.

Returns
One of the following values, which indicates the result of parsing the server's response (this value does not apply to the LDAP extended operation itself):

LDAP_SUCCESS if successful.

LDAP_PARAM_ERROR if any of the arguments are invalid.

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.")

Description
After you call the ldap_extended_operation() function and the ldap_result() function, you can pass the results to the ldap_parse_extended_result() function. ldap_parse_extended_result() parses the server's response to an extended operation.
This function gets the following data from the server's response:

The extended operation OID received from the server is passed back as the retoidp argument.

The data received from the server is passed back in the berval structure as the retdatap argument.

The LDAP result code for the LDAP extended operation is placed in the ld structure. You can get the result code by calling the ldap_get_lderrno() function.

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

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.

See Also
ldap_extended_operation(), ldap_get_lderrno().

ldap_parse_reference()
Parses search references from the results received from an LDAP server.
Search references are part of the LDAPv3 protocol. When calling this function, make sure that you are working with a server that supports the LDAPv3 protocol.

Syntax
#include <ldap.h>
int ldap_parse_reference( LDAP *ld, LDAPMessage *ref,
  char ***referralsp, LDAPControl ***serverctrlsp,
  int freeit );

Parameters
This function has the following parameters:

Table 18-98    ldap_parse_reference() function parameters

ld

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

ref

Pointer to an LDAPMessage structure of the type LDAP_RES_SEARCH_REFERENCE.

referralsp

Pointer to an array of strings representing the referrals found by an LDAP search operation and returned by the server (applicable only if the LDAP operation was a search operation).
When done, you can free this by calling the ldap_value_free() function.

serverctrlsp

Pointer to an array of LDAPControl structures, which represent the LDAPv3 server controls returned by the server.
When done, you can free this by calling the ldap_controls_free() function.

freeit

Specifies whether or not to free the results of the operation (the LDAPMessage structure specified by the res argument). The parameter can have the following possible values:

0 specifies that the result should not be freed.

A non-zero value specifies that the result should be freed.

Returns
One of the following values:

LDAP_SUCCESS if the referral URLs were retrieved successfully.

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_parse_reference() function parses the referral URLs from an LDAPMessage structure of the type LDAP_RES_SEARCH_REFERENCE.

ldap_parse_result()
Parses the results of an LDAP operation received from an LDAP server.

Syntax
#include <ldap.h>
int ldap_parse_result( LDAP *ld, LDAPMessage *res,
  int *errcodep, char **matcheddnp, char **errmsgp,
  char ***referralsp, LDAPControl ***serverctrlsp, int freeit);

Parameters
This function has the following parameters:

Table 18-99    ldap_parse_result() function parameters

ld

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

res

Pointer to the LDAPMessage structure containing the results of an LDAP operation.

errcodep

Pointer to the LDAP result code specifying the result of the operation.

matcheddnp

Pointer to a string specifying the portion of a DN that finds an existing entry (in cases where the server cannot find the entry specified by a DN). See "Receiving the Portion of the DN Matching an Entry" for details.
When done, you can free this by calling the ldap_memfree() function.

errmsgp

Pointer to an additional error message string sent from the server.
When done, you can free this by calling the ldap_memfree() function.

referralsp

Pointer to an array of strings representing the referrals returned by the server.
When done, you can free this by calling the ldap_value_free() function.

serverctrlsp

Pointer to an array of LDAPControl structures, which represent the LDAPv3 server controls returned by the server.
When done, you can free this by calling the ldap_controls_free() function.

freeit

Specifies whether or not to automatically free the results of the operation (the LDAPMessage structure specified by the res argument). The parameter can have the following possible values:

0 specifies that the result should not be freed.

A non-zero value specifies that the result should be freed.

Returns
One of the following values:

LDAP_SUCCESS if the results were parsed successfully.

LDAP_NO_RESULTS_RETURNED if the specified LDAPMessage structure does not contain the result of an LDAP operation (for example, if it contains an entry, search reference, or chain of search results instead of the result of an LDAP operation).

LDAP_MORE_RESULTS_TO_RETURN if the result in the LDAPMessage structure is part of a chain of results and the last result is not included.

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_parse_result() function parses the results of an LDAP operation (received from an LDAP server) and retrieves the following information:

The LDAP result code that indicates the result of the LDAP operation (errcodep).

An additional error message (optional) sent by the server (errmsgp).

The portion of the DN that finds an entry, if the server is unable to find an entry from a DN that you specify (matcheddnp) (see "Receiving the Portion of the DN Matching an Entry" for details).

A set of referrals, if the server does not contain the entries that you've specified and if the server is configured to refer clients to other servers (referralsp).

a set of server response controls that are relevant to the operation (serverctrlsp).
Calling this function creates an array of LDAPControl structures that you can pass to subsequent API functions (such as the ldap_parse_sort_control() function).
Note that this function is not intended to be used to parse entries and search references. (Use the ldap_msgtype() function to determine the type of result contained in the LDAPMessage structure.)

If the result is an entry returned as a search result, call the ldap_first_entry() function to retrieve the entry.

If the result is a search reference, call the ldap_parse_reference() function to retrieve the reference.

Example
See the examples in the following sections:

For an example of parsing the results of an asynchronous LDAP add operation, see "Example: Adding an Entry to the Directory (Asynchronous)."

For an example of parsing the results of an asynchronous LDAP modify operation, see "Example: Modifying an Entry in the Directory (Asynchronous)."

For an example of parsing the results of an asynchronous LDAP delete operation, see "Example: Deleting an Entry from the Directory (Asynchronous)."

For an example of parsing the results of an asynchronous LDAP modify DN operation, see "Example: Renaming an Entry in the Directory (Asynchronous)."

For an example of parsing the results of an asynchronous LDAP search operation, see "Example: Searching the Directory (Asynchronous)."

For an example of parsing the results of an asynchronous LDAP bind operation, see "Performing an Asynchronous Authentication Operation."

See Also
ldap_result().

ldap_parse_sasl_bind_result()
Parses the results of an LDAP SASL bind operation and retrieves data (such as a challenge) returned by the server. This function also gets the LDAP result code for the SASL bind operation and sets it in the ld structure. (You can retrieve it by calling the ldap_get_lderrno() function.)
SASL authentication is part of the LDAPv3 protocol. When calling this function, make sure that you are working with a server that supports the LDAPv3 protocol.

Syntax
#include <ldap.h>
int ldap_parse_sasl_bind_result( LDAP *ld, LDAPMessage *res,
  struct berval **servercredp, int freeit );

Parameters
This function has the following parameters:

Table 18-100    ldap_parse_sals_bind_result() function parameters

ld

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

res

Pointer to the LDAPMessage structure containing the results of an LDAP operation.

servercredp

Pointer to a pointer to an berval structure containing any challenge or credentials returned by the server.
When done, you can free this by calling the ber_bvfree() function.

freeit

Specifies whether or not to free the results of the operation (the LDAPMessage structure specified by the res argument). The parameter can have the following possible values:

0 specifies that the result should not be freed.

A non-zero value specifies that the result should be freed.

Returns
One of the following values, which indicates the result of parsing the server's response (this value does not apply to the SASL bind operation itself):

LDAP_SUCCESS if the results were parsed successfully.

LDAP_PARAM_ERROR if an invalid parameter was passed to the function.

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.")

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

Description
After you call the ldap_sasl_bind() function and the ldap_result() function, you can pass the results to the ldap_parse_sasl_bind_result() function parse the results from the server.
This function gets the following data from the server's response:

The challenge or credentials sent back from the server are passed back in the berval structure as the servercredp argument.

The LDAP result code for the SASL bind operation is placed in the ld structure. You can get the result code by calling the ldap_get_lderrno() function.

For a list of possible result codes for an LDAP SASL bind operation, see the result code documentation for the ldap_sasl_bind_s() function.

If the result code is LDAP_SASL_BIND_IN_PROGRESS, you can call ldap_sasl_bind() again to send a response to the server's challenge and call ldap_result() and ldap_parse_sasl_bind_result() again to get the next challenge from the server.
The LDAP server must support authentication through SASL mechanisms. The Directory Server supports a server plug-in interface that you can use to add SASL support to the server. For details, see the iPlanet Directory Server Programmer's Guide.

See Also
ldap_sasl_bind(), ldap_get_lderrno().

ldap_parse_sort_control()
Parses the result returned from a search operation that used a server control for sorting search results.
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_parse_sort_control( LDAP *ld, LDAPControl **ctrls,
  unsigned long *result, char **attribute );

Parameters
This function has the following parameters:

Table 18-101    ldap_parse_sort_control() function parameters

ld

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

ctrls

An array of controls returned by the server. You obtain these controls by calling the ldap_parse_result() function on the set of results returned by the server.

result

Pointer to the sort control result code retrieved by this function.

attribute

If the sorting operation fails, the function sets this to point to the name of the attribute that caused the failure.
When done, you can free this by calling the ldap_memfree() function.

Returns
One of the following values:

LDAP_SUCCESS if successful.

LDAP_PARAM_ERROR if an invalid parameter was passed to the function (for example, if the LDAP connection is not valid).

LDAP_NO_MEMORY if memory cannot be allocated to decode the control returned by the server.

LDAP_DECODING_ERROR if an error occurred when BER decoding the control.

LDAP_CONTROL_NOT_FOUND if no control can be found in the response returned from the server.

Description
Call the ldap_parse_sort_control() function as part of the process of retrieving sorted search results from a server.
Call this function after receiving the results (call ldap_result() to get the results) and parsing the server controls from the results (call ldap_parse_result() to get the controls from the results).

See Also
ldap_create_sort_control().

ldap_parse_virtuallist_control()
Parses the result returned from a search operation that used a server control for virtual list views.
This function implements an extension to the LDAPv3 protocol. A virtual list view 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_parse_virtuallist_control( LDAP *ld,
  LDAPControl **ctrls, unsigned long *target_posp,
  unsigned long *list_sizep, int *errcodep );

Parameters
This function has the following parameters:

Table 18-102    ldap_parse_virtuallist_control() function parameters

ld

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

ctrls

An array of controls returned by the server. You obtain these controls by calling the ldap_parse_result() function on the set of results returned by the server.

target_posp

Pointer to an unsigned long that is set by the function. The function sets this to the index or offset of the selected entry in the list of entries.

list_sizep

Pointer to an unsigned long that is set by the function. The function sets this to the number of entries in the total number of entries in the entire list (not just the subset).

errcodep

Pointer to the sort control result code retrieved by this function.

Returns
One of the following values:

LDAP_SUCCESS if successful.

LDAP_PARAM_ERROR if an invalid parameter was passed to the function (for example, if the LDAP connection is not valid).

LDAP_NO_MEMORY if memory cannot be allocated to decode the control returned by the server.

LDAP_DECODING_ERROR if an error occurred when BER decoding the control.

LDAP_CONTROL_NOT_FOUND if no control can be found in the response returned 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.")

Description
Call the ldap_parse_virtuallist_control() function as part of the process of retrieving a subset of entries from a list when working with a virtual list view box.
Call this function after receiving the results (call ldap_result() to get the results) and parsing the server controls from the results (call ldap_parse_result() to get the controls from the results).
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".
For more information about this control, see "Using the Virtual List View Control."

See Also
ldap_create_virtuallist_control().

ldap_perror()
The ldap_perror() function prints the last LDAP error message to standard output. The routine precedes this error message with the text you supply as the s parameter. For more information, see "Printing Out Error Messages."

Syntax
#include <ldap.h>
void ldap_perror( LDAP *ld, const char *s );

Parameters
This function has the following parameters:

Table 18-103    ldap_perror() function parameters

ld

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

s

Text to print out before printing the error message.

Example
The following section of code prints out an error message if the search operation cannot complete successfully.

Code Example 18-39    ldap_perror() code example

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

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

  ldap_perror( ld, "ldap_search_s" );

  return( 1 );

...

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

ldap_rename()
Changes the DN of an entry in the directory asynchronously.

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

Parameters
This function has the following parameters:

Table 18-104    ldap_rename() 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 rename.

newrdn

New relative distinguished name (RDN) to assign to the entry.

newparent

DN of the new parent entry you want to move the entry under. Pass NULL if you do not want to move the entry to a different location in the directory tree.

deleteoldrdn

If this is a non-zero value, the old RDN is not retained as a value in the entry. If 0, the old RDN is retained as an attribute in the 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.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_rename() changes the distinguished name (DN) of an entry in the directory asynchronously and allows you to move the entry under a different parent entry in the directory tree.
This function is a new version of the ldap_modrdn2() function. If you are writing a new LDAP client, you should call this function instead of ldap_modrdn2().
You can specify whether or not the old RDN is retained as an attribute of the entry. Use the deleteoldrdn argument to do this. Suppose an entry has the following values for the cn attribute:
cn: Barbara Jensen
cn: Babs Jensen
If you change the RDN to "cn=Barbie Jensen" and pass "1" as deleteoldrdn, the resulting entry has the following values:
cn: Barbie Jensen
cn: Babs Jensen
If instead you pass 0 as deleteoldrdn, the "Barbara Jensen" value is not removed from the entry:
cn: Barbie Jensen
cn: Babs Jensen
cn: Barbara Jensen
ldap_rename() 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_rename_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 rename 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 rename operation, see the result code documentation for the ldap_rename_s() function.
For more information on changing the DN of an entry, see "Changing the DN of an Entry."

Example
See the example under "Example: Renaming an Entry in the Directory (Asynchronous)."

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

ldap_rename_s()
Changes the DN of an entry in the directory synchronously.

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

Parameters
This function has the following parameters:

Table 18-105    ldap_rename_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 modify.

newrdn

New relative distinguished name (RDN) to assign to the entry.

newparent

DN of the new parent entry you want to move the entry under. Pass NULL if you do not want to move the entry to a different location in the directory tree.

deleteoldrdn

If this is a non-zero value, the old RDN is not retained as a value in the modified entry. If 0, the old RDN is retained as an attribute in the modified 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 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 modify DN 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 modify RDN 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.

The RDN specified by the newrdn argument is not a valid RDN.

Your LDAP client has not specified 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 DN specified by the newparent argument is not a valid DN.

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

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

You have specified a value for the newparent argument and the server does not support the ability to move an entry under another parent entry in the directory tree.

The server's database is read-only.

LDAP_NO_SUCH_OBJECT may be sent by the Directory Server if the entry that you want modified 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 renamed 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.

LDAP_ALREADY_EXISTS may be sent by the Directory Server if the new DN identifies an entry that already exists in the directory (for example, if you want to change the DN of an entry to uid=bjensen, ou=People, o=airius.com but an entry with that DN already exists).
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_rename_s() changes the DN of an entry in the directory synchronously and allows you to move the entry under a different parent entry in the directory tree.
This function is a new version of the ldap_modrdn2_s() function. If you are writing a new LDAP client, you should call this function instead of ldap_modrdn2_s().
You can specify whether or not the old RDN is retained as an attribute of the entry. Use the deleteoldrdn argument to do this. Suppose an entry has the following values for the cn attribute:
cn: Barbara Jensen
cn: Babs Jensen
If you change the RDN to cn=Barbie Jensen and pass 1 as deleteoldrdn, the resulting entry has the following values:
cn: Barbie Jensen
cn: Babs Jensen
If instead you pass 0 as deleteoldrdn, the "Barbara Jensen" value is not removed from the entry:
cn: Barbie Jensen
cn: Babs Jensen
cn: Barbara Jensen
The function ldap_rename_s() is synchronous; it 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_rename() instead. (For more information on asynchronous and synchronous functions, see "Calling Synchronous and Asynchronous Functions.")
For more information on changing the DN of an entry, see "Changing the DN of an Entry."

Example
See the example under "Example: Renaming an Entry in the Directory (Synchronous)."

See Also
ldap_rename().

ldap_result()
The function ldap_result() waits for and returns the result of an LDAP operation initiated by one of the asynchronous LDAP API functions (for example, ldap_search(), ldap_add(), ldap_modify()).
To identify the operation that you want to check, pass the message ID of the operation. (Asynchronous functions return a unique message ID that you can pass to the ldap_result() function.)
For more information, see "Getting the Server Response."

Syntax
#include <ldap.h>
int ldap_result( LDAP *ld, int msgid, int all,
  struct timeval *timeout, LDAPMessage **result );

Parameters
This function has the following parameters:

Table 18-106    ldap_result() 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 operation for which you want the results. To check any operation, pass LDAP_RES_ANY as the value of this parameter.

all

Specifies how the results of a search are returned. This parameter can have the following values:

0 specifies that the results are returned one entry at a time, using separate calls to ldap_result().

A non-zero value specifies that all results are returned at the same time (after the final search result is obtained by the library).

timeout

Specifies a maximum interval to wait for the selection to complete. If timeout is a NULL pointer, the select blocks indefinitely. To effect a poll, the timeout parameter should be a non-NULL pointer, pointing to a zero-valued timeval structure.

result

Result of the operation. To interpret the results, pass this to the LDAP parsing routines, such as ldap_result2error(), ldap_parse_result(), and ldap_first_entry().

Returns
One of the following values:

LDAP_RES_BIND indicates that the LDAPMessage structure contains the result of an LDAP bind operation.

LDAP_RES_SEARCH_ENTRY indicates that the LDAPMessage structure contains an entry found during an LDAP search operation.

LDAP_RES_SEARCH_REFERENCE indicates that the LDAPMessage structure contains an LDAPv3 search reference (a referral to another LDAP server) found during an LDAP search operation.

LDAP_RES_SEARCH_RESULT indicates that the LDAPMessage structure contains the result of an LDAP search operation.

LDAP_RES_MODIFY indicates that the LDAPMessage structure contains the result of an LDAP modify operation.

LDAP_RES_ADD indicates that the LDAPMessage structure contains the result of an LDAP add operation.

LDAP_RES_DELETE indicates that the LDAPMessage structure contains the result of an LDAP delete operation.

LDAP_RES_MODDN or LDAP_RES_RENAME indicates that the LDAPMessage structure contains the result of an LDAP modify DN operation.

LDAP_RES_COMPARE indicates that the LDAPMessage structure contains the result of an LDAP compare operation.

LDAP_RES_EXTENDED indicates that the LDAPMessage structure contains the result of an LDAPv3 extended operation.

-1 indicates that an error occurred. The error code is set 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.)

0 indicates that the operation has timed out.

Example
See the examples in the following sections:

For an example of getting the results of an asynchronous LDAP add operation, see "Example: Adding an Entry to the Directory (Asynchronous)."

For an example of getting the results of an asynchronous LDAP modify operation, see "Example: Modifying an Entry in the Directory (Asynchronous)."

For an example of getting the results of an asynchronous LDAP delete operation, see "Example: Deleting an Entry from the Directory (Asynchronous)."

For an example of getting the results of an asynchronous LDAP modify DN operation, see "Example: Renaming an Entry in the Directory (Asynchronous)."

For an example of getting the results of an asynchronous LDAP search operation, see "Example: Searching the Directory (Asynchronous)."

For an example of getting the results of an asynchronous LDAP bind operation, see "Performing an Asynchronous Authentication Operation."

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

ldap_result2error()
This function is deprecated and is supported and documented in this release for backward compatibility only. In its place, you should use ldap_parse_result().
ldap_result2error() returns the corresponding error code for a result produced by the ldap_result() and ldap_search_s() functions.

Syntax
#include <ldap.h>
int ldap_result2error( LDAP *ld, LDAPMessage *r, int freeit );

Parameters
This function has the following parameters:

Table 18-107    ldap_result2error() function parameters

ld

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

r

Pointer to the LDAPMessage structure representing the results returned by the ldap_result() or ldap_search() function.

freeit

Specifies whether or not the result should be freed after the error code is extracted. The parameter can have the following possible values:

0 specifies that the result should not be freed.

A non-zero value specifies that the result should be freed.

Returns
One of the following values:

If successful, sets the error code and other error information in the LDAP structure and returns the error code. (See Chapter 19 "Result Codes" for a complete listing of error codes.)

If unsuccessful, returns LDAP_PARAM_ERROR.

Example
See the example under ldap_result().

See Also
ldap_parse_result(), ldap_get_lderrno(), ldap_err2string(), ldap_result(), ldap_set_lderrno().

ldap_sasl_bind()
Authenticates your client to an LDAP server using an SASL (Simple Authentication and Security Layer) mechanism. The LDAP server must support that SASL mechanism for authentication.

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

Parameters
This function has the following parameters:

Table 18-108    ldap_sasl_bind() 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 user who wants to authenticate. For anonymous authentication, set this to NULL.

mechanism

Name of the SASL mechanism that you want to use for authentication.

cred

Pointer to the berval structure containing the credentials that you want to use for authentication.

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_sasl_bind_result() functions.

Returns
One of the following values:

LDAP_SUCCESS if the SASL bind request was sent successfully.

LDAP_PARAM_ERROR if an invalid parameter was passed to the function.

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.")

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

LDAP_NO_MEMORY if memory cannot be allocated.

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

Description
The ldap_sasl_bind() function authenticates your client to an LDAP server by using a specified SASL mechanism. The LDAP server must support authentication through that SASL mechanism. (The Directory Server supports a server plug-in interface that you can use to add SASL support to the server. For details, see the iPlanet Directory Server Plug-in Programmer's Guide.)
ldap_sasl_bind() 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_sasl_bind_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 SASL bind operation, you need to call the ldap_result() function, the ldap_parse_sasl_bind_result() function, and the ldap_get_lderrno() function. (See "Performing an Asynchronous SASL Bind Operation" for details.) For a list of possible result codes for an LDAP SASL bind operation, see the result code documentation for the ldap_sasl_bind_s() function.
For additional information on authenticating through SASL mechanisms, see Chapter 13 "Using SASL Authentication."

See Also
ldap_result(), ldap_parse_sasl_bind_result(), ldap_get_lderrno(), ldap_sasl_bind_s().

ldap_sasl_bind_s()
Authenticates your client to an LDAP server synchronously using an SASL (Simple Authentication and Security Layer) mechanism. The LDAP server must support that SASL mechanism for authentication.

Syntax
#include <ldap.h>
int ldap_sasl_bind_s( LDAP *ld, const char *dn,
  const char *mechanism, const struct berval *cred,
  LDAPControl **serverctrls, LDAPControl **clientctrls,
  struct berval **servercredp );

Parameters
This function has the following parameters:

Table 18-109    ldap_sasl_bind_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 user who wants to authenticate. For anonymous authentication, set this to NULL.

mechanism

Name of the SASL mechanism that you want to use for authentication.

cred

Pointer to the berval structure containing the credentials that you want to use for authentication.

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.

servercredp

Pointer to a pointer to an berval structure containing any credentials returned by the server. When done, you can free this by calling the ber_bvfree() function.

Returns
One of the following values:

LDAP_SUCCESS if your client authenticated successfully to the server.

LDAP_PARAM_ERROR if an invalid parameter was passed to the function.

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.")

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

LDAP_DECODING_ERROR if an error occurred when the LDAP API library was decoding the BER-encoded results received from the server.

LDAP_NO_MEMORY if memory cannot be allocated.

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

LDAP_LOCAL_ERROR if an error occurred when receiving the results from the server.
The following result codes can be returned by the Directory Server when processing an LDAP SASL bind 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 if the server cannot parse the LDAP controls that you are passing as arguments.

LDAP_UNAVAILABLE_CRITICAL_EXTENSION may be sent by the Directory Server if you specify a critical LDAP control that is not supported by the server.

LDAP_AUTH_METHOD_NOT_SUPPORTED can be set by the Directory Server if the SASL mechanism that you specify is not supported by the server (or if you specify an empty string as the SASL mechanism).

LDAP_PROTOCOL_ERROR if the bind request sent by this function 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.

Your LDAP client has not specified that it is using the LDAPv3 protocol. Make sure that you set the version of your LDAP client to version 3 before sending a SASL bind request. (For details, see "Specifying the LDAP Version of Your Client.")

Note that the iPlanet Directory Server may send other result codes in addition to the codes described here (for example, LDAP_NO_SUCH_OBJECT if the DN in the original bind request does not exist or LDAP_INVALID_CREDENTIALS if the credentials in the original bind request were incorrect). In the Directory Server, the people deploying the server are responsible for implementing the authentication mechanisms for SASL authentication. Check with your server administrator for additional result codes returned to the client.

Description
The ldap_sasl_bind_s() function authenticates your client to an LDAP server by using a specified SASL mechanism. The LDAP server must support authentication through that SASL mechanism. (The Directory Server supports a server plug-in interface that you can use to add SASL support to the server. For details, see the iPlanet Directory Server Plug-In Programmer's Guide.)
After authenticating a client through SASL, an LDAP server can return a set of credentials in the results. The servercredp argument points to this value.
ldap_sasl_bind_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_sasl_bind() instead. (For more information on asynchronous and synchronous functions, see "Calling Synchronous and Asynchronous Functions.")
For additional information on authenticating through SASL mechanisms, see Chapter 13 "Using SASL Authentication."

See Also
ldap_sasl_bind().

ldap_search()
Searches 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_search_ext() instead.

Syntax
#include <ldap.h>
int ldap_search( LDAP *ld, const char *base, int scope,
  const char* filter, char **attrs, int attrsonly );

Parameters
This function has the following parameters:

Table 18-110    ldap_search() function parameters

ld

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

base

Distinguished name (DN) of the entry that serves as the starting point for the search. For example, setting base to "o=airius.com" restricts the search to entries at airius.com.

scope

Scope of the search, which can be one of the following values:

LDAP_SCOPE_BASE searches the entry specified by base.

LDAP_SCOPE_ONELEVEL searches all entries one level beneath the entry specified by base.

LDAP_SCOPE_SUBTREE searches the entry specified by base and all entries at all levels beneath the entry specified by base.

filter

String representation of the filter to apply in the search. You can specify simple filters with the following syntax:

(attributetype=attributevalue)

For details on the syntax for filters, see "Specifying a Search Filter."

attrs

A NULL-terminated array of attribute types to return from entries that match filter. If you specify a NULL, all attributes will be returned.

attrsonly

Specifies whether or not attribute values are returned along with the attribute types. This parameter can have the following values:

0 specifies that both attribute types and attribute values are returned.

1 specifies that only attribute types are returned.

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

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

Example
The following section of code searches the directory.

Code Example 18-40    ldap_search() code example

#include "examples.h"

static void do_other_work();

unsigned long global_counter = 0;

int

main( int argc, char **argv )

{

  LDAP *ld;

  LDAPMessage *result, *e;

  BerElement *ber;

  char *a, *dn;

  char **vals;

  int i, rc, finished, msgid;

  int num_entries = 0;

  struct timeval zerotime;

  zerotime.tv_sec = zerotime.tv_usec = 0L;

/* get a handle to an LDAP connection */

if ( (ld = ldap_init( MY_HOST, MY_PORT )) == NULL ) {

  perror( "ldap_init" );

  return( 1 );

}

/* authenticate to the directory as nobody */

if ( ldap_simple_bind_s( ld, NULL, NULL ) != LDAP_SUCCESS ) {

  ldap_perror( ld, "ldap_simple_bind_s" );

  return( 1 );

}

/* search for all entries with surname of Jensen */

if (( msgid = ldap_search( ld, MY_SEARCHBASE, LDAP_SCOPE_SUBTREE,

   MY_FILTER, NULL, 0 )) == -1 ) {

  ldap_perror( ld, "ldap_search" );

  return( 1 );

}

/* Loop, polling for results until finished */

finished = 0;

while ( !finished ) {

  /*

  * Poll for results. We call ldap_result with the "all" parameter

  * set to zero. This causes ldap_result() to return exactly one

  * entry if at least one entry is available. This allows us to

  * display the entries as they are received.

  */

  result = NULL;

  rc = ldap_result( ld, msgid, 0, &zerotime, &result );

  switch ( rc ) {

  case -1:

    /* some error occurred */

    ldap_perror( ld, "ldap_result" );

    return( 1 );

  case 0:

  /* Timeout was exceeded. No entries are ready for retrieval. */

    if ( result != NULL ) {

      ldap_msgfree( result );

    }

    break;

  default:

  /*

  * Either an entry is ready for retrieval, or all entries have

  * been retrieved.

  */

    if (( e = ldap_first_entry( ld, result )) == NULL ) {

      /* All done */

      finished = 1;

      if ( result != NULL ) {

        ldap_msgfree( result );

      }

      continue;

   }

    /* for each entry print out name + all attrs and values */

    num_entries++;

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

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

      ldap_memfree( dn );

    }

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

     a != NULL; a = ldap_next_attribute( ld, e, ber ) ) {

      if (( vals = ldap_get_values( ld, e, a )) != NULL ) {

        for ( i = 0; vals[ i ] != NULL; i++ ) {

          printf( "%s: %s\n", a, vals[ i ] );

        }

      ldap_value_free( vals );

      }

      ldap_memfree( a );

    }

    if ( ber != NULL ) {

      ldap_ber_free( ber, 0 );

    }

    printf( "\n" );

    ldap_msgfree( result );

  }

  /* Do other work here while you are waiting... */

  do_other_work();

}

/* All done. Print a summary. */

printf( "%d entries retrieved. I counted to %ld "

   "while waiting.\n", num_entries, global_counter );

ldap_unbind( ld );

return( 0 );

}

/*

* Perform other work while polling for results. */

static void

do_other_work()

{

global_counter++;

}

See Also
ldap_search_ext().

ldap_search_ext()
Searches the directory asynchronously.

Syntax
#include <ldap.h>
int ldap_search_ext( LDAP *ld, const char *base, int scope,
  const char *filter, char **attrs, int attrsonly,
  LDAPControl **serverctrls, LDAPControl **clientctrls,
  struct timeval *timeoutp, int sizelimit, int *msgidp );

Parameters
This function has the following parameters:

Table 18-111    ldap_sort_ext() function parameters

ld

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

base

Distinguished name (DN) of the entry that serves as the starting point for the search. For example, setting base to "o=airius.com" restricts the search to entries at airius.com.

scope

Scope of the search, which can be one of the following values:

LDAP_SCOPE_BASE searches the entry specified by base.

LDAP_SCOPE_ONELEVEL searches all entries one level beneath the entry specified by base.

LDAP_SCOPE_SUBTREE searches the entry specified by base and all entries at all levels beneath the entry specified by base.

filter

String representation of the filter to apply in the search. You can specify simple filters with the following syntax:

(attributetype=attributevalue)

For details on the syntax for filters, see "Specifying a Search Filter."

attrs

A NULL-terminated array of attribute types to return from entries that match filter. If you specify a NULL, all attributes will be returned.

attrsonly

Specifies whether or not attribute values are returned along with the attribute types. This parameter can have the following values:

0 specifies that both attribute types and attribute values are returned.

1 specifies that only attribute types are returned.

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.

timeoutp

Pointer to a timeval structure specifying the maximum time to wait for the results of the search. Pass NULL to use the default time limit for the current connection. To specify an infinite time limit, set the tv_sec and tv_usec fields in the timeval structure to 0.

sizelimit

Maximum number of results to return in the search. Pass -1 to use the default size limit for the current connection.

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_search_ext() function searches the directory for matching entries asynchronously.
This function is a new version of the ldap_search() function. If you are writing a new LDAP client, you should call this function instead of ldap_search().
You can use this function to pass LDAP server controls to the server if you want the server to sort the results or if you want to request a persistent search. (See ldap_create_sort_control() and ldap_create_persistentsearch_control() for more information.)
ldap_search_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_search_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 search operation, you need to call the ldap_result() function and the ldap_parse_result() function. (See "Getting Results Asynchronously" for details.) For a list of possible result codes for an LDAP search operation, see the result code documentation for the ldap_search_ext_s() function.
For more information on searching the directory, see Chapter 6 "Searching the Directory."

Example
See the example under "Example: Searching the Directory (Asynchronous)."

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

ldap_search_ext_s()
Searches the directory synchronously.

Syntax
#include <ldap.h>
int ldap_search_ext_s( LDAP *ld, const char *base, int scope,
  const char *filter, char **attrs, int attrsonly,
  LDAPControl **serverctrls, LDAPControl **clientctrls,
  struct timeval *timeoutp, int sizelimit, LDAPMessage **res );

Parameters
This function has the following parameters:

Table 18-112    ldap_search_ext_s() function parameters

ld

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

base

Distinguished name (DN) of the entry that serves as the starting point for the search. For example, setting base to "o=airius.com" restricts the search to entries at airius.com.

scope

Scope of the search, which can be one of the following values:

LDAP_SCOPE_BASE searches the entry specified by base.

LDAP_SCOPE_ONELEVEL searches all entries one level beneath the entry specified by base.

LDAP_SCOPE_SUBTREE searches all entries at all levels beneath the entry specified by base.

filter

String representation of the filter to apply in the search. You can specify simple filters with the following syntax:

(attributetype=attributevalue)

For details on the syntax for filters, see "Specifying a Search Filter."

attrs

A NULL-terminated array of attribute types to return from entries that match filter. If you specify a NULL, all attributes will be returned.

attrsonly

Specifies whether or not attribute values are returned along with the attribute types. This parameter can have the following values:

0 specifies that both attribute types and attribute values are returned.

1 specifies that only attribute types are returned.

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.

timeoutp

Pointer to a timeval structure specifying the maximum time to wait for the results of the search.

sizelimit

Maximum number of results to return in the search.

res

Results of the search (when the call is completed).

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.")

LDAP_FILTER_ERROR if an error occurred when parsing and BER-encoding the search filter specified by the filter argument.

LDAP_TIMEOUT if the search exceeded the time specified by the timeoutp argument.
The following result codes can be returned by the iPlanet Directory Server when processing an LDAP search 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 search 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.

The search request received by the server specifies an unknown search scope or filter type.

Your LDAP client attempts to use an extensible search filter and has not specified that it is using the LDAPv3 protocol. Make sure that you set the version of your LDAP client to version 3 before sending the request. (For details, see "Specifying the LDAP Version of Your Client.")

The server encountered an error when attempting to sort the search results or when attempting to send sorted results.

LDAP_INVALID_SYNTAX may be sent by the Directory Server if your LDAP client specified a substring filter containing no value for comparison.

LDAP_NO_SUCH_OBJECT may be sent by the Directory Server if the entry specified by the base argument does not exist and if no referral URLs are available.

LDAP_REFERRAL may be sent by the Directory Server if the entry specified by the base argument is 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_TIMELIMIT_EXCEEDED may be sent by the Directory Server if the search exceeded the maximum time specified by the timeoutp argument.

LDAP_SIZELIMIT_EXCEEDED may be sent by the Directory Server if the search found more results than the maximum number of results specified by the sizelimit argument.

LDAP_ADMINLIMIT_EXCEEDED may be sent by the Directory Server if the search found more results than the limit specified by the lookthroughlimit directive in the slapd.conf configuration file. (If not specified in the configuration file, the limit is 5000.)
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_search_ext_s() searches the directory for matching entries synchronously.
You can use this function to pass LDAP server controls to the server if you want the server to sort the results or if you want to request a persistent search. (See ldap_create_sort_control() and ldap_create_persistentsearch_control() for more information.)
This function is a new version of the ldap_search_s() function. If you are writing a new LDAP client, you should call this function instead of ldap_search_s().
The function ldap_search_ext_s() is synchronous; it 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_search_ext() instead. (For more information on asynchronous and synchronous functions, see "Calling Synchronous and Asynchronous Functions.")
For more information on searching the directory, see Chapter 6 "Searching the Directory."

Example
See the example under "Example: Searching the Directory (Synchronous)."

See Also
ldap_search_ext().

ldap_search_s()
Searches 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_search_ext_s() instead.

Syntax
#include <ldap.h>
int ldap_search_s( LDAP *ld, const char *base, int scope,
  const char* filter, char **attrs, int attrsonly,
  LDAPMessage **res );

Parameters
This function has the following parameters:

Table 18-113    ldap_search_s() function parameters

ld

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

base

Distinguished name (DN) of the entry that serves as the starting point for the search. For example, setting base to "o=airius.com" restricts the search to entries at airius.com.

scope

Scope of the search, which can be one of the following values:

LDAP_SCOPE_BASE searches the entry specified by base.

LDAP_SCOPE_ONELEVEL searches all entries one level beneath the entry specified by base.

LDAP_SCOPE_SUBTREE searches all entries at all levels beneath the entry specified by base.

filter

String representation of the filter to apply in the search. You can specify simple filters with the following syntax:

(attributetype=attributevalue)

For details on the syntax for filters, see "Specifying a Search Filter."

attrs

A NULL-terminated array of attribute types to return from entries that match filter. If you specify a NULL, all attributes will be returned.

attrsonly

Specifies whether or not attribute values are returned along with the attribute types. This parameter can have the following values:

0 specifies that both attribute types and attribute values are returned.

1 specifies that only attribute types are returned.

res

Results of the search (when the call is completed).

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

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

Example
The following section of code searches the directory for all people whose surname (last name) is "Jensen".

Code Example 18-41    ldap_search_s() code example

#include "examples.h"

int main( int argc, char **argv )

{

  LDAP *ld;

  LDAPMessage *result, *e;

  BerElement *ber;

  char *a, *dn;

  char **vals;

  int i;

  /* get a handle to an LDAP connection */

  if ( (ld = ldap_init( MY_HOST, MY_PORT )) == NULL ) {

    perror( "ldap_init" );

    return( 1 );

  }

  /* authenticate to the directory as nobody */

  if ( ldap_simple_bind_s( ld, NULL, NULL ) != LDAP_SUCCESS ) {

    ldap_perror( ld, "ldap_simple_bind_s" );

    return( 1 );

  }

  /* search for all entries with surname of Jensen */

  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 entry print out name + all attrs and values */

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

      ldap_memfree( dn );

    }

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

     a != NULL; a = ldap_next_attribute( ld, e, ber ) ) {

      if ((vals = ldap_get_values( ld, e, a)) != NULL ) {

        for ( i = 0; vals[i] != NULL; i++ ) {

          printf( "%s: %s\n", a, vals[i] );

        }

        ldap_value_free( vals );

      }

      ldap_memfree( a );

    }

    if ( ber != NULL ) {

      ldap_ber_free( ber, 0 );

    }

    printf( "\n" );

  }

  ldap_msgfree( result );

  ldap_unbind( ld );

  return( 0 );

}

See Also
ldap_search_ext_s().

ldap_search_st()
Searches the directory synchronously within a specified time limit.
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_search_ext_s() instead.

Syntax
#include <ldap.h>
int ldap_search_st( LDAP *ld, const char *base, int scope,
  const char* filter, char **attrs, int attrsonly,
  struct timeval *timeout, LDAPMessage **res );

Parameters
This function has the following parameters:

Table 18-114    ldap_search_st() function parameters

ld

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

base

Distinguished name (DN) of the entry that serves as the starting point for the search. For example, setting base to "o=airius.com" restricts the search to entries at airius.com.

scope

Scope of the search, which can be one of the following values:

LDAP_SCOPE_BASE searches the entry specified by base.

LDAP_SCOPE_ONELEVEL searches all entries one level beneath the entry specified by base.

LDAP_SCOPE_SUBTREE searches all entries at all levels beneath the entry specified by base.

filter

String representation of the filter to apply in the search. You can specify simple filters with the following syntax:

(attributetype=attributevalue)

For details on the syntax for filters, see "Specifying a Search Filter."

attrs

A NULL-terminated array of attribute types to return from entries that match filter. If you specify a NULL, all attributes will be returned.

attrsonly

Specifies whether or not attribute values are returned along with the attribute types. This parameter can have the following values:

0 specifies that both attribute types and attribute values are returned.

1 specifies that only attribute types are returned.

timeout

Maximum time to wait for the results of the search.

res

Results of the search (when the call is completed).

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

Description
The ldap_search_st() function searches the directory for matching entries. The ldap_search_st() function works like the ldap_search_s() function and lets you set a timeout period for the search.
A newer version of this function, ldap_search_ext_s(), is available in this release of the LDAP API. ldap_search_st() (the older version of the function) is included only for backward-compatibility. If you are writing a new LDAP client, use ldap_search_ext_s() instead of ldap_search_st().
If you want more information on ldap_search_st(), refer to the LDAP C SDK 1.0 Programmer's Guide.

See Also
ldap_search_ext_s().

ldap_set_filter_additions()
The ldap_set_filter_additions() function sets a prefix to be prepended and a suffix to be appended to all filters returned by the ldap_getfirstfilter() and ldap_getnextfilter() function calls.

Syntax
#include <ldap.h>
int ldap_set_filter_additions( LDAPFiltDesc *lfdp, char *prefix,
  char *suffix );

Parameters
This function has the following parameters:

Table 18-115    ldap_set_filter_additions() function parameters

lfdp

Pointer to an LDAPFiltDesc structure.

prefix

Prefix to prepend to all filters. If NULL, no prefix is prepended.

suffix

Suffix to append to all filters. If NULL, no suffix is appended.

Returns
One of the following values:

LDAP_SUCCESS if successful.

If unsuccessful, returns an LDAP error code. (See Chapter 19 "Result Codes" for a complete listing.)

Example
The following section of code loads the filter configuration file named myfilters.conf into memory and adds the prefix "(&(objectClass=person)" and the suffix ")" to each filter retrieved:

Code Example 18-42    ldap_set_filter_additions() code example

...

LDAPFiltDesc *lfdp;

char *filter_file = "myfilters.conf";

char *prefix = "(&(objectClass=person)";

char *suffix = ")";

int rc;

...

lfdp = ldap_init_getfilter( filter_file );

rc = ldap_set_filter_additions( ldfp, prefix, suffix );

if ( rc != LDAP_SUCCESS ) {

  printf( "Error setting filter prefix and suffix\n");

  return( rc );

}

...

See Also
ldap_getfirstfilter(), ldap_getnextfilter().

ldap_setfilteraffixes()
The ldap_setfilteraffixes() function is a deprecated function. Use the ldap_set_filter_additions() function instead.

ldap_set_lderrno()
The ldap_set_lderrno() function sets an error code and information about an error in an LDAP structure. You can call this function to set error information that will be retrieved by subsequent ldap_get_lderrno() function calls.
For more information, see "Setting Error Codes."

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

Parameters
This function has the following parameters:

Table 18-116    ldap_set_lderrno() function parameters

ld

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

e

The error code that you want to set.

m

In the event that an entry for a specified DN cannot be found, you should set this parameter to the portion of the DN that identifies an existing entry. (See "Receiving the Portion of the DN Matching an Entry" for details.)

s

The text of the error message that you want associated with this error code.

Returns
One of the following values:

LDAP_SUCCESS if successful.

If unsuccessful, returns an LDAP error code. (See Chapter 19 "Result Codes" for a complete listing.)

Example
The following section of code attempts to perform an operation. If the operation fails, the LDAP_PARAM_ERROR error code is placed in the LDAP structure.

Code Example 18-43    ldap_set_lderrno() code example

int rc;

char *errmsg = "Invalid parameter";

...

if ( ldap_my_function() != LDAP_SUCCESS ) {

  rc = ldap_set_lderrno( ld, LDAP_PARAM_ERROR, NULL, errmsg );

  if ( rc != LDAP_SUCCESS ) {

    printf( "Error: %d\nError code could not be set.\n", rc );

  }

  return( rc );

}

...

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

ldap_set_option()
The function ldap_set_option() sets session preferences in the LDAP structure. For more information on the options you can set, see "Setting Preferences."

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

Parameters
This function has the following parameters:

Table 18-117    ldap_set_option() function parameters

ld

Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.
If NULL, you are setting the default options that will apply to any new LDAP connection handles that are subsequently created.

option

Option that you want to set.

optdata

Pointer to the value of the option that you want to set.

The option parameter can have one of the following values:

Table 18-118    Options for ldap_set_option() function

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_DEREF

Determines how aliases are handled 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 the base object and searching under the base object.

LDAP_OPT_DNS_FN_PTRS

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

LDAP_OPT_EXTRA_THREAD_FN_PTRS

Lets you specify the locking and semaphore functions 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_MEMALLOC_FNS_PTRS

Lets you replace the standard function used for memory management (for example malloc(), calloc(), realloc(), and free()) with your own function. See the prototype for the ldap_memalloc_fns callback structure for the details on the structure that you can set.

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 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 client should follow referrals.

LDAP_OPT_OFF specifies that the client 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

If there is a fatal error on connection, this option resets the connection to an initial unconnected known state.

LDAP_OPT_SERVER_CONTROLS

Pointer to an array of LDAPControl structures representing the LDAPv3 server controls you want sent with every request by default.
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 *).

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 *).

LDAP_X_OPT_EXTIO_FN_PTRS

Lets you specify the extended I/O callback functions which were introduced with version 4.0 of the LDAP SDK for C.

Returns
One of the following values:

LDAP_SUCCESS if successful.

-1 if unsuccessful.

Example
The following section of code sets the maximum number of entries returned in a search.

Code Example 18-44    ldap_set_option() code example

#include <ldap.h>

...

LDAP *ld;

int max_ret = 100, max_tim = 30;

char *host = "ldap.netscape.com";

...

/* Initialize a session with the LDAP server ldap.netscape.com:389 */

if ( ( ld = ldap_init( host, LDAP_PORT ) ) == NULL ) {

  perror( "ldap_init" );

  return( 1 );

}

/* Set the maximum number of entries returned */

if (ldap_set_option( ld, LDAP_OPT_SIZELIMIT, &max_ret) != LDAP_SUCCESS) {

  ldap_perror( ld, "ldap_set_option" );

  return( 1 );

}

...

See Also
ldap_init(), ldap_get_option().

ldap_set_rebind_proc()
Sets the rebind function, which is the function called by your client to obtain authentication credentials when following a referral.

Syntax
#include <ldap.h>
void ldap_set_rebind_proc( LDAP *ld,
  LDAP_REBINDPROC_CALLBACK *rebindproc, void *arg );

Parameters
This function has the following parameters:

Table 18-119    ldap_set_rebind_proc() function parameters

ld

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

rebindproc

Name of the rebind function.

arg

Pointer to an additional argument that you want to pass to the rebind function.

Description
Call ldap_set_rebind_proc() to specify the rebind function (the function called by the LDAP client when following a referral to a new LDAP server). This rebind function is responsible for obtaining the credentials used to authenticate to the new LDAP server.
For example, suppose LDAP server A sends a referral to your client. The referral points your client to LDAP server B. When automatically following the referral, your client calls the rebind function to obtain a DN and credentials; your client uses these to authenticate to server B.
By default, if you do not call ldap_set_rebind_proc() or if you pass NULL for the rebindproc argument, your client authenticates anonymously when following referrals.
The rebind function that you specify with ldap_set_rebind_proc() should have the following prototype:
int LDAP_CALL LDAP_CALLBACK rebindproc( LDAP *ld, char **dnp,
  char **passwdp, int *authmethodp, int freeit, void *arg );
(LDAP_CALL and LDAP_CALLBACK are used to set up calling conventions, such as Pascal calling conventions on Windows. These are defined in the lber.h header file.)
LDAP clients that are built with the Netscape LDAP SDK for C use this procedure when following referrals (the procedure explains what the rebind function is expected to do):

The LDAP server sends a referral back to the client.

The client calls the rebind function, passing 0 as the freeit argument.

The rebind function sets the dnp, passwdp, and authmethodp arguments to point to the following information:

The dnp argument is set to point to the DN to be used to authenticate to the new LDAP server.

The passwdp argument is set to point to the credentials for this DN.

The authmethodp argument is set to point to the method of authentication used (for example, LDAP_AUTH_SIMPLE).

If successful, the rebind function returns LDAP_SUCCESS, and referral processing continues. (If any other value is returned, referral processing stops, and that value is returned as the result code for the original LDAP request.)

The client gets the DN, credentials, and authentication method from the arguments of the rebind function and uses this information to authenticate to the new LDAP server.

The client calls the rebind function again, passing 1 as the freeit argument.

The rebind function frees any memory allocated earlier to specify the DN and credentials.
You need to write a rebind function that does the following:

If freeit is 0, set the following pointers:

Set dnp to point to the DN to be used for authentication.

Set passwdp to point to the credentials to be used for authentication.

Set authmethodp to point to the method of authentication used (for example, LDAP_AUTH_SIMPLE).

You can make use of the arg argument, which is a pointer to the argument specified in the ldap_set_rebind_proc() function.

If successful, return LDAP_SUCCESS. Otherwise, return the appropriate LDAP error code.

If freeit is 1, free any memory that you allocated to create the DN and credentials.
After you have defined this function, pass the function name to ldap_set_rebind_proc() to register your rebind function.
Note that in order to use the rebind function, the LDAP_OPT_REFERRALS option must be set to LDAP_OPT_ON, so that your client automatically follows referrals. This option is already set to LDAP_OPT_ON by default.

Example
The following example demonstrates how to write and register a rebind function.

Code Example 18-45    ldap_set_rebind_proc() code example

...

/* Declare your rebind function */

int rebindproc( LDAP *ld, char **dnp, char **passwdp, int *authmethodp, int freeit, void *arg );

...

int main( int argc, char **argv )

{

  LDAP *ld;

  /* Additional argument to be passed to the rebind function */

  char *testarg = "cn=Directory Manager";

  /* Get a handle to an LDAP connection */

  if ( (ld = ldap_init( "directory.myhost.com", 389 )) == NULL ) {

    perror( "ldap_init" );

    return( 1 );

  }

  /* Specify the function used for reauthentication on referrals */

  ldap_set_rebind_proc( ld, rebindproc, (void *)testarg );

  /* Authenticate */

  if ( ldap_simple_bind_s( ld, "uid=bjensen,ou=People,o=airius.com",

      "hifalutin" ) != LDAP_SUCCESS ) {

    ldap_perror( ld, "ldap_simple_bind_s" );

    return( 1 );

  }

  ...

  /* Your code to interact with the LDAP server */

  ...

}

...

/* rebindproc is the rebind function responsible for providing the DN,

  credentials, and authentication method used for authenticating the

  client to other Directory Servers.

  The function should set the following arguments:

  - dnp should point to the DN that will be used for authentication.

  - passwdp should point to the credentials used for authentication.

  - authmethodp should point to the method of authentication to be used

  (for example, LDAP_AUTH_SIMPLE).

  The function should return LDAP_SUCCESS if successful or an LDAP

  error code if an error occurs.

  In order to demonstrate how the freeit argument works, this example

  uses strdup() to copy the DN and password. You can also just copy

  string pointers if the DN and password are already available as

  global variables.

*/

int LDAP_CALL LDAP_CALLBACK rebindproc( LDAP *ld, char **dnp, char **passwdp, int *authmethodp, int freeit, void *arg )

{

  printf( "Rebind function called.\n" );

  switch ( freeit ) {

  /* Your client calls the rebind function with freeit==1 when it needs

    to free any memory you've allocated. */

  case 1:

    printf( "\tFreeing memory.\n" );

    if ( dnp && *dnp ) {

      free( *dnp );

    }

    if ( passwdp && *passwdp ) {

      free( *passwdp );

    }

    break;

  /* Your client calls the rebind function with freeit==0 when it needs

  to get the DN, credentials, and authentication method. */

  case 0:

    printf( "\tGetting DN and credentials.\n" );

    *dnp = strdup( "uid=username,o=OtherServerSuffix" );

    *passwdp = strdup( "23skidoo" );

    *authmethodp = LDAP_AUTH_SIMPLE;

    break;

  default:

    printf( "\tUnknown value of freeit argument: %d\n", freeit );

    break;

  }

  /* If you successfully set the DN and credentials, you should return

    LDAP_SUCCESS. (Any other return code will stop the client from

    automatically following the referral. */

  return LDAP_SUCCESS;

}

See Also
ldap_simple_bind(), ldap_simple_bind_s().

ldap_simple_bind()
Asynchronously authenticates your client to the LDAP server using a DN and a password.

Syntax
#include <ldap.h>
int ldap_simple_bind(LDAP *ld, const char *who,
  const char *passwd);

Parameters
This function has the following parameters:

Table 18-120    ldap_simple_bind() function parameters

ld

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

who

Distinguished name (DN) of the user who wants to authenticate. For anonymous authentication, set this or the passwd argument to NULL.

passwd

Password of the user who wants to authenticate. For anonymous authentication, set this or the who argument to NULL.

Returns
Returns the message ID of the ldap_simple_bind() operation. To check the result of this operation, call ldap_result() and ldap_result2error().

Description
The ldap_simple_bind() function authenticates to the LDAP server. The function verifies that the password supplied for authentication matches the userPassword attribute of the given entry.
ldap_simple_bind() 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_simple_bind_s() instead. (For more information on asynchronous and synchronous functions, see "Calling Synchronous and Asynchronous Functions.")
Note that if you specify a DN but no password, your client will bind to the server anonymously. If you want a NULL password to be rejected as an incorrect password, you need to write code to perform the check before you call the ldap_simple_bind() function.
For additional information on authenticating to the LDAP server, see "Binding and Authenticating to an LDAP Server."

Example
The following section of code calls ldap_simple_bind() to authenticate the user "Barbara Jensen" to the directory.

Code Example 18-46    ldap_simple_bind() code example

#include <ldap.h>

...

LDAP *ld;

char *host = "ldap.netscape.com";

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

char *pw = "hifalutin";

struct timeval zerotime;

zerotime.tv_sec = zerotime.tv_usec = 0L;

...

/* Initialize a session with the LDAP server ldap.netscape.com:389 */

if ( ( ld = ldap_init( host, LDAP_PORT ) ) == NULL ) {

  perror( "ldap_init" );

  return( 1 );

}

/* Attempt to bind with the LDAP server */

msgid = ldap_simple_bind( ld, dn, pw );

/* Initialize the value returned by ldap_result() */

rc = 0;

/* While the operation is still running, do this: */

while ( rc == 0 ) {

  ... /* do other work while waiting */...



  /* Check the status of the LDAP operation */

  rc = ldap_result( ld, msgid, NULL, &zerotime, &result );

  switch( rc ) {

    /* If -1 was returned, an error occurred */

    case -1:

      ldap_perror( ld, "Error in results: " );

      return( 1 );

    /* If 0 was returned, the operation is still in progress */

    case 0:

      continue;

    /* If any other value is returned, assume we are done */

    default:

      /* Check if the "bind" operation was successful */

      if ( ldap_result2error( result ) != LDAP_SUCCESS ) {

        ldap_perror( ld, "Error binding to server: " );

        return( 1 );

        }

  }

}

...

See Also
ldap_simple_bind_s().

ldap_simple_bind_s()
Synchronously authenticates your client to the LDAP server using a DN and a password.

Syntax
#include <ldap.h>
int ldap_simple_bind_s( LDAP *ld, const char *who,
  const char *passwd );

Parameters
This function has the following parameters:

Table 18-121    ldap_simple_bind_s() function parameters

ld

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

who

Distinguished name (DN) of the user who wants to authenticate. For anonymous authentication, set this or the passwd argument to NULL.

passwd

Password of the user who wants to authenticate. For anonymous authentication, set this or the who argument to NULL.

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 iPlanet Directory Server when processing an LDAP search 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 search 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.

The search request received by the server specifies an unknown search scope or filter type.

Your LDAP client attempts to use an extensible search filter and has not specified that it is using the LDAPv3 protocol. Make sure that you set the version of your LDAP client to version 3 before sending the request. For details, see "Specifying the LDAP Version of Your Client."

The server encountered an error when attempting to sort the search results or when attempting to send sorted results.

LDAP_INVALID_SYNTAX may be sent by the Directory Server if your LDAP client specified a substring filter containing no value for comparison.

LDAP_NO_SUCH_OBJECT may be sent by the Directory Server if the entry specified by the base argument does not exist and if no referral URLs are available.

LDAP_REFERRAL may be sent by the Directory Server if the entry specified by the base argument is 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_TIMELIMIT_EXCEEDED may be sent by the Directory Server if the search exceeded the maximum time specified by the timeoutp argument.

LDAP_SIZELIMIT_EXCEEDED may be sent by the Directory Server if the search found more results than the maximum number of results specified by the sizelimit argument.

LDAP_ADMINLIMIT_EXCEEDED may be sent by the Directory Server if the search found more results than the limit specified by the lookthroughlimit directive in the slapd.conf configuration file. (If not specified in the configuration file, the limit is 5000.)
Note that the iPlanet 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_simple_bind_s() function authenticates to the LDAP server. The function verifies that the password supplied for authentication matches the userPassword attribute of the given entry.
ldap_simple_bind_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_simple_bind() instead. (For more information on asynchronous and synchronous functions, see "Calling Synchronous and Asynchronous Functions.")
Note that if you specify a DN but no password, your client will bind to the server anonymously. If you want a NULL password to be rejected as an incorrect password, you need to write code to perform the check before you call the ldap_simple_bind_s() function.
For additional information on authenticating to the LDAP server, see "Binding and Authenticating to an LDAP Server."

Example
The following section of code uses the synchronous ldap_simple_bind_s() function to authenticate to the directory as the user "Barbara Jensen".

Code Example 18-47    ldap_simple_bind_s() code example

#include <ldap.h>

...

LDAP *ld;

char *host = "ldap.netscape.com";

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

char *pw = "hifalutin";

...

/* Initialize a session with the LDAP server ldap.netscape.com:389 */

if ( ( ld = ldap_init( host, LDAP_PORT ) ) == NULL ) {

  perror( "ldap_init" );

  return( 1 );

}

/* Attempt to bind with the LDAP server */

if ( ldap_simple_bind_s( ld, dn, pw ) != LDAP_SUCCESS ) {

  ldap_perror( ld, "Authentication failed: " );

  return( 1 );

}

...

See Also
ldap_simple_bind().

ldap_sort_entries()
The ldap_sort_entries() function sorts a chain of entries retrieved from an LDAP search call (ldap_search_s() or ldap_result()) either by distinguished name (DN) or by a specified attribute in the entries.
For additional information, see "Sorting the Search Results."

Syntax
#include <ldap.h>
int ldap_sort_entries( LDAP *ld, LDAPMessage *chain, char *attr,
  LDAP_CMP_CALLBACK *cmp );

Parameters
This function has the following parameters:

Table 18-122    ldap_sort_entires() function parameters

ld

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

chain

Chain of entries returned by the ldap_result() or ldap_search_s() function.

attr

Attribute to use when sorting the results. To sort by distinguished name instead of by attribute, use NULL.

cmp

Comparison function used when sorting the values. For details, see "Sorting Entries by an Attribute."

Returns
One of the following values:

LDAP_SUCCESS if successful.

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

Example
The following section of code sorts entries by the roomNumber attribute.

Code Example 18-48    ldap_sort_entries() code example

#include <string.h>

#include <ldap.h>

LDAP *ld;

LDAPMessage *result;

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

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

char *sortby = "roomNumber";

...

/* 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 );

}

/* Sort the results by room number, using strcasecmp */

if ( ldap_sort_entries( ld, &result, sortby, strcasecmp ) != LDAP_SUCCESS ) {

  ldap_perror( ld, "ldap_sort_entries" );

  return( 1 );

}

...

See Also
ldap_multisort_entries(), ldap_result(), ldap_search_s().

ldap_sort_values()
The ldap_sort_values() function sorts an array of values retrieved from an ldap_get_values() call.
For additional information, see "Sorting the Search Results."

Syntax
#include <ldap.h>
int ldap_sort_values( LDAP *ld, char **vals,
  LDAP_VALCMP_CALLBACK cmp );

Parameters
This function has the following parameters:

Table 18-123    ldap_sort_values() function parameters

ld

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

vals

The array of values to sort.

cmp

Comparison function used when sorting the values.
In the ldap_sort_values() function, the comparison function must pass (char **) parameters. Because of this, you need to use the ldap_sort_strcasecmp() function, rather than a function like strcasecmp().

Returns
One of the following values:

LDAP_SUCCESS if successful.

If unsuccessful, returns an LDAP error code. (See Chapter 19 "Result Codes" for a complete listing of error codes.)

Example
The following section of code sorts the values of attributes before printing them.

Code Example 18-49    ldap_sort_values() code example

#include <string.h>

#include <ldap.h>

...

LDAP *ld;

LDAPMessage *result, *e;

BerElement *ber;

char *a, *dn;

char **vals;

int i;

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

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

...

    if ( ( vals = ldap_get_values( ld, e, a ) ) != NULL ) {

      /* Sort the values of the attribute */

      if ( ldap_sort_values( ld, vals, strcasecmp ) ) != LDAP_SUCCESS ) {

        ldap_perror( ld, "ldap_sort_values" );

        return( 1 );

      }

      /* Print the values of the attribute */

      for ( i = 0; vals[i] != NULL; i++ ) {

        printf( "%s: %s\n", a, vals[i] );

      }

      /* Free the values from memory */

      ldap_value_free( vals );

    }

...

See Also
ldap_get_values(), ldap_sort_strcasecmp().

ldap_sort_strcasecmp()
The ldap_sort_strcasecmp() routine compares two strings and ignores any differences in case when comparing uppercase and lowercase characters. This function is similar to the C function strcasecmp().
When sorting attribute values with ldap_sort_values(), call this function to compare the attribute values.

Syntax
#include <ldap.h>
int ldap_sort_strcasecmp( const char **a, const char **b );

Parameters
This function has the following parameters:

Table 18-124    ldap_sort_strcasecmp() function parameters

a

Pointer to first string to compare

b

Pointer to second string to compare

Returns
One of the following values:

If a is greater than b, returns a value greater than 0.

If a is equal to b, returns 0.

If a is less than b, returns a value less than 0.

See Also
ldap_sort_values().

ldap_unbind()
The ldap_unbind() function unbinds from the directory, terminates the current association, and frees the resources contained in the LDAP structure.
The ldap_unbind() routine works the same as ldap_unbind_s(); both routines are synchronous. This function is provided so that the function ldap_simple_bind() has a corresponding unbind function. For additional information, see "Closing the Connection to the Server."

Syntax
#include <ldap.h>
int ldap_unbind( LDAP *ld );

Parameters
This function has the following parameters:

Table 18-125    ldap_unbind() function parameters

ld

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

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

Example
The following code closes the current connection with the LDAP server:

Code Example 18-50    ldap_unbind() code example

...

LDAP *ld;

...

/* After completing your LDAP operations with the server, close the connection. */

if ( ldap_unbind( ld ) != LDAP_SUCCESS ) {

  ldap_perror( ld, "Error while unbinding from the directory" );

  return( 1 );

}

...

See Also
ldap_unbind_s(), ldap_unbind_ext().

ldap_unbind_s()
The ldap_unbind_s() function unbinds from the directory, terminates the current association, and frees the resources contained in the LDAP structure.

Syntax
#include <ldap.h>
int ldap_unbind_s( LDAP *ld );

Parameters
This function has the following parameters:

Table 18-126    ldap_unbind_s() function parameters

ld

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

Returns
One of the following values:

LDAP_SUCCESS if successful.

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 three unbind functions (ldap_unbind_ext(), ldap_unbind() and ldap_unbind_s()) all work synchronously in the sense that they send an unbind request to the server, close all open connections associated with the LDAP session handle, and dispose of all resources associated with the session handle before returning.
Note that there is no server response to an LDAP unbind operation. All three of the unbind functions return LDAP_SUCCESS (or another LDAP error code if the request cannot be sent to the LDAP server). After a call to one of the unbind functions, the session handle ld is invalid and it is illegal to make any further LDAP API calls using ld. For additional information, see "Closing the Connection to the Server."

Example
The following code closes the current connection with the LDAP server:

Code Example 18-51    ldap_unbind_s() code example

...

LDAP *ld;

...

/* After completing your LDAP operations with the server, close the connection. */

if ( ldap_unbind_s( ld ) != LDAP_SUCCESS ) {

  ldap_perror( ld, "Error while unbinding from the directory" );

  return( 1 );

}

...

See Also
ldap_unbind(), ldap_unbind_ext().

ldap_unbind_ext()
The ldap_unbind_ext() function unbinds from the directory, terminates the current association, and frees the resources contained in the LDAP structure.
Unlike the other two unbind functions, ldap_unbind_ext() allows you to explicitly include both server and client controls in your unbind request. However, since there is no server response to an unbind request, there is no way to receive a response from a server control that is included with your unbind request.

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

Parameters
This function has the following parameters:

Table 18-127    ldap_unbind_ext() function parameters

ld

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

serverctrls

List of LDAP server controls.

clientctrls

List of client controls.

Returns
One of the following values:

LDAP_SUCCESS if successful.

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 three unbind functions (ldap_unbind_ext(), ldap_unbind() and ldap_unbind_s()) all work synchronously in the sense that they send an unbind request to the server, close all open connections associated with the LDAP session handle, and dispose of all resources associated with the session handle before returning.
Note that there is no server response to an LDAP unbind operation. All three of the unbind functions return LDAP_SUCCESS (or another LDAP error code if the request cannot be sent to the LDAP server). After a call to one of the unbind functions, the session handle ld is invalid and it is illegal to make any further LDAP API calls using ld. For additional information, see "Closing the Connection to the Server."

Example
The following code closes the current connection with the LDAP server:

See Also
ldap_unbind(), ldap_unbind_s().

ldap_url_parse()
The ldap_url_parse() function parses an LDAP URL into its components. For more information, see "Getting the Components of an LDAP URL."

Syntax
#include <ldap.h>
int ldap_url_parse( const char *url, LDAPURLDesc **ludpp );

Parameters
This function has the following parameters:

Table 18-128    ldap_url_parse() function parameters

url

The URL that you want to check.

ludpp

Pointer to a structure containing the components of the URL.

Returns
One of the following values:

LDAP_SUCCESS if successful.

LDAP_URL_ERR_NOTLDAP if the URL does not begin with the "ldap://" or "ldaps://" prefix.

LDAP_URL_ERR_NODN if the URL missing trailing slash after host or port.

LDAP_URL_ERR_BADSCOPE if the scope within the URL is invalid.

LDAP_URL_ERR_MEM if not enough free memory is available for this operation.

LDAP_URL_ERR_PARAM if an invalid argument was passed to the function.

Example
The following section of code parses an LDAP URL and prints out each component of the URL.

Code Example 18-52    ldap_url_parse() code example

#include <ldap.h>

...

char *my_url = "ldap://ldap.netscape.com:5000/o=airius.com?cn,mail,telephoneNumber?sub?(sn=J ensen)";

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 missing trailing slash after host or port\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( "Components of the URL:\n" );

printf( "Host name: %s\n", ludpp->lud_host );

printf( "Port number: %d\n", ludpp->lud_port );

if ( ludpp->lud_dn != NULL ) {

  printf( "Base entry: %s\n", ludpp->lud_dn );

} else {

  printf( "Base entry: Root DN\n" );

}

if ( ludpp->lud_attrs != NULL ) {

  printf( "Attributes returned: \n" );

  for ( i=0; ludpp->lud_attrs[i] != NULL; i++ ) {

    printf( "\t%s\n", ludpp->lud_attrs[i] );

}

} else {

printf( "No attributes returned.\n" );

}

printf( "Scope of the search: " );

switch( ludpp->lud_scope ) {

  case LDAP_SCOPE_BASE:

    printf( "base\n" );

    break;

  case LDAP_SCOPE_ONELEVEL:

    printf( "one\n" );

    break;

  case LDAP_SCOPE_SUBTREE:

    printf( "sub\n" );

    break;

  default:

    printf( "Unknown scope\n" );

}

printf( "Filter: %s\n", ludpp->lud_filter );

...

See Also
ldap_free_urldesc().

ldap_url_search()
The ldap_url_search() function searches the directory for matching entries, based on the contents of the URL.
ldap_url_search() 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_url_search_s() instead. For more information on asynchronous and synchronous functions, see "Calling Synchronous and Asynchronous Functions."
For more information on processing LDAP searches specified as URLs, see "Processing an LDAP URL."

Syntax
#include <ldap.h>
int ldap_url_search( LDAP *ld, const char *url, int attrsonly );

Parameters
This function has the following parameters:

Table 18-129    ldap_url_search() function parameters

ld

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

url

LDAP URL specifying a search of the directory.

attrsonly

Specifies whether or not attribute values are returned along with the attribute types. This parameter can have the following values:

0 specifies that both attribute types and attribute values are returned.

1 specifies that only attribute types are returned.

Returns
Returns the message ID of the ldap_url_search() operation. To check the result of this operation, call ldap_result() and ldap_result2error().

Example

Code Example 18-53    ldap_url_search() code example

static void do_other_work();

unsigned long global_counter = 0;

int

main( int argc, char **argv )

{

  char *my_url = "ldap://ldap.netscape.com/o=airius.com?cn,mail,telephoneNumber?sub?(sn=Jensen )";

  LDAP *ld;

  LDAPMessage *result, *e;

  BerElement *ber;

  char *a, *dn;

  char **vals;

  int i, rc, finished, msgid;

  int num_entries = 0;

  struct timeval zerotime;

  zerotime.tv_sec = zerotime.tv_usec = 0L;

/* get a handle to an LDAP connection */

if ( (ld = ldap_init( MY_HOST, MY_PORT )) == NULL ) {

  perror( "ldap_init" );

  return( 1 );

}

/* authenticate to the directory as nobody */

if ( ldap_simple_bind_s( ld, NULL, NULL ) != LDAP_SUCCESS ) {

  ldap_perror( ld, "ldap_simple_bind_s" );

  return( 1 );

}

/* search for all entries with surname of Jensen */

if (( msgid = ldap_url_search( ld, my_url, 0 )) == -1 ) {

  ldap_perror( ld, "ldap_url_search" );

  return( 1 );

}

/* Loop, polling for results until finished */

finished = 0;

while ( !finished ) {

  /*

  * Poll for results. We call ldap_result with the "all" parameter

  * set to zero. This causes ldap_result() to return exactly one

  * entry if at least one entry is available. This allows us to

  * display the entries as they are received.

  */

  result = NULL;

  rc = ldap_result( ld, msgid, 0, &zerotime, &result );

  switch ( rc ) {

  case -1:

    /* some error occurred */

    ldap_perror( ld, "ldap_result" );

    return( 1 );

  case 0:

  /* Timeout was exceeded. No entries are ready for retrieval. */

    if ( result != NULL ) {

      ldap_msgfree( result );

    }

    break;

  default:

  /*

  * Either an entry is ready for retrieval, or all entries have

  * been retrieved.

  */

    if (( e = ldap_first_entry( ld, result )) == NULL ) {

      /* All done */

      finished = 1;

      if ( result != NULL ) {

        ldap_msgfree( result );

      }

      continue;

   }

    /* for each entry print out name + all attrs and values */

    num_entries++;

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

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

      ldap_memfree( dn );

    }

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

     a != NULL; a = ldap_next_attribute( ld, e, ber ) ) {

      if (( vals = ldap_get_values( ld, e, a )) != NULL ) {

        for ( i = 0; vals[ i ] != NULL; i++ ) {

          printf( "%s: %s\n", a, vals[ i ] );

        }

      ldap_value_free( vals );

      }

      ldap_memfree( a );

    }

    if ( ber != NULL ) {

      ldap_ber_free( ber, 0 );

    }

    printf( "\n" );

    ldap_msgfree( result );

  }

  /* Do other work here while you are waiting... */

  do_other_work();

}

/* All done. Print a summary. */

printf( "%d entries retrieved. I counted to %ld "

   "while I was waiting.\n", num_entries,

   global_counter );

ldap_unbind( ld );

return( 0 );

}

/*

* Perform other work while polling for results. */

static void

do_other_work()

{

global_counter++;

}

See Also
ldap_url_search_s(), ldap_result(), ldap_result2error().

ldap_url_search_s()
The ldap_url_search_s() function searches the directory for matching entries, based on the contents of the URL.
ldap_url_search_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_url_search() instead. (For more information on asynchronous and synchronous functions, see "Calling Synchronous and Asynchronous Functions.")
For more information on processing LDAP searches specified as URLs, see "Processing an LDAP URL."

Syntax
#include <ldap.h>
int ldap_url_search_s( LDAP *ld, const char *url,
  int attrsonly, LDAPMessage **res );

Parameters
This function has the following parameters:

Table 18-130    ldap_url_search_s() function parameters

ld

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

url

LDAP URL specifying a search of the directory.

attrsonly

Specifies whether or not attribute values are returned along with the attribute types. This parameter can have the following values:

0 specifies that both attribute types and attribute values are returned.

1 specifies that only attribute types are returned.

res

Results of the search (when the call is completed).

Returns
One of the following values:

LDAP_SUCCESS if successful.

If unsuccessful, returns the LDAP error code for the operation. See Chapter 19 "Result Codes" for a complete listing.

Example
The following example processes a search request from an LDAP URL.

Code Example 18-54    ldap_url_search_s() code example

#include <ldap.h>

...

LDAP *ld;

LDAPMessage *result;

char *my_url = "ldap://ldap.netscape.com/o=airius.com?cn,mail,telephoneNumber?sub?(sn=Jensen )";

...

/* Process the search request in the URL */

if ( ldap_url_search_s( ld, my_url, 0, &result ) != LDAP_SUCCESS ) {

  ldap_perror( ld, "ldap_url_search_s" );

  return( 1 );

}

...

See Also
ldap_search(), ldap_search_st().

ldap_url_search_st()
The ldap_url_search_st() function searches the directory for matching entries, based on the contents of the URL. This function works like ldap_url_search_s() and lets you specify a timeout period for the search.
For more information, see "Processing an LDAP URL."

Syntax
#include <ldap.h>
int ldap_url_search_st( LDAP *ld, const char *url, int attrsonly,
  struct timeval *timeout, LDAPMessage **res );

Parameters
This function has the following parameters:

Table 18-131    ldap_url_search_st() function parameters

ld

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

url

LDAP URL specifying a search of the directory.

attrsonly

Specifies whether or not attribute values are returned along with the attribute types. This parameter can have the following values:

0 specifies that both attribute types and attribute values are returned.

1 specifies that only attribute types are returned.

timeout

Maximum time to wait for the results of the search.

res

Results of the search (when the call is completed).

Returns
One of the following values:

LDAP_SUCCESS if successful.

If unsuccessful, returns the LDAP error code for the operation. See Chapter 19 "Result Codes" for a complete listing.

See Also
ldap_search(), ldap_search_s().

ldap_value_free()
The ldap_value_free() function frees an array of values from memory. Use the ldap_value_free_len() function instead of this function if the values are berval structures.
For additional information, see "Getting the Values of an Attribute."

Syntax
#include <ldap.h>
void ldap_value_free( char **values );

Parameters
This function has the following parameters:

Table 18-132    ldap_value_free() function parameters

values

Array of values.

Example
See the example under ldap_get_values().

See Also
ldap_get_values(), ldap_value_free_len().

ldap_value_free_len()
The ldap_value_free_len() function frees an array of berval structures from memory. Use the ldap_value_free() function instead of this function if the values are string values.
For additional information, see "Getting the Values of an Attribute."

Syntax
#include <ldap.h>
void ldap_value_free_len( struct berval **values );

Parameters
This function has the following parameters:

Table 18-133    ldap_value_free_len() function parameters

values

Array of berval structures.

Example
See the example under ldap_get_values_len().

See Also
ldap_get_values(), ldap_get_values_len().

ldap_version()
This function has been deprecated; you should use the function ldap_get_option() in its place (it is documented here for backward compatibility only).
Gets version information about the LDAP SDK for C libraries. The version information is returned in an LDAPVersion structure.

Syntax
#include <ldap.h>
int ldap_version( LDAPVersion *ver );

Parameters
This function has the following parameters:

Table 18-134    ldap_version() function parameters

ver

LDAPVersion structure returning version information. If you only want the SDK version, you can pass NULL for this parameter.

Returns
The version number of the LDAP SDK for C, multiplied by 100. For example, for version 1.0 of the LDAP SDK for C, the function returns 100.

ldapssl_advclientauth_init()
Initializes your client application to connect to a secure LDAP server over SSL and to use certificate-based client authentication.
The use of ldapssl_pkcs_init(), a version 4.0 function, is recommended over the use of this older SSL initialization function.

Syntax
#include <ldap_ssl.h>
int LDAP_CALL ldapssl_advclientauth_init( char *certdbpath,
  void *certdbhandle, int needkeydb, char *keydbpath,
  void *keydbhandle, int needsecmoddb, char *secmodpath,
  const int sslstrength);

Parameters
This function has the following parameters:

Table 18-135    ldapssl_advclientauth_init() function parameters

certdbpath

Path to the database containing certificates for your client. The database must be the cert7.db certificate database used by Netscape Communicator 4.x.
Note the following:

You can include the database filename in the path (for example, /usr/mozilla/cert7.db).

If you specify the path to the directory containing the certificate database (for example, /usr/mozilla), the function assumes that the database file is named cert7.db.

If you pass NULL for this parameter, the function looks for the certificate database used by Netscape Communicator (for example, ~/.netscape/cert7.db on UNIX).

certdbhandle

Pass a NULL value for this. (This parameter is not used currently.)

needkeydb

Specifies whether or not the private key database needs to be opened for use. This parameter can have one of the following values:

If it is a non-zero value, the function opens the private key database, which is identified by the keydbpath argument.

If 0, the function does not open the private key database.

keydbpath

Path to the database containing the private key certified by your certificate. The database must be the key3.db private key database used by Netscape Communicator 4.x.
Note the following:

You can include the database filename in the path (for example, /usr/mozilla/key3.db).

If you specify the path to the directory containing the private key database (for example, /usr/mozilla), the function assumes that the database file is named key3.db.

If you pass NULL for this parameter, the function looks for the private key database used by Netscape Communicator (for example, ~/.netscape/key3.db on UNIX).

certdbhandle

Pass a NULL value for this. (This parameter is not used currently.)

needsecmoddb

Specifies whether or not the security module database file needs to be opened for use. This parameter can have one of the following values:

If it is a non-zero value, the function opens the security module database, which is identified by the keydbpath argument.

If 0, the function does not open the security modules database.

secmodpath

Path to the database containing security modules. The database must be the secmod.db private key database used by Netscape Communicator 4.x.
Note the following:

You can include the database filename in the path (for example, /usr/mozilla/secmod.db).

If you specify the path to the directory containing the security module database (for example, /usr/mozilla), the function assumes that the database file is named secmod.db.

If you pass NULL for this parameter, the function looks for the security module database used by Netscape Communicator (for example, ~/.netscape/secmod.db on UNIX).

sslstrength

Specifies how the server certificate is evaluated. You can specify one of the following values:

LDAPSSL_AUTH_WEAK indicates that you accept the server's certificate without checking the CA who issued the certificate.

LDAPSSL_AUTH_CERT indicates that you accept the server's certificate only if you trust the CA who issued the certificate.

LDAPSSL_AUTH_CNCHECK indicates that you accept the server's certificate only if you trust the CA who issued the certificate and if the value of the cn attribute is the DNS hostname of the server.

Returns
One of the following values:

0 if successful.

-1 if unsuccessful.

Description
You can call the ldapssl_advclientauth_init() function to initialize your client application for SSL and for certificate-based client authentication.
This function is similar to ldapssl_clientauth_init() and allows you to do the following:

Specify the name and path of a security module database.

Specify the method used to verify the server's certificate.
You must call this function before calling the ldapssl_init() function to connect to the server. For details, see Chapter 12 "Connecting Over SSL."

Example
The following example initializes a client before connecting with a secure LDAP server.

Code Example 18-55    ldapssl_advclientauth_init() code example

#include <ldap_ssl.h>

#include <stdio.h>

...

/* Initialize client, using mozilla's certificate database */

if ( ldapssl_advclientauth_init( "/u/mozilla/.netscape/cert7.db",

  NULL, 1, "/u/mozilla/.netscape/key3.db", NULL , 1,

  "/u/mozilla/.netscape/secmod.db", LDAPSSL_AUTH_CNCHECK) < 0 ) {

  perror( "ldap_advclientauth_init" );

    return( 1 );

  }

}

...

See Also
ldap_init(), ldapssl_clientauth_init(), ldapssl_init(), ldapssl_install_routines().

ldapssl_client_init()
Initializes your client application to connect to a secure LDAP server over SSL.
The use of ldapssl_pkcs_init(), a version 4.0 function, is recommended over the use of this older SSL initialization function.

Syntax
#include <ldap_ssl.h>
int ldapssl_client_init( const char *certdbpath, void *certdbhandle );

Parameters
This function has the following parameters:

Table 18-136    ldapssl_client_init() function parameters

certdbpath

Path to the database containing certificates for your client. The database must be the cert7.db certificate database used by Netscape Communicator 4.x.
You can either specify the path to the directory containing the certificate database (in which case the function assumes that the database file is named cert7.db) or you can include the database filename in the path.
If you pass NULL for this parameter, the function looks for the certificate database used by Netscape Communicator (for example, ~/.netscape/cert7.db on UNIX).

certdbhandle

Pass a NULL value for this. (This parameter is not used currently.)

Returns
One of the following values:

0 if successful.

-1 if unsuccessful.

Description
You can call the ldapssl_client_init() function to initialize your client application for SSL.
If you plan to use certificate-based authentication, you should call the ldapssl_clientauth_init() or ldapssl_advclientauth_init() function instead of this function.
You must call this function before calling the ldapssl_init() function to connect to the server. For details, see Chapter 12 "Connecting Over SSL."

Example
The following example initializes a client before connecting with a secure LDAP server.

Code Example 18-56    ldapssl_client_init() code example

#include <ldap_ssl.h>

#include <stdio.h>

...

/* Initialize client, using mozilla's certificate database */

if ( ldapssl_client_init( "/u/mozilla/.netscape/cert7.db", NULL ) < 0) {

  printf( "Failed to initialize SSL client...\n" );

  return( 1 );

}

...

See Also
ldap_init(), ldapssl_init(), ldapssl_install_routines().

ldapssl_clientauth_init()
Initializes your client application to connect to a secure LDAP server over SSL and to use certificate-based client authentication.
The use of ldapssl_pkcs_init(), a version 4.0 function, is recommended over the use of this older SSL initialization function.

Syntax
#include <ldap_ssl.h>
int ldapssl_clientauth_init( char *certdbpath, void *certdbhandle,
  int needkeydb, char *keydbpath, void *keydbhandle );

Parameters
This function has the following parameters:

Table 18-137    ldapssl_clientauth_init() function parameters

certdbpath

Path to the database containing certificates for your client. The database must be the cert7.db certificate database used by Netscape Communicator 4.x.
You can either specify the path to the directory containing the certificate database (in which case the function assumes that the database file is named cert7.db) or you can include the database filename in the path.
If you pass NULL for this parameter, the function looks for the certificate database used by Netscape Communicator (for example, ~/.netscape/cert7.db on UNIX).

certdbhandle

Pass a NULL value for this. (This parameter is not used currently.)

needkeydb

Specifies whether or not the private key database needs to be opened for use. This parameter can have one of the following values:

If it is a non-zero value, the function opens the private key database, which is identified by the keydbpath argument.

If 0, the function does not open the private key database.

keydbpath

Path to the database containing the private key certified by your certificate. The database must either be the key3.db certificate database used by Netscape Communicator 4.x.
You can either specify the path to the directory containing the private key database (in which case the function assumes that the database file is named key3.db) or you can include the database filename in the path.
If you pass NULL for this parameter, the function looks for the key database used by Netscape Communicator (for example, ~/.netscape/key3.db on UNIX).

certdbhandle

Pass a NULL value for this. (This parameter is not used currently.)

Returns
One of the following values:

0 if successful.

-1 if unsuccessful.

Description
You can call the ldapssl_clientauth_init() function to initialize your client application for SSL and certificate-based client authentication.
If you need to specify the name and path of the security modules database or if you need to specify how the server's certificate will be verified, you should call the ldapssl_advclientauth_init() function instead of this function.
You must call this function before calling the ldapssl_init() function to connect to the server. For details, see Chapter 12 "Connecting Over SSL."

Example
The following example initializes a client before connecting with a secure LDAP server.

Code Example 18-57    ldapssl_clientauth_init() code example

#include <ldap_ssl.h>

#include <stdio.h>

...

/* Initialize client, using mozilla's certificate database */

if ( ldapssl_clientauth_init( "/u/mozilla/.netscape/cert7.db", NULL, 1,

  "/u/mozilla/.netscape/key3.db", NULL ) < 0 ) {

  perror( "ldap_clientauth_init" );

    return( 1 );

  }

}

...

See Also
ldap_init(), ldapssl_clientauth_init(), ldapssl_init(), ldapssl_install_routines().

ldapssl_enable_clientauth()
Enables your application to use client authentication.

Syntax
#include <ldap_ssl.h>
int ldapssl_enable_clientauth( LDAP *ld, char *keynickname,
  char *keypasswd, char *certnickname );

Parameters
This function has the following parameters:

Table 18-138    ldapssl_enable_clientauth() function parameters

ld

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

keynickname

This parameter is not currently used. Pass an empty string ("") for this value.

keypasswd

Password to the encrypted private key database.

certnickname

Nickname of the certificate that you want to use for client authentication.

Returns
One of the following values:

0 if successful.

-1 if unsuccessful.

See Also
ldapssl_clientauth_init().

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

Syntax
#include <ldap_ssl.h>
const char * LDAP_CALL ldapssl_err2string ( const int prerrno );

Parameters
This function has the following parameters:

Table 18-139    ldapssl_err2string() function parameters

prerrno

The SSL 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 SSL error code.

If unsuccessful (for example, if the error code is not a known SSL error code), returns a pointer to the string "Unknown error."

Description
This function provides support for the SSL-specific error messages that are not covered by the regular message routine ldap_err2string(). If any ldapssl_*() function returns an error code that is unknown to ldap_err2string() (and ldap_err2string() returns "Unknown Error"), this function should be called to determine the SSL-specific error message.
To check for SSL errors, you should call ldapssl_err2string() after you call any of the following SSL initialization functions:

ldapssl_client_init()

ldapssl_clientauth_init()

ldapssl_advclientauth_init()

ldapssl_pkcs_init()
The errors returned by these functions are usually related to certificate database corruption, missing certs in a certificate database, client authentication failures, and other general SSL errors.

See Also
ldapssl_client_init(), ldapssl_clientauth_init(), ldapssl_advclientauth_init(), ldapssl_pkcs_init(), ldap_err2string()

ldapssl_init()
Initializes the LDAP library for SSL and installs the I/O routines for SSL. ldapssl_init() allocates an LDAP structure but does not open an initial connection.
Calling this function is equivalent to calling ldap_init() followed by ldapssl_install_routines() and ldap_set_option() to set the LDAP_OPT_SSL option to LDAP_OPT_ON.
Before calling this function, you should call the ldapssl_client_init() function to initialize your client for SSL. For details, see Chapter 12 "Connecting Over SSL."

Syntax
#include <ldap_ssl.h>
LDAP *ldapssl_init( const char *defhost, int defport,
  int defsecure );

Parameters
This function has the following parameters:

Table 18-140    ldapssl_init() function parameters

defhost

Connect to this LDAP server, if no other server is specified.

defport

Connect to this server port, if no other port is specified. To specify the default port 389, use LDAP_PORT as the value for this parameter.

defsecure

Determines whether or not to establish the default connection over SSL. Set this to a non-zero value to establish the default connection over SSL.

Returns
One of the following values:

If successful, returns a pointer to an LDAP structure, which should be passed to subsequent calls to other LDAP API functions.

If unsuccessful, returns a -1.

Example
The following example connects your client with a secure LDAP server.

Code Example 18-58    ldapssl_init() code example

#include <ldap_ssl.h>

#include <stdio.h>

...

/* Initialize client, using mozilla's certificate database */

if ( ldapssl_client_init( "/u/mozilla/.netscape/cert5.db", NULL ) < 0) {

  printf( "Failed to initialize SSL client...\n" );

  return( 1 );

}

/* get a handle to an LDAP connection */

if ( (ld = ldapssl_init( "cert.netscape.com", LDAPS_PORT, 1 )) == NULL {

  perror( "ldapssl_init" );

  return( 1 );

}

...

/* Client can now perform LDAP operations on the secure LDAP server */

...

See Also
ldap_init(), ldapssl_client_init(), ldapssl_install_routines().

ldapssl_install_routines()
Installs the I/O routines to enable SSL over LDAP. You need to call this routine in combination with ldap_init() and ldap_set_option(). (As an alternative, you can call ldapssl_init() instead of these three functions).
As is the case with the ldapssl_init() function, you need to call ldapssl_client_init() before calling this function.

Syntax
#include <ldap_ssl.h>
int ldapssl_install_routines( LDAP *ld );

Parameters
This function has the following parameters:

Table 18-141    ldapssl_install_routines() function parameters

ld

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

Returns
One of the following values:

0 if successful.

-1 if unsuccessful.

Example
The following example connects your client with a secure LDAP server.

Code Example 18-59    ldapssl_install_routines() code example

#include <ldap_ssl.h>

#include <stdio.h>

...

/* Initialize client, using mozilla's certificate database */

if ( ldapssl_client_init( "/u/mozilla/.netscape/cert5.db", NULL ) < 0) {

  printf( "Failed to initialize SSL client...\n" );

  return( 1 );

}

/* Get the handle to an LDAP connection */

if ( (ld = ldap_init( MY_HOST, 6360 )) == NULL ) {

  perror( "ldap_init" );

  return( 1 );

}

/* Load SSL routines */

if ( ldapssl_install_routines( ld ) != LDAP_SUCCESS ) {

  ldap_perror( ld, "ldapssl_install_routines" );

  return( 1 );

}

/* Set the option to use SSL with the default connection */

if (ldap_set_option( ld, LDAP_OPT_SSL, LDAP_OPT_ON ) != LDAP_SUCCESS) {

  ldap_perror( ld, "ldap_set_option" );

  return( 1 );

}

...

See Also
ldap_init(), ldapssl_init(), ldapssl_client_init().

ldapssl_pkcs_init()
This function, added in version 4.0 of the LDAP C SDK, provides better SSL initialization than the previous ldapssl_*_init() SSL initialization functions ldapssl_client_init(), ldapssl_clientauth_init(), and ldapssl_advclientauth_init().
The function ldap_pcks_init() is preferred over these previous initialization because it is thread-safe, while the other ldapssl_*_init() functions are not.
The LDAP SDK for C uses the Public Key Cryptography Standard (PKCS) API implemented in Network Security Services (NSS) to provide SSL security support. Specifically, NSS implements the security API as defined in the PKCS#11 standard.

Syntax
#include <ldap_ssl.h>
int LDAP_CALL ldapssl_pkcs_init(const struct
  ldapssl_pkcs_fns *pfns);

Parameters
This function has the following parameters:

Table 18-142    ldapssl_pkcs_init() function parameters

pfns

A pointer to a ldapssl_okcs_fns structure that defines the callback function for obtaining the required SSL security parameters.

Returns
One of the following values:

0 is successful.

-1 if unsuccessful.

n, a positive integer, denotes an NSPR error as returned by the PR_GetError() NSPR function. Consult the NSPR documentation on mozilla.org for more information.

Description
The ldap_pkcs_init() structure sets up callbacks for the security library to obtain required runtime information. It should be used in place of ldapssl_client_init(), ldapssl_clientauth_init(), and ldapssl_advclientauth_init().
Because ldap_pkcs_init() is based on the ldapssl_pkcs_fns structure, you do not need to know all of the security parameters at initialization, unlike the other SSL initialization functions (ldapssl_*_init()), which did require all security parameters to be known at the time of initialization.
Over time, the ldapssl_*_int() functions will be deprecated in favor of ldap_pcks_init().
The ldapssl_pkcs_fns structure is defined as follows:

typedef int (LDAP_PKCS_GET_TOKEN_CALLBACK)
  (void *context, char **tokenname);

typedef int (LDAP_PKCS_GET_PIN_CALLBACK)
  (void *context, const char *tokenname, char **tokenpin);

typedef int (LDAP_PKCS_GET_CERTPATH_CALLBACK)
  (void *context, char **certpath);

typedef int (LDAP_PKCS_GET_KEYPATH_CALLBACK)(void *context,
  char **keypath);

typedef int (LDAP_PKCS_GET_MODPATH_CALLBACK)
  (void *context, char **modulepath);

typedef int (LDAP_PKCS_GET_CERTNAME_CALLBACK)
  (void *context, char **certname);

typedef int (LDAP_PKCS_GET_DONGLEFILENAME_CALLBACK)
  (void *context, char **filename);

#define PKCS_STRUCTURE_ID 1

struct ldapssl_pkcs_fns {

  int local_structure_id;

  void *local_data;

  LDAP_PKCS_GET_CERTPATH_CALLBACK *pkcs_getcertpath;

  LDAP_PKCS_GET_CERTNAME_CALLBACK *pkcs_getcertname;

  LDAP_PKCS_GET_KEYPATH_CALLBACK *pkcs_getkeypath;

  LDAP_PKCS_GET_MODPATH_CALLBACK *pkcs_getmodpath;

  LDAP_PKCS_GET_PIN_CALLBACK *pkcs_getpin;

  LDAP_PKCS_GET_TOKEN_CALLBACK *pkcs_gettokenname;

  LDAP_PKCS_GET_DONGLEFILENAME_CALLBACK *pkcs_getdonglefilename;

};

See Also
ldapssl_client_init(), ldapssl_clientauth_init(), ldapssl_advclientauth_init().

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_get_lang_values() or ldap_get_lang_values_len()	Get an attribute's value in a particular language.

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.

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

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

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 );
}
...

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.

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 );
}
...

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.

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 );
}
...

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.

...
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 ));
}
...

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.

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.

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.

...
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 );
}
...

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

#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" );
...

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.

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.

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.

#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 );
}
...

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

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

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.

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.

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.

values	Array of values.

#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 );
...

values	Array of berval structures.

#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 );
...

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.

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 );
...

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.

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.

Previous Contents Index DocHome Next
Copyright © 2000 Sun Microsystems, Inc. Some preexisting portions Copyright © 2000 Netscape Communications Corp. All rights reserved.

Last Updated November 16, 2000

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.

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.

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.

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.

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.

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.

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.

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

defhost	Space-delimited list of one or more host names (or IP address in dotted notation, such as "141.211.83.36") of the LDAP servers that you want the LDAP client to connect to. The names can be in hostname:portnumber format (in which case, portnumber overrides the port number specified by the defport argument.
defport	Default port number of the LDAP server. To specify the standard LDAP port (port 389), use LDAP_PORT as the value for this parameter.

buf	Buffer containing LDAP filter configuration information.
buflen	Size of the buffer

cache	Pointer to the LDAPMemCache structure that you want to flush entries from.
dn	Base DN identifying the search requests that you want flushed from the cache. If the base DN of a search request is within the scope specified by this DN and the scope argument, the search request is flushed from the cache. If this argument is NULL, the entire cache is flushed.
scope	Scope that (together with the dn argument) identifies the search requests that you want flushed from the cache. If the base DN of the request is within the scope specified by this argument and the dn argument, the request is flushed from the cache. This argument can have one of the following values: LDAP_SCOPE_BASE LDAP_SCOPE_ONELEVEL LDAP_SCOPE_SUBTREE

ld	Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.
cachep	When you call this function, the function sets this parameter to the pointer to the LDAPMemCache structure associated with the connection handle.

ttl	The maximum amount of time (in seconds) that an item can be cached. If 0, there is no limit to the amount of time that an item can be cached.
size	Maximum amount of memory (in bytes) that the cache will consume. If 0, the cache has no size limit.
baseDNs	An array of the base DN strings representing the base DNs of the search requests you want cached. If not NULL, only the search requests with the specified base DNs will be cached. If NULL, all search requests are cached.
thread_fns	An ldap_thread_fns structure specifying the functions that you want used to ensure that the cache is thread-safe. You should specify this if you have multiple threads that are using the same connection handle and cache. If you are not using multiple threads, pass NULL for this parameter.
cachep	When you call this function, the function sets this parameter to the pointer to the newly created LDAPMemCache structure.

ld	Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.
cache	Pointer to an LDAPMemCache structure, which represents the cache that you want used for this connection.

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 modify.
mods	Pointer to a NULL-terminated array of pointers to LDAPMod structures representing the attributes that you want to modify.

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 modify.
newrdn	New relative distinguished name (RDN) to assign to the entry.
deleteoldrdn	If this is a non-zero value, the old RDN is not retained as a value in the modified entry. If 0, the old RDN is retained as an attribute in the modified entry.

mods	Pointer to a NULL-terminated array of pointers to LDAPMod structures.
freemods	If this is a non-zero value, frees the array of pointers as well as the LDAPMod structures. If 0, just frees the LDAPMod structures.

LDAP_RES_BIND	Results from an LDAP bind operation.
LDAP_RES_SEARCH_ENTRY	Entry returned by an LDAP search operation.
LDAP_RES_SEARCH_RESULT	Results from an LDAP search operation.
LDAP_RES_MODIFY	Results from an LDAP modify operation.
LDAP_RES_ADD	Results from an LDAP add operation.
LDAP_RES_DELETE	Results from an LDAP delete operation.
LDAP_RES_MODRDN, LDAP_RES_RENAME	Results from an LDAP modify DN operation.
LDAP_RES_COMPARE	Results from an LDAP compare operation.
LDAP_RES_SEARCH_REFERENCE	Search reference returned by an LDAP search operation.
LDAP_RES_EXTENDED	Results from an LDAP extended operation.
LDAP_RES_ANY	Results from any asynchronous LDAP operation.

ld	Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.
chain	Chain of entries returned by the ldap_result() or ldap_search_s() function.
attr	Array of attributes to use when sorting the results. If NULL, results are sorted by distinguished name (DN).
cmp	Comparison function used when sorting the values.

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 in a chain of search results.

ld	Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.
ctrlp	An array of controls returned by the server. You obtain these controls by calling the ldap_get_entry_controls() function on an entry returned by the server.
changetypes	Pointer to an integer specifying the type of change made to the entry. This field can have one of the following values: LDAP_CHANGETYPE_ADD specifies that the entry was added to the directory. LDAP_CHANGETYPE_DELETE specifies that the entry was deleted from the directory. LDAP_CHANGETYPE_MODIFY specifies that the entry was modified. LDAP_CHANGETYPE_MODDN specifies that the DN or RDN of the entry was changed (a modify RDN or modify DN operation was performed).
prevdnp	Pointer to the previous DN of the entry, if the changetypes argument is LDAP_CHANGETYPE_MODDN. (If the changetypes argument has a different value, this argument is set to NULL.) When done, you can free this by calling the ldap_memfree() function.
chgnumpresentp	Pointer to an integer specifying whether or not to the change number is included in the control. The parameter can have the following possible values: 0 specifies that the change number is not included. A non-zero value specifies that the change number is included and is available as the chgnump argument.
chgnump	Pointer to the change number identifying the change made to the entry, if chgnumpresentp points to a non-zero value.

ld	Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.
res	Pointer to the LDAPMessage structure containing the results of an LDAP operation.
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.
freeit	Specifies whether or not to free the results of the operation (the LDAPMessage structure specified by the res argument). The parameter can have the following possible values: 0 specifies that the result should not be freed. A non-zero value specifies that the result should be freed.

ld	Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.
ref	Pointer to an LDAPMessage structure of the type LDAP_RES_SEARCH_REFERENCE.
referralsp	Pointer to an array of strings representing the referrals found by an LDAP search operation and returned by the server (applicable only if the LDAP operation was a search operation). When done, you can free this by calling the ldap_value_free() function.
serverctrlsp	Pointer to an array of LDAPControl structures, which represent the LDAPv3 server controls returned by the server. When done, you can free this by calling the ldap_controls_free() function.
freeit	Specifies whether or not to free the results of the operation (the LDAPMessage structure specified by the res argument). The parameter can have the following possible values: 0 specifies that the result should not be freed. A non-zero value specifies that the result should be freed.

ld	Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.
res	Pointer to the LDAPMessage structure containing the results of an LDAP operation.
errcodep	Pointer to the LDAP result code specifying the result of the operation.
matcheddnp	Pointer to a string specifying the portion of a DN that finds an existing entry (in cases where the server cannot find the entry specified by a DN). See "Receiving the Portion of the DN Matching an Entry" for details. When done, you can free this by calling the ldap_memfree() function.
errmsgp	Pointer to an additional error message string sent from the server. When done, you can free this by calling the ldap_memfree() function.
referralsp	Pointer to an array of strings representing the referrals returned by the server. When done, you can free this by calling the ldap_value_free() function.
serverctrlsp	Pointer to an array of LDAPControl structures, which represent the LDAPv3 server controls returned by the server. When done, you can free this by calling the ldap_controls_free() function.
freeit	Specifies whether or not to automatically free the results of the operation (the LDAPMessage structure specified by the res argument). The parameter can have the following possible values: 0 specifies that the result should not be freed. A non-zero value specifies that the result should be freed.