Skip to main content

Mozilla LDAP C SDK Programmer's Guide

Chapter 18 - Function Reference

This chapter contains a reference to the public functions of the LDAP C SDK. 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)

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

Summary of Functions by Task

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

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.
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.
ldapssl_client_init(), ldapssl_clientauth_init(), ldapssl_advclientauth_init(), or ldapssl_pkcs_init(). Perform once-per-process initialization required in order to use SSL.

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 "dc=example,dc=com" and
"ou=People, dc=example,dc=com" must already exist in the directory. */
char *dn = "uid=bjensen, ou=People, dc=example,dc=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, dc=example,dc=com, the entries ou=People, dc=example,dc=com and dc=example,dc=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= 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, dc=example,dc=com and if ou=People, dc=example,dc=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, dc=example,dc=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, dc=example,dc=com, the entries ou=People, dc=example,dc=com and dc=example,dc=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 "dc=example,dc=com" and
   "ou=People, dc=example,dc=com" must already exist in the directory. */
char *dn = "uid=bjensen, ou=People, dc=example,dc=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@example.com".

Code Example 18-6 - Using ldap_compare() 

>#include <stdio.h>
#include <ldap.h>
...
LDAP *ld;
char *dn = "uid=bjensen, ou=People, dc=example,dc=com";
int msgid;
...
msg_id = ldap_compare( ld, dn, "mail", "bjensen@example.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, dc=example,dc=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@example.com".

Code Example 18-7 - ldap_compare_s() code example 

#include <ldap.h>
LDAP *ld;
char *dn = "uid=bjensen, ou=People, dc=example,dc=com";
int has_value;
...
has_value = ldap_compare_s( ld, dn, "mail", "bjensen@example.com" );
switch ( has_value ) {
  case LDAP_COMPARE_TRUE:
    printf( "The mail attribute contains bjensen@example.com.\n");
    break;
  case LDAP_COMPARE_FALSE:
    printf( "The mail attribute does not contain bjensen@example.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@example.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@example.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 - ldap_create_proxyauth_control() function parameters

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