Sun logo      Previous      Contents      Index      Next     

Sun Java System LDAP SDK for C Programming Guide

Chapter 17
Function Reference

This chapter contains detailed reference material for each public function of the Sun™ Java System Directory Server Resource Kit LDAP SDK for C. Each reference gives a description of the function, and its usage syntax, parameters and return values. In many cases, an example program is also included. The chapter contains the following sections:


Typographic Conventions

The general purpose of a function is usually given by its name. Table 17-1 lists the naming conventions used when adding suffixes to function names.

Table 17-1  Function Naming Conventions 

Suffix

Description

_ext

Identifies extended functions introduced for LDAPv3. These functions are augmented through additional parameters, as compared to the functions they replace. As LDAPv3 has become widely adopted, it is recommended you use extended functions whenever possible in your new applications. See Table 17-19.

_s

Identifies the synchronous form of functions. A synchronous function will not return until it receives a response from the server, thereby blocking the caller. Similar function names without this suffix are asynchronous, allowing the caller to perform other operations while waiting for a result. (The synchronous and asynchronous forms exist only for functions which involve possible delays due to communication with the LDAP server. Functions which do not involve communication do not use this suffix.) For more information on these options, see "Managing Memory" of Chapter 4, "Using the LDAP API."


Function Summary by Task

In the following sections, the functions of the LDAP SDK for C are grouped into task categories.

Working with Basic Encoding Rules

The functions listed in Table 17-2 may be used to encode and decode with Basic Encoding Rules (BER). They are often used inside of control and extension values.

Table 17-2  Functions to Encode and Decode BER 

Function

Description

ber_alloc()
ber_alloc_t()
ber_sockbuf_alloc()
ber_special_alloc()

Allocate new BER elements.

ber_bvecfree()
ber_bvfree()
ber_free()
ber_sockbuf_free()
ber_sockbuf_free_data()

Free allocated memory.

ber_bvdup()
ber_dup()

Duplicate BER structures.

ber_init()
ber_init_w_nullchar()

Construct new structures.

ber_get_boolean()
ber_get_int()
ber_get_next()
ber_get_next_buffer()
ber_get_next_buffer_ext()
ber_get_null()
ber_get_option()
ber_get_stringa()
ber_get_stringal()
ber_get_stringb()

Retrieve miscellaneous information.

ber_put_bitstring()
ber_put_boolean()
ber_put_enum()
ber_put_int()
ber_put_null()
ber_put_ostring()
ber_put_seq()
ber_put_set()
ber_put_string()

Write miscellaneous information.

ber_first_element()
ber_next_element()
ber_peek_tag()
ber_skip_tag()

Target specific elements and tags.

ber_set_option()
ber_set_string_translators()

Set session parameters.

ber_flatten()
ber_printf()
ber_read()
ber_reset()
ber_scanf()
ber_sockbuf_get_option()
ber_sockbuf_set_option()
ber_start_seq()
ber_start_seq()
ber_start_set()
ber_svecfree()
ber_write()

Miscellaneous functions.

Managing LDAP Sessions

The functions listed in Table 17-3 manage the different phases of an LDAP session: initialization, configuration, authentication (binding) and termination (unbinding). These phases are described in more detail in Chapter 3, "Writing an LDAP Client."

Table 17-3  Functions to Manage an LDAP Session 

Function

Description

ldap_init()

Initializes an LDAP session.

ldapssl_init()

Initializes an LDAP session over SSL.

ldapssl_pkcs_init()

Initializes a thread-safe session over SSL.

ldap_get_option()
ldap_set_option()

Read and writes the current preference settings for a session.

ldap_memcache_init()
ldap_memcache_set()
ldap_memcache_get()
ldap_memcache_update()
ldap_memcache_flush()
ldap_memcache_destroy()

Creates a memory cache and uses it for search results from this session. Manages the data in the cache and frees the memory when the cache is no longer needed. The in-memory cache for search results is a Sun Java System extension to the API.

ldap_unbind_ext()

Ends an LDAP session and frees the associated data structures.

Performing LDAP Operations

The functions listed in Table 17-4 perform LDAP operations on a server and retrieve the results. These operations are covered in Chapter 7, "Adding, Modifying and Deleting Entries," Chapter 8, "Comparing Entries," and Chapter 15, "Extended Operations."

Table 17-4  Functions to Perform Operations on LDAP Server 

Function

Description

ldap_add_ext() or
ldap_add_ext_s()

Adds a new entry to the directory.

ldap_modify_ext() or
ldap_modify_ext_s()

Modifies an entry in the directory

ldap_delete_ext() or
ldap_delete_ext_s()

Deletes an entry from the directory.

ldap_rename() or
ldap_rename_s()

Renames or moves one or more entry(ies).

ldap_search_ext() or
ldap_search_ext_s()

Searches the directory.

ldap_compare_ext() or
ldap_compare_ext_s()

Compares a value with the values of an entry’s attribute.

ldap_result()

Checks the results of an asynchronous operation.

ldap_abandon_ext()

Cancels an asynchronous operation.

ldap_extended_operation() or
ldap_extended_operation_s()

Performs an LDAPv3 extended operation.

ldap_parse_extended_result()

Parses the results of an LDAPv3 extended operation.

ldap_msgfree()

Frees the memory used by the data structure for the results.

ldap_simple_bind() or
ldap_simple_bind_s()

Authenticates to an LDAP server using a password.

ldap_sasl_bind() and
ldap_parse_sasl_bind_result()
or
ldap_sasl_bind_s()

Authenticates to an LDAP server using a SASL mechanism.

ldap_set_rebind_proc()

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

Processing Search Results

Search results are given as a chain of LDAPMessage structures which can contain both entry messages and search reference messages. The functions listed in Table 17-5 retrieve the results of a search operation and process the data structures which are returned. These functions are introduced in "Getting Search Results" of Chapter 5, "Searching a LDAP Directory."

Table 17-5  Functions to Process Search Results 

Function

Description

ldap_first_message()

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

ldap_next_message()

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

ldap_count_messages()

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

ldap_msgid()

Gets the ID number of a message structure containing part of a result.

ldap_msgtype()

Determines whether a message structure contains an entry or a search reference.

ldap_msgfree()

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

ldap_first_entry()

Gets the first entry in a chain of search results.

ldap_next_entry()

Gets the next entry in a chain of search results.

ldap_count_entries()

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

ldap_first_reference()

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

ldap_next_reference()

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

ldap_count_references()

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

ldap_parse_reference()

Extracts the referral strings from a search reference.

Reading the Contents of an Entry

The functions listed in Table 17-6 are used to access the contents of an entry returned as a search result. These functions are described in "Getting Distinguished Names for Each Entry" and "Getting Attribute Names from an Entry" of Chapter 5, "Searching a LDAP Directory."

Table 17-6  Functions to Access Contents of an Entry 

Function

Description

ldap_get_dn()

Get the DN for an entry.

ldap_explode_dn()
ldap_explode_rdn()

Split a DN or relative DN into its components.

ldap_explode_dns()

Takes a DNS-style DN and breaks it up into its components.

ldap_is_dns_dn()

Determines the style of the DN.

ldap_dn2ufn()

Removes cryptic type names to make a DN easier to read.

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

With the functions listed in Table 17-7, your LDAP client can sort the data structures returned as search results. These functions are demonstrated in "Sorting Entries by an Attribute" and "Sorting the Values of an Attribute" in Chapter 5, "Searching a LDAP Directory."

Table 17-7  Client-side Sorting Functions 

Function

Description

ldap_sort_entries()

Sorts search results by DN or by a single attribute.

ldap_multisort_entries()

Sorts search results by by multiple attributes

ldap_keysort_entries()

Sorts search results using key(s).

ldap_sort_values()

Sorts the values of an attribute.

ldap_sort_strcasecmp()

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

Sun Java System Directory Server and others also provide server-side sorting through LDAPv3 controls. The controls mechanism is described in Chapter 13, "Working with LDAP Controls," including the following server-side sorting functions which are shown in "Using the Server-Side Sorting Control".

Table 17-8  Server-side Sorting Functions 

Function

Description

ldap_create_sort_keylist()

Define the criteria for sorting entries by attribute values.

ldap_free_sort_keylist()

Free the memory for the sort criteria data structure.

ldap_create_sort_control()

Create the sort control structure needed for server-side sorting.

ldap_control_free()

Free the memory for the sort control data structure.

ldap_parse_sort_control()

Analyze the server’s response to the sort control.

ldap_controls_free()

Free the memory for the sort control response data structure.

Working with Search Filters

The functions listed in Table 17-9 retrieve and build filters using a filter configuration file. Use this mechanism to create complex filters to pass to the search functions. Filters and filter configuration files are described in Chapter 6, "Using Filter Configuration Files."

Table 17-9  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 string from a buffer.

ldap_getfilter_free()

Free the filter configuration data structure from memory.

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

Build a filter without using the filter configuration file mechanism.

Using LDAPv3 Controls

Sun Java System Directory Server and others also provide additional functionality throught LDAPv3 controls. The functions listed in Table 17-10 configure LDAPv3 control structures which ask the server to perform advanced operations. This mechanism is described in Chapter 13, "Working with LDAP Controls."

Table 17-10  Functions to Manage LDAPv3 Controls 

Function

Description

ldap_create_persistentsearch_control()
ldap_get_entry_controls()
ldap_parse_entrychange_control()

Track changes to an entry or a set of entries by setting the persistent search control and analyzing the entry change control sent by the server.

ldap_create_sort_keylist()
ldap_free_sort_keylist()
ldap_create_sort_control()
ldap_parse_sort_control()

Define and send criteria for server-side sorting of search results and check the server’s response

ldap_create_virtuallist_control()
ldap_parse_virtuallist_control()

Use in conjuction with server- side sorting to limit and handle the number of results returned to the client.

ldap_create_proxiedauth_control()

Define a proxy authorization control to perform an operation under a different bind DN

ldap_parse_result()

Parse an LDAP response from the server to extract the result and the response to the control.

Using Sun Java System Extensions

The functions listed in Table 17-11 are utility functions for parsing space-separated host lists. This is useful for implementing an extended I/O CONNECT callback function.

Table 17-11  Sun Java System Extensions

Function

Description

ldap_x_hostlist_first()
ldap_x_hostlist_next()
ldap_x_hostlist_status()

Utility functions for parsing space-separated host lists.

Working with LDAP URLs

The functions listed in Table 17-12 interpret LDAP URLs (universal resource locators of the form ldap://...). For additional information, see Chapter 9, "Working with LDAP URLs."

Table 17-12  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()
ldap_url_search_st()

Perform the search specified by an LDAP URL.

ldap_free_urldesc()

Free the memory allocated for a parsed URL.

Working with UTF-8 Encoding

The functions listed in Table 17-13 work with strings and characters that use UTF-8 encoding.

Table 17-13  Functions to Handle UTF-8 Encoding 

Function

Description

ldap_utf8len()

Function to determine bytel length.

ldap_utf8next()

Function to get next character.

ldap_utf8prev()

Function to get previous character.

ldap_utf8copy()

Function to copy a character to a destination.

ldap_utf8characters()

Function to return the number of characters.

ldap_utf8getcc()

Function moves the pointer to the next character following a UCS-4 character.

ldap_utf8strtok_r()

Function moves the pointer to the next character following a UCS-4 character.

ldap_utf8isalnum()
ldap_utf8isalpha()
ldap_utf8isdigit()
ldap_utf8len()
ldap_utf8isspace()

Functions to determine characteristics of the character.

Handling Errors

The functions listed in Table 17-14 handle errors returned by the functions. Chapter 18, "Result Codes" lists all of the error and status codes used in the LDAP SDK for C. You can also find details about possible errors in the reference section for each function.

Table 17-14  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.

Managing Memory

The functions listed in Table 17-15 free memory allocated by the LDAP SDK for C functions. See Table 4-1 in the "Managing Memory" section of Chapter 4, "Using the LDAP API" for a list of all functions which allocate memory that needs to be freed.

Table 17-15  Functions to Free Memory 

Function

Description

ber_bvfree()

Free the memory allocated for a berval structure.

ber_free()

Free the memory of a BerElement structure.

ldap_control_free()

Free the memory of an LDAPControl structure.

ldap_controls_free()

Free an array of LDAPControl structures.

ldap_free_friendlymap()

Free the memory of a FriendlyMap structure

ldap_free_sort_keylist()

Free an array of LDAPsortkey structures

ldap_free_urldesc()

Free the memory of an LDAPURLDesc structure

ldap_getfilter_free()

Free the memory of an LDAPFiltDesc structure.

ldap_memfree()

General function for freeing memory of any other data structure

ldap_mods_free()

Free an array of LDAPMod structure.

ldap_msgfree()

Free the memory of an LDAPMessage structure.

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)

You may also manage memory directly with the functions in Table 17-16.

Table 17-16  Functions to Directly Manage Memory 

Function

Description

ldap_x_malloc()

Allocates memory.

ldap_x_calloc()

Allocates memory for an array of elements.

ldap_x_realloc()

Changes the size of a memory block.

ldap_x_free()

Frees a block of memory.

Working with Netscape Portable Runtime

The functions listed in Table 17-17 tie libldap into Netscape Portable Runtime (NSPR).

Table 17-17  Functions to Work with Netscape Portable Runtime 

Function

Description

prldap_get_default_socket_info()

Gets default socket information.

prldap_get_session_info()

Gets application-specific data.

prldap_get_session_option()

Gets a session option specific to the prldap layer.

prldap_get_socket_info()

Gets socket information.

prldap_init()

Creates a new NSPR session handle.

prldap_install_routines()

Installs NSPR functions for use with LDAP handle.

prldap_set_default_socket_info()

Sets default socket information.

prldap_set_session_info()

Sets application-specific data.

prldap_set_session_option()

Sets a session option specific to the prldap layer.

prldap_set_socket_info()

Sets socket information.

Deprecated and Outdated Functions

The functions listed in first column of Table 17-18 should no longer be used; they have been superceded by the newer functions listed in the second column of Table 17-18. Deprecated functions are those being dropped from the standard or from the Sun Java System extensions to the LDAP SDK for C. Outdated functions are those which are not officially deprecated but which have newer, extended functions for performing the same operation.


Note

Deprecated functions are not guaranteed to be implemented in future versions of the API. However, all of these functions are still implemented in this version for backwards compatibility. For maintenance reasons, they have often been reimplemented to simply call the newer function which performs the same task.


Table 17-18  Deprecated Functions and Their Replacement 

Deprecated Function

Replacement

ldap_ber_free()

Replaced by ber_free().

ldap_bind()
ldap_bind_s()

Replaced by ldap_simple_bind() and ldap_simple_bind_s(), respectively.

ldap_build_filter()

Replaced by ldap_create_filter().

ldap_cache_flush()

Replaced by ldap_memcache_*() functions.

ldap_charray_add()
ldap_charray_dup()
ldap_charray_free()
ldap_charray_inlist()
ldap_charray_merge()
ldap_charray_position()
ldap_str2charray()

None documented to replace these character array functions.

ldap_create_proxyauth_control()

Replaced by Description.

ldap_get_lang_values()
ldap_get_lang_values_len()

Rarely used, no replacement.

ldap_modrdn()

Replaced by ldap_modrdn2(), itself outdated by ldap_rename().

ldap_modrdn_s()

Replaced by ldap_modrdn2_s(), itself outdated by ldap_rename_s().

ldap_open()

Replaced by ldap_init() and one of the bind functions.

ldap_result2error()

Replaced by ldap_parse_result().

ldap_setfilteraffixes()

Replaced by ldap_set_filter_additions().

ldap_ufn_search_c()
ldap_ufn_search_ct()
ldap_ufn_search_s()
ldap_ufn_setfilter()
ldap_ufn_setprefix()
ldap_ufn_timeout()

None documented to replace these user-friendly search functions.

ldap_version()

Replaced by ldap_get_option().

Outdated Standard Functions and Equivalents

Many LDAPv2 functions are outdated now that LDAPv3 has been widely adopted. Table 17-19 lists both the outdated function and its new equivalent. Although LDAPv2 functions remain in the standard specification, you should use the LDAPv3 functions in any new client applications. Again, for maintenance reaons, the outdated functions have often been reimplemented to simply call the newer function.

Table 17-19  Outdated LDAPv2 Functions and New Equivalent 

LDAPv2 Functions

LDAPv3 Equivalent

ldap_abandon()

ldap_abandon_ext()

ldap_add()
ldap_add_s()

ldap_add_ext()
ldap_add_ext_s()

ldap_compare()
ldap_compare_s()

ldap_compare_ext()
ldap_compare_ext_s()

ldap_delete()
ldap_delete_s()

ldap_delete_ext()
ldap_delete_ext_s()

ldap_modify()
ldap_modify_s()

ldap_modify_ext()
ldap_modify_ext_s()

ldap_modrdn2()
ldap_modrdn2_s()

ldap_rename()
ldap_rename_s()

ldap_search()
ldap_search_s()
ldap_search_st()

ldap_search_ext()
ldap_search_ext_s()
ldap_search_ext_s() - use timeout argument

ldap_unbind()
ldap_unbind_s()

ldap_unbind_ext() replaces both forms which are identical besides the suffix.


Functions Alphabetically


ber_alloc()

The ber_alloc() function is used to allocate a new Basic Encoding Rules (BER) BerElement structure.

Syntax

#include <lber.h>
BerElement* ber_alloc( void );

Parameters

This function has no parameters.

Returns
Description

ber_alloc() is used to allocate a new BerElement structure for encoding data with the BER.

See Also

ber_printf(), BerElement


ber_alloc_t()

The ber_alloc_t() function constructs and returns a BerElement structure.

Syntax

#include <lber.h>
BerElement* ber_alloc_t( int options );

Parameters

This function has the parameter listed in Table 17-20.

Table 17-20  ber_alloc_t() Function Parameter

Parameter

Description

options

Contains bitwise OR of options to be used when generating the encoding of the BerElement. One option is defined and must always be supplied:

#define LBER_USE_DER 0x01

When this option is present, lengths will always be encoded in the minimum number of octets. This option does not cause values of sets and sequences to be rearranged in tag and byte order, so these functions are not suitable for generating DER output as defined in X.509 and X.680.

Returns
Description

This function is the same as ber_alloc() except it has an option.

See Also

ber_printf(), BerElement


ber_bvecfree()

The ber_bvecfree() function frees an array of berval structures.

Syntax

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

Parameters

This function has the parameter listed in Table 17-21.

Table 17-21  ber_bvecfree() Function Parameter 

Parameter

Description

bv

Pointer to the array that you want to free from memory.

Description

Each berval in the array is freed using ber_bvfree(), and then the array itself is freed.

See Also

ber_bvfree()


ber_bvdup()

The ber_bvdup() function returns a copy of a berval structure.

Syntax

#include <lber.h>
berval* ber_bvdup( const struct berval *bv );

Parameters

This function has the parameter listed in Table 17-22.

Table 17-22  ber_bvdup() Function Parameter 

Parameter

Description

bv

Pointer to the berval structure to be duplicated.

Returns
Description

The ber_bvdup() function returns a copy of a berval structure. The data referenced in the structure is also duplicated. The bv_val field in the returned berval points to a different area of memory than the bv_val field in the argument berval.


ber_bvfree()

The ber_bvfree() function frees a berval structure.

Syntax

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

Parameters

This function has the parameter listed in Table 17-23.

Table 17-23  ber_bvfree() Function Parameter

Parameter

Description

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 a berval passed back from the ldap_extended_operation_s(), ldap_parse_extended_result(), ldap_sasl_bind_s(), or 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_dup()

The ber_dup() function returns a copy of a BerElement structure.

Syntax

#include <lber.h>
BerElement* ber_dup( BerElement *ber );

Parameters

This function has the parameters listed in Table 17-24.

Table 17-24  ber_dup() Function Parameter 

Parameter

Description

ber

Pointer to the BerElement to be duplicated.

Returns
Description

The ber_dup() function returns a copy of a BerElement structure.


ber_first_element()

The ber_first_element() function is used to return the tag and length of the first element in a set or sequence.

Syntax

#include <lber.h>
unsigned long ber_first_element( BerElement *ber, unsigned long *len,
  char **last );

Parameters

This function has the parameters listed in Table 17-25.

Table 17-25  ber_first_element() Function Parameters 

Parameter

Description

ber

Pointer to a BerElement.

len

Pointer to the address of the unsigned long which returns the length of the first element.

last

Address of the pointer to return the address of the last byte of the element.

Returns

NULL pointer is returned on error.

Description

The ber_first_element() function is used to return the tag and length of the first element in a set or sequence. It also returns a magic cookie parameter that should be passed to subsequent calls to ber_next_element().

See Also

ber_next_element()


ber_flatten()

The ber_flatten() function allocates a berval structure whose contents are taken from a source BerElement structure.

Syntax

#include <lber.h>
int ber_flatten( BerElement *ber, struct berval **bvPtr );

Parameters

This function has the parameters listed in Table 17-26.

Table 17-26  ber_flatten() Function Parameters 

Parameter

Description

ber

Pointer to the source BerElement.

bvPtr

Pointer to the newly allocated berval structure which must be freed using ber_bvfree().

Returns

Returns 0 on success and -1 on error.

Description

This function is usually used when encoding LDAPv3 controls or extended operations values.

See Also

ber_bvfree()


ber_free()

The ber_free() function frees a BerElement structure previously allocated with ber_alloc(), ber_alloc_t(), ber_init(), or the ldap_first_attribute() and ldap_next_attribute() search functions.

Syntax

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

Parameters

This function has the parameters listed in Table 17-27.

Table 17-27  ber_free() Function Parameters 

Parameter

Description

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

This function frees 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 it still exists.


Note

To retrieve attributes from a search result entry, you need to call either the ldap_first_attribute() or ldap_next_attribute() function. When freeing structures allocated by these functions, you should specify 0 for the freebuf argument. Otherwise, it should always be set to 1.


Example

Code Example 17-1 frees the BerElement structure allocated by the ldap_first_attribute() function.

Code Example 17-1  ber_free() Code Example

LDAP *ld;

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

ber_alloc(), ber_alloc_t(), ber_init(), ldap_first_attribute(), ldap_next_attribute()


ber_get_boolean()

The ber_get_boolean() function is used to read a boolean value.

Syntax

#include <lber.h>
unsigned long ber_get_boolean( BerElement *ber,
  int *boolval );

Parameters

This function has the parameters listed in Table 17-28.

Table 17-28  ber_get_boolean() Function Parameters 

Parameter

Description

ber

Pointer to the BerElement structure that contains the boolean.

boolval

Specifies the boolean to read.

Returns

The value is returned on success and LBER_ERROR (-1) on failure.


ber_get_int()

The ber_get_int() function tries to interpret the next element as an integer, returning the result in num.

Syntax

#include <lber.h>
unsigned long ber_get_int( BerElement *ber, int *num );

Parameters

This function has the parameters listed in Table 17-29.

Table 17-29  ber_get_int() Function Parameters 

Parameter

Description

ber

Pointer to the BerElement structure that contains the boolean.

num

Pointer to the result.

Returns

The tag of whatever it finds is returned on success and LBER_ERROR (-1) on failure.


ber_get_next()

The ber_get_next() function reads the next BER element.

Syntax

#include <lber.h>
unsigned long ber_get_next( Sockbuf *sb, unsigned long *len,
  BerElement *ber );

Parameters

This function has the parameters listed in Table 17-27.

Table 17-30  ber_get_next() Function Parameters 

Parameter

Description

sb

Descriptor (socket or file descriptor) from which to read.

len

The length of the entire element.

ber

Pointer to the BerElement structure.

Description

ber_get_next() strips off and returns the leading tag, strips off and returns the length of the entire element, and sets up a pointer to ber for subsequent calls to decode the element.


ber_get_next_buffer()

The ber_get_next_buffer() function reads the next BER element from a byte buffer.


Note

This is an older function included in the SDK for backward-compatibility. If you are writing a new LDAP client, use ber_get_next_buffer_ext() instead.



ber_get_next_buffer_ext()

The ber_get_next_buffer_ext() function reads the next BER element from a byte buffer.


Note

ber_get_next_buffer_ext() is a new version of the ber_get_next_buffer() function. If you are writing a new LDAP client, use ber_get_next_buffer_ext().


Syntax

#include <lber.h>
unsigned long ber_get_next_buffer_ext( void *buffer,
  size_t buffer_size, unsigned long *len, BerElement *ber,
  unsigned long *Bytes_Scanned, Sockbuf *sb );

Parameters

This function has the parameters listed in Table 17-31.

Table 17-31  ber_get_next_buffer_ext() Function Parameters 

Parameter

Description

buffer

Pointer to the buffer.

buffer_size

The size of the buffer.

len

The length of the entire element.

ber

Pointer to a BerElement.

Bytes_Scanned

Returns the number of bytes actually searched through.

sb

Descriptor (socket or file descriptor) from which to read.


ber_get_null()

The ber_get_null() function is used to read a NULL element.

Syntax

#include <lber.h>
unsigned long ber_get_null( BerElement *ber );

Parameters

This function has the parameter listed in Table 17-32.

Table 17-32  ber_get_null() Function Parameter 

Parameter

Description

ber

Pointer to a BerElement.

Returns

Returns the tag of the element it skips over.


ber_get_option()

The ber_get_option() function is used to retrieve information about the API and about the specific implementation being used.

Syntax

#include <lber.h>
int ber_get_option( BerElement *ber, int option, void *value );


ber_get_stringa()

The ber_get_stringa() function is used to allocate memory space into which an octet string is read.

Syntax

#include <lber.h>
unsigned long ber_get_stringa( BerElement *ber, char **buf );


ber_get_stringal()

The ber_get_stringal() function is used to allocate memory space into which an octet string and its length are read.

Syntax

#include <lber.h>
unsigned long ber_get_stringal( BerElement *ber, struct berval **bv );

Description

It takes a berval structure, and returns the result in this parameter.


ber_get_stringb()

The ber_get_stringb() function is used to read an octet string into a preallocated buffer.

Syntax

#include <lber.h>
unsigned long ber_get_stringb( BerElement *ber, char *buf,
  unsigned long *len );

Description

The len parameter should be initialized to the size of the buffer, and will contain the length of the octet string read upon return. The buffer should be big enough to take the octet string value plus a terminating NULL byte.


ber_init()

The ber_init() function constructs a new BerElement.

Syntax

#include <lber.h>
BerElement * ber_init( const struct berval *bv );

Parameters

This function has the parameter listed in Table 17-32.

Table 17-33  ber_init() Function Parameter 

Parameter

Description

bv

Pointer to a berval.

Returns


ber_init_w_nullchar()

The ber_init_w_nullchar() function constructs a new BerElement with a NULL character.

Syntax

#include <lber.h>
void ber_init_w_nullchar( BerElement *ber, int options );


ber_next_element()

The ber_next_element() function is used to return the tag and length of the next element in a set or sequence.

Syntax

#include <lber.h>
unsigned long ber_next_element( BerElement *ber, unsigned long *len,
  char *last );

Parameters

This function has the parameters listed in Table 17-34.

Table 17-34  ber_next_element() Function Parameters 

Parameter

Description

ber

Pointer to a BerElement.

len

Pointer to the address of the unsigned long which returns the length of the next element.

last

Address of the pointer to return the address of the last byte of the element.

Returns

NULL pointer is returned on error.

Description

The ber_next_element() function is used to return the tag and length of the first element in a set or sequence.

See Also

ber_first_element()


ber_peek_tag()

The ber_peek_tag() function returns the tag of the next element to be parsed in the supplied BerElement structure.

Syntax

#include <lber.h>
unsigned long ber_peek_tag( BerElement *ber, unsigned long *len );

Parameters

This function has the parameters listed in Table 17-35.

Table 17-35  ber_peek_tag() Function Parameters 

Parameter

Description

ber

Pointer to a BerElement.

len

Pointer to the address of the unsigned long which returns the length of the next element.

Returns

Returns the tag of the next element to be read in the BerElement structure. LBER_DEFAULT is returned if there is no further data to be read.


ber_printf()

The ber_printf() function encodes a BER element.

Syntax

#include <lber.h>
ber_printf( BerElement *ber, const char *fmt, ... );

Parameters

This function has the parameters listed in Table 17-36.

Table 17-36  ber_printf() Function Parameters 

Parameter

Description

ber

Pointer to a BerElement returned by ber_alloc() or ber_alloc_t().

fmt

Defines the encoding format string. The format string can contain the following characters:

  • -b Boolean. An integer parameter should be supplied. A boolean element is output.
  • -i Integer. An integer parameter should be supplied. An integer element is output.
  • -B Bitstring. A char * pointer to the start of the bitstring is supplied, followed by the number of bits in the bitstring. A bitstring element is output.
  • -n Null. No parameter is required. A NULL element is output.
  • -o Octet string. A char * is supplied, followed by the length of the string pointed to. An octet string element is output.
  • -s Octet string. A NULL-terminated string is supplied. An octet string element is output, not including the trailing NULL octet.
  • -t Tag. An int specifying the tag to give the next element is provided. This works across calls.
  • -v Several octet strings. A NULL-terminated array of char *'s is supplied. Note that a construct like '{v}' is required to get an actual sequence of octet strings.
  • -{ Begin sequence. No parameter is required.
  • -} End sequence. No parameter is required.
  • -[ Begin set. No parameter is required.
  • -] End set. No parameter is required.

...

Values to be encoded.

Description

State information is kept with the ber parameter so multiple calls can be made to ber_printf() to append things to the end of the BerElement. ber_printf() interprets and formats its arguments according to the format string fmt. Each character in fmt refers to an argument to ber_printf().

Returns

-1 if there is an error during encoding.


ber_put_bitstring()

The ber_put_bitstring() function writes a bitstring value to the given BerElement.

Syntax

#include <lber.h>
int ber_put_bitstring( BerElement *ber, char *str,
  unsigned long bitlen, unsigned long tag );

Description

The ber_put_bitstring() function writes bitlen bits starting at str as a bitstring value to the given BerElement.


ber_put_boolean()

The ber_put_boolean() function writes a boolean value to a BerElement.

Syntax

#include <lber.h>
int ber_put_boolean( BerElement *ber, int boolval, unsigned long tag );

Description

The boolean value is given by boolval to the BerElement.


ber_put_enum()

The ber_put_enum() function writes an enumerated value to a BerElement.

Syntax

#include <lber.h>
int ber_put_enum( BerElement *ber, long num, unsigned long tag );


ber_put_int()

The ber_put_int() function writes an integer to a BerElement.

Syntax

#include <lber.h>
int ber_put_int( BerElement *ber, long num, unsigned long tag );


ber_put_null()

The ber_put_null() function writes a writes a NULL element to a BerElement.

Syntax

#include <lber.h>
int ber_put_null( BerElement *ber, unsigned long tag );


ber_put_ostring()

The ber_put_ostring() function writes bytes to a BerElement as an octet string.

Syntax

#include <lber.h>
int ber_put_ostring( BerElement *ber, char *str,
  unsigned long len, unsigned long tag );


ber_put_seq()

The ber_put_seq() function puts a sequence to a BerElement.

Syntax

#include <lber.h>
int ber_put_seq( BerElement *ber );

Parameters

This function has the parameter listed in Table 17-37.

Table 17-37  ber_put_seq() Function Parameter 

Parameter

Description

ber

Pointer to a BerElement.

Description

The ber_start_seq() function is used to start a sequence in the BerElement. The end of the sequence is marked by the nearest matching call to ber_put_seq().


ber_put_set()

The ber_put_set() function puts a set to a BerElement.

Syntax

#include <lber.h>
int ber_put_set( BerElement *ber );

Parameters

This function has the parameter listed in Table 17-38.

Table 17-38  ber_put_set() Function Parameter 

Parameter

Description

ber

Pointer to a BerElement.

Description

The ber_start_set() function is used to start a set in the BerElement. The end of the set is marked by the nearest matching call to ber_put_set().


ber_put_string()

The ber_put_string() function writes a NULL-terminated string (minus the terminating 0) to a BerElement as an octet string.

Syntax

#include <lber.h>
int ber_put_string( BerElement *ber, char *str, unsigned long tag );


ber_read()

Syntax

#include <lber.h>
long ber_read( BerElement *ber, char *buf, unsigned long len );


ber_reset()

Syntax

#include <lber.h>
void ber_reset( BerElement *ber, int was_writing );


ber_scanf()

The ber_scanf() function decodes a BerElement.

Syntax

#include <lber.h>
unsigned long ber_scanf( BerElement *ber, const char *fmt, ... );

Parameters

This function has the parameters listed in Table 17-39.

Table 17-39  ber_scanf() Function Parameters 

Parameter

Description

ber

Pointer to a BerElement as returned by ber_get_next().

fmt

Defines the encoding format string. The format string can contain the following characters:

  • -a Octet string. A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, NULL-terminated, and returned in the parameter.
  • -s Octet string. A char * buffer should be supplied, followed by a pointer to an integer initialized to the size of the buffer. Upon return, the NULL-terminated octet string is put into the buffer, and the integer is set to the actual size of the octet string.
  • -O Octet string. A struct ber_val ** should be supplied, which upon return points to a memory allocated struct berval containing the octet string and its length. Call ber_bvfree() to free allocated memory.
  • -b Boolean. A pointer to an integer should be supplied.
  • -i Integer. A pointer to an integer should be supplied.
  • -B Bitstring. A char ** should be supplied which will point to the memory allocated bits, followed by an unsigned long *, which will point to the length (in bits) of the bitstring returned.
  • -n Null. No parameter is required. The element is simply skipped if it is recognized.
  • -v Sequence of octet strings. A char *** should be supplied, which upon return points to a memory allocated NULL-terminated array of char *'s containing the octet strings. NULL is returned if the sequence is empty.
  • -V Sequence of octet strings with lengths. A struct berval *** should be supplied, which upon return points to a memory allocated, NULL-terminated array of struct berval *'s containing the octet strings and their lengths. NULL is returned if the sequence is empty. ber_bvecfree() can be called to free the allocated memory.
  • -x Skip element. The next element is skipped.
  • -{ Begin sequence. No parameter is required. The initial sequence tag and length are skipped.
  • -} End sequence. No parameter is required and no action is taken.
  • -[ Begin set. No parameter is required. The initial set tag and length are skipped.
  • -] End set. No parameter is required and no action is taken.

...

Values to be encoded.

Description

ber_scanf() reads from ber, interprets the bytes according to the format string fmt, and stores the results in its additional arguments. The format string contains conversion specifications which are used to direct the interpretation of the BER element.

See Also

ber_printf()


ber_set_option()

Syntax

#include <lber.h>
int ber_set_option( BerElement *ber, int option, void *value );


ber_set_string_translators()

Syntax

#include <lber.h>
unsigned long ber_skip_tag( BerElement *ber, unsigned long *len );


ber_skip_tag()

The ber_skip_tag() function advances the pointer to a BerElement past the first tag and length to the next tag.

Syntax

#include <lber.h>
unsigned long ber_skip_tag( BerElement *ber, unsigned long *len );

Parameters

This function has the parameters listed in Table 17-40.

Table 17-40  ber_skip_tag() Function Parameters 

Parameter

Description

ber

Pointer to a BerElement.

len

Pointer to the length of the value to be skipped.

Description

ber_skip_tag() should only be used with constructed types and situations when a BER encoding is used as the value of an octet string.

See Also

ber_peek_tag()


ber_sockbuf_alloc()

Syntax

#include <lber.h>
Sockbuf* ber_sockbuf_alloc( void );


ber_sockbuf_free()

Syntax

#include <lber.h>
void ber_sockbuf_free( Sockbuf* p );


ber_sockbuf_free_data()

Syntax

#include <lber.h>
void ber_sockbuf_free_data(Sockbuf *p);


ber_sockbuf_get_option()

Syntax

#include <lber.h>
int ber_sockbuf_get_option( Sockbuf *sb, int option, void *value );


ber_sockbuf_set_option()

Syntax

#include <lber.h>
int ber_sockbuf_set_option( Sockbuf *sb, int option, void *value );


ber_special_alloc()

The ber_special_alloc() function allocates a BerElement structure plus some extra memory.

Syntax

#include <lber.h>
void* ber_special_alloc( size_t size, BerElement **ppBer );

Returns

Returns a pointer to the BerElement and a pointer to the extra memory.

Description

ber_special_alloc() allocates a ber data buffer within the same block, thus saving a call to calloc later when we read data.


ber_special_free()

The ber_special_free() function frees an allocated BerElement structure.

Syntax

#include <lber.h>
void ber_special_free( void* buf, BerElement *ber );

See Also

ber_special_alloc()


ber_stack_init()

Syntax

#include <lber.h>
int) LDAP_CALL ber_stack_init(BerElement *ber, int options,
  char * buf, size_t size);


ber_start_seq()

The ber_start_seq() function is used to start a sequence in a BerElement.

Syntax

#include <lber.h>
int ber_start_seq( BerElement *ber, unsigned long tag );

See Also

ber_put_seq()


ber_start_set()

The ber_start_seq() function is used to start a set in a BerElement.

Syntax

#include <lber.h>
int ber_start_set( BerElement *ber, unsigned long tag );

See Also

ber_put_set()


ber_svecfree()

Syntax

#include <lber.h>
void ber_svecfree( char **vals );


ber_write()

Syntax

#include <lber.h>
long ber_write( BerElement *ber, char *buf,
  unsigned long len, int nosos );


ldap_abandon()

The ldap_abandon() function cancels an asynchronous LDAP operation that is in progress.


Note

This is an older function included in the SDK 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 parameters listed in Table 17-41.

Table 17-41  ldap_abandon() Function Parameters 

Parameter

Description

ld

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:

Description

Please use the newer version of this function, ldap_abandon_ext().

Example

Code Example 17-2 cancels an ldap_url_search() operation, abandoning the results of the operation.

Code Example 17-2  Cancelling 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()

The ldap_abandon_ext() function cancels an asynchronous LDAP operation that is in progress.


Note

ldap_abandon_ext() is a new version of the ldap_abandon() function. If you are writing a new LDAP client, use ldap_abandon_ext().


Syntax

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

Parameters

This function has the parameters listed in Table 17-42.

Table 17-42  ldap_abandon_ext() Function Parameters 

Parameter

Description

ld

Pointer to an LDAP structure containing information about the connection to the LDAP server.

msgid

Message ID of an LDAP operation to identify the operation to be cancelled. When you call an asynchronous function (such as ldap_search_ext()), the msgidp argument returns a pointer to a message ID that uniquely identifies the operation. Thus, when you call ldap_abandon_ext(), your LDAP client is able to send a request specifying the message ID of the operation to be cancelled.

serverctrls

Pointer to an array of LDAPControl structures representing LDAP server controls that apply to this 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 operation. If you do not want to pass any client controls, specify NULL for this argument.

Returns

One of the following values:

Description

The ldap_abandon_ext() function cancels 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 it. 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. Once cancelled, the results of the operation will not be returned, even if you subsequently call ldap_result() to retrieve them. To identify the operation to be cancelled, specify the message ID of the operation in the msgid argument of the ldap_abandon_ext() function.

For more information, see "To Cancel an Operation in Progress" of Chapter 4, "Using the LDAP API."

Example

Code Example 17-3 cancels an ldap_url_search() operation, abandoning the results of the operation.

Code Example 17-3  ldap_abandon_ext() Code Example 

LDAP *ld;

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

The ldap_add() function adds a new entry to the directory asynchronously.


Note

This is an older function that is included in the SDK 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 parameters listed in Table 17-43.

Table 17-43  ldap_add() Function Parameters

Parameter

Description

ld

Pointer to an LDAP structure containing information about the connection to the LDAP server.

dn

DN of the entry to add. With the exception of the leftmost component, all components of the DN (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.


Note

To check the result of this operation, call ldap_result() and ldap_result2error(). See ldap_add_ext_s() for a list of possible result codes for the LDAP add operation.


Description

Please use the newer version of this function, ldap_add_ext().

Example

Code Example 17-4 adds a new entry to the directory.

Code Example 17-4  ldap_add() 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 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()

The ldap_add_ext() function adds a new entry to the directory asynchronously.


Note

ldap_add_ext() is a new version of the ldap_add() function. If you are writing a new LDAP client, use ldap_add_ext().


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 parameters listed in Table 17-44.

Table 17-44  ldap_add_ext() Function Parameters 

Parameter

Description

ld

Pointer to an LDAP structure containing information about the connection to the LDAP server.

dn

DN of the entry to add. With the exception of the leftmost component, all components of the DN (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 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 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.

Returns

One of the following values:

Description

The ldap_add_ext() adds a new entry to the directory. To add a new entry to the directory, you need to specify:

ldap_add_ext() is an asynchronous function; it does not directly return results. In order to get the results of the asynchronous operation, you need to call the ldap_result() and ldap_parse_result() functions. If you want the results to be returned directly by the function, call the synchronous function ldap_add_ext_s(). For a list of possible result codes for an LDAP add operation, see the ldap_add_ext_s() function.

For additional information on adding new entries to the directory, see "Adding an Entry" of Chapter 7, "Adding, Modifying and Deleting Entries."

Example

See Code Example 4-7 of Chapter 4, "Using the LDAP API."

See Also

ldap_add_ext_s(), ldap_result(), ldap_parse_result(), LDAPMod


ldap_add_ext_s()

The ldap_add_ext_s() function adds a new entry to the directory synchronously.


Note

ldap_add_ext_s() is a new version of the ldap_add_s() function. If you are writing a new LDAP client, use ldap_add_ext_s().


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 parameters listed in Table 17-45.

Table 17-45  ldap_add_ext_s() Function Parameters 

Parameter

Description

ld

Pointer to an LDAP structure containing information about the connection to the LDAP server.

dn

DN of the entry to add. With the exception of the leftmost component, all components of the DN (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 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 operation. If you do not want to pass any client controls, specify NULL for this argument.

Returns

One of the following values:

Description

The ldap_add_ext_s() function adds a new entry to the directory. To add a new entry to the directory, you need to specify:

ldap_add_ext_s() is a synchronous function; 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_add_ext().

For additional information on adding new entries to the directory, see "Adding an Entry" of Chapter 7, "Adding, Modifying and Deleting Entries."

Example

See Code Example 7-8 of Chapter 7, "Adding, Modifying and Deleting Entries."

See Also

ldap_add_ext(), LDAPMod


ldap_add_s()

The ldap_add_s() function adds a new entry to the directory synchronously.


Note

This is an older function that is included in the SDK 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 parameters listed in Table 17-46.

Table 17-46  ldap_add_s() Function Parameters 

Parameter

Description

ld

Pointer to an LDAP structure containing information about the connection to the LDAP server.

dn

DN of the entry to add. With the exception of the leftmost component, all components of the DN (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 ldap_add_ext_s() for a list of possible return codes.

Description

Please use the newer version of this function, ldap_add_ext_s().

Example

Code Example 17-5 adds a new entry to the directory.

Code Example 17-5  ldap_add_s Code Example 

#include <ldap.h>

...

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

The ldap_ber_free() function frees a BerElement structure from memory.


Note

This is an older function that is included in the SDK for backward-compatibility. If you are writing a new LDAP client, use ber_free() instead. Except in name, the two functions are identical.


Syntax

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

Parameters

This function has the parameters listed in Table 17-47.

Table 17-47  ldap_ber_free() Function Parameters

Parameter

Description

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

Please use the newer version of this function, ber_free().

See Also

ber_free()


ldap_bind()


Caution

This function is deprecated and should not be used. It is included in ldap-deprecated.h for backward-compatibility. Please use ldap_simple_bind().


ldap_bind() can be used when the authentication method being used needs to be selected at runtime.

Syntax

#include <ldap-deprecated.h>
ldap_bind( LDAP *ld, const char *who, const char *passwd, int method );

Parameters

This function has the parameters listed in Table 17-48.

Table 17-48  ldap_bind() Function Parameters 

Parameter

Description

ld

Pointer to an LDAP structure containing information about the connection to the LDAP server.

who

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.

method

Defines the authentication method to be used. It should be set to LDAP_AUTH_SIMPLE to select simple authentication.

Returns

ldap_bind() returns the message ID of the request it initiates.

Description

This is an asynchronous function that authenticates a specified entry to the directory. After a connection is made to an LDAP server using ldap_open(), a bind operation must be performed before other operations can be attempted over the conection.

See Also

ldap_open(), ldap_init(), ldap_bind_s()


ldap_bind_s()


Caution

This function is deprecated and should not be used. It is included in ldap-deprecated.h for backward-compatibility. Please use ldap_simple_bind_s().


ldap_bind_s() can be used when the authentication method needs to be selected at runtime.

Syntax

#include <ldap-deprecated.h>
ldap_bind_s( LDAP *ld, const char *who, const char *cred, int method );

Parameters

This function has the parameters listed in Table 17-49.

Table 17-49  ldap_bind_s() Function Parameters 

Parameter

Description

ld

Pointer to an LDAP structure containing information about the connection to the LDAP server.

who

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

cred

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

method

Defines the authentication method to be used. It should be set to LDAP_AUTH_SIMPLE to select simple authentication.

Returns

ldap_bind_s() returns an LDAP error indication.

Description

This is a synchronous function that authenticates a specified entry to the directory. After a connection is made to an LDAP server using ldap_open(), a bind operation must be performed before other operations can be attempted over the conection

See Also

ldap_open(), ldap_init() , ldap_bind()


ldap_build_filter()


Caution

This function is deprecated and should not be used. It is included in ldap-deprecated.h for backward-compatibility. Please use ldap_create_filter().


See Also

ldap_create_filter()


ldap_cache_flush()


Caution

This function is deprecated and should not be used. It is included in ldap-deprecated.h for backward-compatibility. Please use the ldap_memcache_* functions.


For more specific information, see the header file ldap-deprecated.h.

See Also

ldap_memcache_init(), ldap_memcache_set(), ldap_memcache_get(), ldap_memcache_update(), ldap_memcache_flush(), ldap_memcache_destroy()


ldap_charray_add()


Caution

This function is deprecated and should not be used. It is included in ldap-to-be-deprecated.h for backward-compatibility.


For more specific information, see the header file ldap-to-be-deprecated.h.


ldap_charray_dup()


Caution

This function is deprecated and should not be used. It is included in ldap-to-be-deprecated.h for backward-compatibility.


For more specific information, see the header file ldap-to-be-deprecated.h.


ldap_charray_free()


Caution

This function is deprecated and should not be used. It is included in ldap-to-be-deprecated.h for backward-compatibility.


For more specific information, see the header file ldap-to-be-deprecated.h.


ldap_charray_inlist()


Caution

This function is deprecated and should not be used. It is included in ldap-to-be-deprecated.h for backward-compatibility.


For more specific information, see the header file ldap-to-be-deprecated.h.


ldap_charray_merge()


Caution

This function is deprecated and should not be used. It is included in ldap-to-be-deprecated.h for backward-compatibility.


For more specific information, see the header file ldap-to-be-deprecated.h.


ldap_charray_position()


Caution

This function is deprecated and should not be used. It is included in ldap-to-be-deprecated.h for backward-compatibility.


For more specific information, see the header file ldap-to-be-deprecated.h.


ldap_compare()

The ldap_compare() function asynchronously determines if an attribute of an entry contains a specified value.


Note

This is an older function that is included in the SDK 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 parameters listed in Table 17-50.

Table 17-50  ldap_compare() Function Parameters 

Parameter

Description

ld

Pointer to an LDAP structure containing information about the connection to the LDAP server.

dn

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.


Note

To check the result of this operation, call ldap_result() and ldap_result2error(). See ldap_compare_ext_s() function for a list of possible result codes for the LDAP compare operation.


Description

Please use the newer version of this function, ldap_compare_ext().

Example

Code Example 17-6 checks to see if Barbara Jensen has the e-mail address bjensen@example.com.

Code Example 17-6  ldap_compare() Code Sample 

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

The ldap_compare_ext() function asynchronously determines if an attribute of an entry contains a specified value.


Note

ldap_compare_ext() is a new version of the ldap_compare() function. If you are writing a new LDAP client, use ldap_compare_ext().


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 parameters listed in Table 17-51.

Table 17-51  ldap_compare_ext() Function Parameters 

Parameter

Description

ld

Pointer to an LDAP structure containing information about the connection to the LDAP server.

dn

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

Returns

One of the following values:

Returns

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

Description

The ldap_compare_ext() function compares the value of an attribute in an entry against a specified value. Because 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().

For additional information on comparing attribute values in an entry, see Chapter 8, "Comparing Entries."

Example

See Code Example 8-4 of Chapter 8, "Comparing Entries."

See Also

ldap_compare_ext_s(), ldap_result(), ldap_parse_result()


ldap_compare_ext_s()

The ldap_compare_ext_s() function 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 parameters listed in Table 17-52.

Table 17-52  ldap_compare_ext_s() Function Parameters 

Parameter

Description

ld

Pointer to an LDAP structure containing information about the connection to the LDAP server.

dn

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 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 operation. If you do not want to pass any client controls, specify NULL for this argument.

Returns

One of the following values:

Description

The ldap_compare_ext_s() function compares the value of an attribute in an entry against a specified value. 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().

For additional information on comparing attribute values in an entry, see Chapter 8, "Comparing Entries."

Example

See Code Example 8-2 of Chapter 8, "Comparing Entries."

See Also

ldap_compare_ext()


ldap_compare_s()

The ldap_compare_s() function synchronously determines if an attribute of an entry contains a specified value.


Note

This is an older function that is included in the SDK 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 parameters listed in Table 17-53.

Table 17-53  ldap_compare_s() Function Parameters 

Parameter

Description

ld

Pointer to an LDAP structure containing information about the connection to the LDAP server.

dn

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

Description

Please use the newer version of this function, ldap_compare_ext_s().

Example

Code Example 17-7 checks to see if Barbara Jensen has the e-mail address bjensen@example.com.

Code Example 17-7  ldap_compare_s() Code Sample 

#include <stdio.h>

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

The ldap_control_free() function frees an LDAPControl structure from memory.

Syntax

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

Parameters

This function has the parameter listed in Table 17-54.

Table 17-54  ldap_control_free() Function Parameter 

Parameter

Description

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

The ldap_controls_free() function frees an array of LDAPControl structures from memory.

Syntax

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

Parameters

This function has the parameter listed in Table 17-55.

Table 17-55  ldap_controls_free() Function Parameter 

Parameter

Description

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


ldap_count_entries()

The ldap_count_entries() function 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 parameters listed in Table 17-56.

Table 17-56  ldap_count_entries() Function Parameters 

Parameter

Description

ld

Pointer to an LDAP structure containing information about the connection to the LDAP server.

result

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

Returns

One of the following values:

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

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 "Getting Search Results" of Chapter 5, "Searching a LDAP Directory."

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_entry(), ldap_next_message()


ldap_count_messages()

The ldap_count_messages() function 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 parameters listed in Table 17-57.

Table 17-57  ldap_count_messages() Function Parameters 

Parameter

Description

ld

Pointer to an LDAP structure containing information about the connection to the LDAP server.

result

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

Returns

One of the following values:

Description

The ldap_count_messages() function returns the number of LDAPMessage structures in a chain of search results. The count is the number of search entries plus the number of search references.


Note

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 "Getting Search Results" of Chapter 5, "Searching a LDAP Directory."

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_first_entry(), ldap_next_entry(), ldap_first_reference(), ldap_next_reference()


ldap_count_references()

The ldap_count_references() function 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 parameters listed in Table 17-58.

Table 17-58  ldap_count_references() Function Parameters 

Parameter

Description

ld

Pointer to an LDAP structure containing information about the connection to the LDAP server.

result

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

Returns

One of the following values:

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

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 "Getting Search Results" of Chapter 5, "Searching a LDAP Directory."

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.


Note

Use the ldap_count_values_len() function if the array contains berval structures.


Syntax

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

Parameters

This function has the parameter listed in Table 17-59.

Table 17-59  ldap_count_values() Function Parameter 

Parameter

Description

values

Array of values.

Returns

One of the following values:

See Chapter 18, "Result Codes" for a complete listing.

Description

For additional information, see "Getting the Values of an Attribute" of Chapter 5, "Searching a LDAP Directory."

Example

Code Example 17-8 counts the number of values assigned to an attribute.

Code Example 17-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.


Note

Use the ldap_count_values() function if the array contains strings.


Syntax

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

Parameters

This function has the parameter listed in Table 17-60.

Table 17-60  ldap_count_values_len() Function Parameter

Parameter

Description

values

Array of berval structures.

Returns

One of the following values:

See Chapter 18, "Result Codes" for a complete listing.

Description

For additional information, see "Getting the Values of an Attribute" of Chapter 5, "Searching a LDAP Directory."

Example

Code Example 17-9 counts the number of values assigned to an attribute.

Code Example 17-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.

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 parameters listed in Table 17-61.

Table 17-61  ldap_create_filter() Function Parameters 

Parameter

Description

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:

Description

For more information about filters, see "Creating Filters Programmatically" of Chapter 6, "Using Filter Configuration Files."

Example

Code Example 17-10 builds the filter (mail=bjensen@example.com).

Code Example 17-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()

The ldap_create_persistentsearch_control() function creates a control that allows your client to perform a search of an LDAP v3 server that continues without termination until your client abandons it.


Note

Persistent search is an optional feature; it may not be supported on all LDAP servers. In order for the control to work, the 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 Supported Controls" of Chapter 13, "Working with LDAP Controls"for information on determining the controls supported by a server.


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 parameters listed in Table 17-62.

Table 17-62  ldap_create_persistentsearch_control() Function Parameters 

Parameter

Description

ld

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:

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

You can OR the values together to specify multiple types.

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 controls are included with each entry returned to your client:

  • If non-zero, a control is included with each entry.
  • If 0, controls are not included with the entries returned from the server.

ctl_iscritical

Specifies whether the control is critical to the operation.

  • If non-zero, the control is critical to the operation. If the server does not support it, the server will return an LDAP_UNAVAILABLE_CRITICAL_EXTENSION error.
  • If 0, the control is not critical to the operation. Even if the server does not support the control, the operation is still attempted and the control is ignored.

ctrlp

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

Returns

One of the following values:

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 ldap_create_persistentsearch_control() creates an LDAP server control that you can pass to the ldap_search_ext() function.

As stated, after you create the control, you can pass it to the LDAP server during a search operation. 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 parameter), the server includes controls with each changed entry it sends back. To retrieve the controls 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_geteffectiveRights_control()

The ldap_create_geteffectiveRights_control() function allows a user (with correct privileges) to query about the access rights another identity has on one or more entries in the directory.

Syntax

#include <ldap-extension.h>
int ldap_create_geteffectiveRights_control( LDAP *ld, char *authzid,
  char *attrlist, char ctl_iscritical, LDAPControl **ctrlp);

Parameters

This function has the parameters listed in Table 17-63.

Table 17-63  ldap_create_geteffectiveRights_control() Function Parameters 

Parameter

Description

ld

Pointer to an LDAP structure containing information about the connection to the LDAP server.

authzid

The DN of the identity for which you are checking access rights.

attrlist

A comma-separated list of access rights to determine.

ctl_iscritical

Specifies whether the control is critical to the operation.

  • If non-zero, the control is critical to the operation. If the server does not support it, the server will return an LDAP_UNAVAILABLE_CRITICAL_EXTENSION error.
  • If 0, the control is not critical to the operation. Even if the server does not support the control, the operation is still attempted and the control is ignored.

ctrlp

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

Description

Typically, this control is used in an LDAP search request where the base, the scope, the filter and the attributes will determine the entries to return the access rights.


Note

This control is specific to Sun Java System Directory Server 5.2 and later.



ldap_create_proxiedauth_control()

The ldap_create_proxiedauth_control() function creates an LDAPv3 control that allows a bound entity to assume the identity of another directory entry.


Note

ldap_create_proxiedauth_control() is a new version of the ldap_create_proxyauth_control() function. If you are writing a new LDAP client, use ldap_create_proxiedauth_control().


Syntax

#include <ldap.h>
int ldap_create_proxiedauth_control( LDAP *ld, char *authzid,
  LDAPControl **ctrlp);

Parameters

This function has the parameters listed in Table 17-64.

Table 17-64  ldap_create_proxiedauth_control() Function Parameters

Parameter

Description

ld

Pointer to an LDAP structure containing information about the connection to the LDAP server.

authzid

The string representing the identity to assume for the access rights, defined in the format specified by the following Augmented Backus-Naur Form (ABNF) (copied from RFC 2829):

; Specific predefined authorization (authz) id schemes are
   ; defined below -- new schemes may be defined in the future.

authzId = dnAuthzId / uAuthzId

   ; distinguished-name-based authz id.
   dnAuthzId = "dn:" dn
   dn = utf8string ; with syntax defined in RFC 2253

   ; unspecified userid, UTF-8 encoded.
   uAuthzId = "u:" userid
   userid = utf8string ; syntax unspecified

ctrlp

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

Description

More information on proxy authorization can be found in the LDAP Proxied Authorization Control Internet Draft (http://ietfreport.isoc.org/ids/draft-weltman-ldapv3-proxy-12.txt).


Note

Proxy authorization is an optional feature; it may not be supported on all LDAP servers. In order for the control to work, the server that you are connecting to must support the server control for proxy authorization (OID 2.16.840.1.113730.3.4.18, or LDAP_CONTROL_PROXIEDAUTH, as defined in the ldap-extension.h header file). See "Determining Supported Controls" of Chapter 13, "Working with LDAP Controls"for information on determining the controls supported by a server.



ldap_create_proxyauth_control()

The ldap_create_proxyauth_control() function creates an LDAPv3 control that allows a bound entity to assume the identity of another directory entry.


Note

This is an older function that is included in the SDK for backward-compatibility. If you are writing a new LDAP client, use ldap_create_proxiedauth_control().


Syntax

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

Parameters

This function has the parameters listed in Table 17-65.

Table 17-65  ldap_create_proxyauth_control() Function Parameters

Parameter

Description

ld

Pointer to an LDAP structure containing information about the connection to the LDAP server.

DN

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

ctl_iscritical

Specifies whether the control is critical to the operation.

  • If non-zero, the control is critical to the operation. If the server does not support it, the server will return an LDAP_UNAVAILABLE_CRITICAL_EXTENSION error.
  • If 0, the control is not critical to the operation. Even if the server does not support the control, the operation is still attempted and the control is ignored.

ctrlp

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

Returns

One of the following values:

See Also

ldap_control_free()


ldap_create_sort_control()

The ldap_create_sort_control() function creates a control that specifies the order in which you want search results returned.


Note

This function implements an extension to the LDAPv3. Server-side sorting is an optional feature; it may not be supported on all LDAP servers. Call this function when interacting with LDAP servers that support this LDAPv3 extension. See "Determining Supported Extended Operations" of Chapter 15, "Extended Operations" to determine if the server supports extended operations.


Syntax

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

Parameters

This function has the parameters listed in Table 17-66.

Table 17-66  ldap_create_sort_control() Function Parameters 

Parameter

Description

ld

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 the control is critical to the operation.

  • If non-zero, the control is critical to the operation. If the server does not support it, the server will return an LDAP_UNAVAILABLE_CRITICAL_EXTENSION error.
  • If 0, the control is not critical to the operation. Even if the server does not support the control, the operation is still attempted and the control is ignored.

ctrlp

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

Returns

One of the following values:

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.


Note

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 the ldap.h header file). See "Determining Supported Controls" of Chapter 13, "Working with LDAP Controls"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() and ldap_free_sort_keylist() functions.

For more information, see "Creating the Control" of Chapter 13, "Working with LDAP Controls."

See Also

ldap_create_sort_keylist(), ldap_search_ext(), ldap_search_ext_s(), ldap_control_free()


ldap_create_sort_keylist()

The ldap_create_sort_keylist() function 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 parameters listed in Table 17-67.

Table 17-67  ldap_create_sort_keylist() Function Parameters 

Parameter

Description

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. The value 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:

1.  cn (sorts by the cn attribute)

2.  -cn (sorts by the cn attribute in reverse order)

3.  -cn:1.2.3.4 (sorts by the cn attribute in reverse order using the matching rule identified by the OID 1.2.3.4)

Returns

One of the following values:

Description

Calling 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. You can then pass the array 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 and how the sort will work. When you are done sorting the results, you should free the array of LDAPsortkey structures by calling the ldap_free_sort_keylist() function.

For more information, see "Specifying the Sort Order" of Chapter 13, "Working with LDAP Controls."

See Also

ldap_create_sort_control(), ldap_free_sort_keylist()


ldap_create_virtuallist_control()

The ldap_create_virtuallist_control() function creates a control that requests a subset of search results for use in a virtual list box.


Note

ldap_create_virtuallist_control() implements an extension to the LDAPv3 supported by Sun Java System Directory Server. For information on determining if another server supports this control, see "Determining Supported Controls" of Chapter 13, "Working with LDAP Controls."


Syntax

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

Parameters

This function has the parameters listed in Table 17-68.

Table 17-68  ldap_create_virtuallist_control() Function Parameters 

Parameter

Description

ld

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 an LDAPControl structure created by this function. When you are done using this control, you should free it by calling ldap_control_free().

Returns

One of the following values:

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


Note

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 2.16.840.1.113730.3.4.9, or LDAP_CONTROL_VLVREQUEST, as defined in the ldap.h header file). See "Determining Supported Controls" of Chapter 13, "Working with LDAP Controls" for information on determining the controls supported by a server.


Calling ldap_create_virtuallist_control() creates an LDAP control that you can pass to the ldap_search_ext() and ldap_search_ext_s() functions. You also need to pass a server-side sorting control to the search functions. You can call ldap_create_sort_keylist() and ldap_create_sort_control() to create a server-side sorting control. 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" of Chapter 13, "Working with LDAP Controls."

See Also

LDAPVirtualList, ldap_parse_virtuallist_control(), ldap_search_ext(), ldap_search_ext_s(), ldap_control_free()


ldap_delete()

The ldap_delete() function removes an entry from the directory asynchronously.


Note

This is an older function that is included in the SDK 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 parameters listed in Table 17-69.

Table 17-69  ldap_delete() FunctionParameters 

Parameter

Description

ld

Pointer to an LDAP structure containing information about the connection to the LDAP server.

dn

DN of the entry to remove.

Returns

Returns the message ID of the ldap_delete() operation.


Note

To check the result of this operation, call ldap_result() and ldap_result2error(). See ldap_delete_ext_s() for a list of possible result codes for the LDAP delete operation.


Description

Please use the newer version of this function, ldap_delete_ext().

Example

Code Example 17-11 uses the asynchronous ldap_delete() function to remove the entry for Barbara Jensen from the directory.

Code Example 17-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,dc=example, dc=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()

The ldap_delete_ext() function deletes an entry from the directory asynchronously.


Note

ldap_delete_ext() is a new version of the ldap_delete() function. If you are writing a new LDAP client, you should call ldap_delete_ext().


Syntax

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

Parameters

This function has the parameters listed in Table 17-70.

Table 17-70  ldap_delete_ext() Function Parameters 

Parameter

Description

ld

Pointer to an LDAP structure containing information about the connection to the LDAP server.

dn

DN of the entry to remove.

serverctrls

Pointer to an array of LDAPControl structures representing LDAP server controls that apply to this 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 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.

Returns

One of the following values:

Description

The ldap_delete_ext() function deletes an entry from the directory, using the dn argument to specify the entry that you want to 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().

For additional information on deleting entries from the directory, see Chapter 7, "Adding, Modifying and Deleting Entries."

Example

See Code Example 4-2 of Chapter 4, "Using the LDAP API" and Code Example 7-21 of Chapter 7, "Adding, Modifying and Deleting Entries."

See Also

ldap_delete_ext_s(), ldap_result(), ldap_parse_result()


ldap_delete_ext_s()

The ldap_delete_ext_s() function deletes an entry from the directory synchronously.


Note

ldap_delete_ext_s() is a new version of the ldap_delete_s() function. If you are writing a new LDAP client, you should call ldap_delete_ext_s().


Syntax

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

Parameters

This function has the parameters listed in Table 17-71.

Table 17-71  ldap_delete_ext_s() Function Parameters 

Parameter

Description

ld

Pointer to an LDAP structure containing information about the connection to the LDAP server.

dn

DN of the entry to remove.

serverctrls

Pointer to an array of LDAPControl structures representing LDAP server controls that apply to this 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 operation. If you do not want to pass any client controls, specify NULL for this argument.

Returns

One of the following values:

Returns

One of the following values:

Description

The ldap_delete_ext_s() function deletes an entry from the directory, using the dn argument to specify the entry that you want to delete. 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 additional information on deleting entries from the directory, see Chapter 7, "Adding, Modifying and Deleting Entries."

Example

See Code Example 4-1 of Chapter 4, "Using the LDAP API" and Code Example 7-19 in Chapter 7, "Adding, Modifying and Deleting Entries."

See Also

ldap_delete_ext()


ldap_delete_s()

The ldap_delete_s() deletes an entry from the directory synchronously.


Note

This is an older function that is included in the SDK 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 parameters listed in Table 17-72.

Table 17-72  ldap_delete_s() Function Parameters

Parameters

Description

ld

Pointer to an LDAP structure containing information about the connection to the LDAP server.

dn

DN of the entry to remove.

Returns

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

Description

Please use the newer version of this function, ldap_delete_ext_s().

Example

Code Example 17-12 uses the synchronous ldap_delete_s() function to delete the entry for Barbara Jensen from the directory.

Code Example 17-12  ldap_delete_s() Code Example 

#include <ldap.h>

LDAP *ld;

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

char *dn = "uid=bjensen,ou=People,dc=example, dc=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 DN into a more user-friendly form by stripping off the cryptic type names.

Syntax

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

Parameters

This function has the parameter listed in Table 17-73.

Table 17-73  ldap_dn2ufn() Function Parameter

Parameter

Description

dn

The DN that you want converted.

Returns

One of the following values:

Description

For more information on ldap_dn2ufn(), see the man page. For more information on user friendly naming (UFN), see RFC 1781, Using the OSI Directory to Achieve User Friendly Naming (http://www.faqs.org/rfcs/rfc1781.html).


ldap_entry2html()

The ldap_entry2html() function writes the HTML representation of an LDAP entry.

Syntax

#include <disptmpl.h>
int ldap_entry2html( LDAP *ld, char *buf, LDAPMessage *entry,
  struct ldap_disptmpl *tmpl, char **defattrs, char ***defvals,
  writeptype writeproc, void *writeparm, char *eol, int rdncount,
  unsigned long opts, char *urlprefix, char *base );

Parameters

This function has the parameters listed in Table 17-74.

Table 17-74  ldap_entry2html() Function Parameters 

Parameter

Description

ld

Pointer to an LDAP structure containing information about the connection to the LDAP server.

buf

A pointer to a buffer of size LDAP_DTMPL_BUFSIZ or larger. If NULL, a buffer is allocated and freed internally.

entry

Specifies the attribute values to be represented.

tmpl

Pointer to the display template to be used, usually obtained by calling ldap_oc2template().

defattrs

A NULL-terminated array of LDAP attribute names for which you wish to provide default values. It is only used if the entry contains no values for the attribute.

defvals

An array of NULL-terminated arrays of default values corresponding to the attributes.

writeproc

writeproc function should be declared as:

int writeproc( writeparm, p, len )

void *writeparm;

char *p;

int len;

where p is a pointer to text to be written and len is the length of the text. p is guaranteed to be zero-terminated.

writeparm

A pointer to a structure that will be passed as the first parameter of the writeproc procedure. Typically, this is used to pass the file descriptor of the file to write to.

eol

Lines of text are terminated with this string.

rdncount

Limits the number of components that are displayed for DN attributes.

opts

Specifies output options. The allowed values are:

  • zero (default output)
  • LDAP_DISP_OPT_AUTOLABELWIDTH which causes the width for labels to be determined based on the longest label in tmpl.
  • LDAP_DISP_OPT_HTMLBODYONLY which instructs the library not to include <HTML>, <HEAD>, <TITLE>, and <BODY> tags. In other words, an HTML fragment is generated, and the caller is responsible for prepending and appending the appropriate HTML tags to construct a correct HTML document.

urlprefix

Starting text to use when constructing an LDAP URL. The default is the string ldap://.

base

The base with which to begin when executing search actions. If NULL, search action template items are ignored.

Returns
Description

ldap_entry2html() produces an HTML representation of an entry. It behaves exactly like ldap_entry2text() except for the output and the addition of two parameters.

See Also

ldap_entry2text(), ldap_oc2template()


ldap_entry2html_search()

The ldap_entry2html_search() function determines the appropriate display template to use by calling ldap_oc2template().

Syntax

#include <disptmpl.h>
int ldap_entry2html_search( LDAP *ld, char *dn, char *base,
  LDAPMessage *entry, struct ldap_disptmpl *tmpllist, char **defattrs,
  char ***defvals, writeptype writeproc, void *writeparm, char *eol,
  int rdncount, unsigned long opts, char *urlprefix );

Parameters

This function has the parameters listed in Table 17-75.

Table 17-75  ldap_entry2html_search() Function Parameters 

Parameter

Description

ld

Pointer to an LDAP structure containing information about the connection to the LDAP server.

dn

DN of the entry to write as HTML.

base

The base with which to begin when executing search actions. If NULL, search action template items are ignored.

entry

Specifies the attribute values to be represented.

tmpllist

Pointer to the entire list of templates available (usually obtained by calling ldap_init_templates() or ldap_init_templates_buf()). If NULL, will attempt to read a load templates from the default template configuration file.

defattrs

A NULL-terminated array of LDAP attribute names for which you wish to provide default values. It is only used if the entry contains no values for the attribute.

defvals

An array of NULL-terminated arrays of default values corresponding to the attributes.

writeproc

writeproc function should be declared as:

int writeproc( writeparm, p, len )

void *writeparm;

char *p;

int len;

where p is a pointer to text to be written and len is the length of the text. p is guaranteed to be zero-terminated.

writeparm

A pointer to a structure that will be passed as the first parameter of the writeproc procedure. Typically, this is used to pass the file descriptor of the file to write to.

eol

Lines of text are terminated with this string.

rdncount

Limits the number of components that are displayed for DN attributes.

opts

Specifies output options. The allowed values are:

  • zero (default output)
  • LDAP_DISP_OPT_AUTOLABELWIDTH which causes the width for labels to be determined based on the longest label in tmpl.
  • LDAP_DISP_OPT_HTMLBODYONLY which instructs the library not to include <HTML>, <HEAD>, <TITLE>, and <BODY> tags. In other words, an HTML fragment is generated, and the caller is responsible for prepending and appending the appropriate HTML tags to construct a correct HTML document.

urlprefix

Starting text to use when constructing an LDAP URL. The default is the string ldap://

Returns
Description

ldap_entry2html_search() will call ldap_search_s() to retrieve any attribute values to be displayed. It behaves exactly like ldap_entry2text_search(), except the urlprefix parameter is required and HTML is the output.

See Also

ldap_search_s(), ldap_entry2text_search(), ldap_init_templates(), ldap_init_templates_buf(), ldap_entry2text()


ldap_entry2text()

The ldap_entry2text() function writes the text representation of an LDAP entry.

Syntax

#include <disptmpl.h>
int ldap_entry2text( LDAP *ld, char *buf, LDAPMessage *entry,
  struct ldap_disptmpl *tmpl, char **defattrs, char ***defvals,
  writeptype writeproc, void *writeparm, char *eol, int rdncount,
  unsigned long opts );

Parameters

This function has the parameters listed in Table 17-76.

Table 17-76  ldap_entry2text() Function Parameters 

Parameter

Description

ld

Pointer to an LDAP structure containing information about the connection to the LDAP server.

buf

A pointer to a buffer of size LDAP_DTMPL_BUFSIZ or larger. If NULL, a buffer is allocated and freed internally.

entry

Specifies the attribute values to be represented.

tmpl

Pointer to the display template to be used, usually obtained by calling ldap_oc2template().

defattrs

A NULL-terminated array of LDAP attribute names for which you wish to provide default values. It is only used if the entry contains no values for the attribute.

defvals

An array of NULL-terminated arrays of default values corresponding to the attributes.

writeproc

writeproc function should be declared as:

int writeproc( writeparm, p, len )

void *writeparm;

char *p;

int len;

where p is a pointer to text to be written and len is the length of the text. p is guaranteed to be zero-terminated.

writeparm

A pointer to a structure that will be passed as the first parameter of the writeproc procedure. Typically, this is used to pass the file descriptor of the file to write to.

eol

Lines of text are terminated with this string.

rdncount

Limits the number of components that are displayed for DN attributes.

opts

Specifies output options. The allowed values are:

  • zero (default output)
  • LDAP_DISP_OPT_AUTOLABELWIDTH which causes the width for labels to be determined based on the longest label in tmpl.
  • LDAP_DISP_OPT_HTMLBODYONLY which instructs the library not to include <HTML>, <HEAD>, <TITLE>, and <BODY> tags. In other words, an HTML fragment is generated, and the caller is responsible for prepending and appending the appropriate HTML tags to construct a correct HTML document.

Returns
Description

ldap_entry2text() produces a text representation of an entry and writes the text by calling the writeproc function. All of the attribute values to be displayed must be present in entry as no interaction with the LDAP server will be performed.

See Also

ldap_entry2html(), ldap_oc2template()


ldap_entry2text_search()

The ldap_entry2text_search() function determines the appropriate display template to use by calling ldap_oc2template().

Syntax

#include <disptmpl.h>
int ldap_entry2text_search( LDAP *ld, char *dn, char *base,
  LDAPMessage *entry, struct ldap_disptmpl *tmpllist, char **defattrs,
  char ***defvals, writeptype writeproc, void *writeparm,
  char *eol, int rdncount, unsigned long opts );

Parameters

This function has the parameters listed in Table 17-77.

Table 17-77  ldap_entry2text_search() Function Parameters 

Parameter

Description

ld

Pointer to an LDAP structure containing information about the connection to the LDAP server.

dn

DN of the entry to write.

base

If NULL, the search action template items are ignored. If not NULL, it is the search base to use when executing search actions.

entry

If entry is not NULL, it should contain the objectClass attribute values for the entry to be displayed. If NULL, dn can not be NULL, and ldap_entry2text_search() will retrieve the objectClass values itself by calling ldap_search_s().

tmpllist

Pointer to the entire list of templates available (usually obtained by calling ldap_init_templates() or ldap_init_templates_buf()). If NULL, will attempt to read a load templates from the default template configuration file.

defattrs

A NULL-terminated array of LDAP attribute names for which you wish to provide default values. It is only used if the entry contains no values for the attribute.

defvals

An array of NULL-terminated arrays of default values corresponding to the attributes.

writeproc

writeproc function should be declared as:

int writeproc( writeparm, p, len )

void *writeparm;

char *p;

int len;

where p is a pointer to text to be written and len is the length of the text. p is guaranteed to be zero-terminated.

writeparm

A pointer to a structure that will be passed as the first parameter of the writeproc procedure. Typically, this is used to pass the file descriptor of the file to write to.

eol

Lines of text are terminated with this string.

rdncount

Limits the number of components that are displayed for DN attributes.

opts

Specifies output options. The allowed values are:

  • zero (default output)
  • LDAP_DISP_OPT_AUTOLABELWIDTH which causes the width for labels to be determined based on the longest label in tmpl.
  • LDAP_DISP_OPT_HTMLBODYONLY which instructs the library not to include <HTML>, <HEAD>, <TITLE>, and <BODY> tags. In other words, an HTML fragment is generated, and the caller is responsible for prepending and appending the appropriate HTML tags to construct a correct HTML document.

Returns
Description

ldap_entry2text_search() will call ldap_search_s() to retrieve any attribute values to be displayed.

See Also

ldap_entry2html_search(), ldap_oc2template(), ldap_search_s(), ldap_init_templates(), ldap_init_templates_buf()


ldap_err2string()

The ldap_err2string() function returns the corresponding error message for an error code.

Syntax

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

Parameters

This function has the parameter listed in Table 17-78.

Table 17-78  ldap_err2string() Function Parameter

Parameter

Description

err

Error code that you want interpreted into an error message.

Returns

One of the following values:

Description

For more information, see "Getting the Error Message from an Error Code" of Chapter 4, "Using the LDAP API."

Example

Code Example 17-13 sets the variable err_msg to the error message corresponding to the error code returned by the ldap_simple_bind_s() function.

Code Example 17-13  ldap_err2string() Code Example

#include <ldap.h>

...

LDAP *ld;

char *dn = "uid=bjensen,ou=People,dc=example, dc=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 DN into its component parts.

Syntax

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

Parameters

This function has the parameters listed in Table 17-79.

Table 17-79  ldap_explode_dn() Function Parameters 

Parameter

Description

dn

DN that you want separated into components.

notypes

Specifies whether or not type names in the DN 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:

Description

For more information, see "Getting the Components of a Distinguished Name" of Chapter 5, "Searching a LDAP Directory."

Example

The following function call:

ldap_explode_dn( "uid=bjensen,ou=People,dc=example,dc=com", 0 )

returns this array:

{ "uid=bjensen", "ou=People", "dc=example,dc=com", NULL }

If you change the notypes parameter from 0 to 1:

ldap_explode_dn( "uid=bjensen,ou=People,dc=example,dc=com", 1 )

The component names are not returned in the array:

{ "bjensen", "People", "example.com", NULL }

See Also

ldap_explode_rdn(), ldap_get_dn()


ldap_explode_dns()


Caution

This function is to be deprecated and should not be used. It is included in ldap-to-be-deprecated.h for backward-compatibility.


The ldap_explode_dns() function takes a DNS-style DN, breaks it up into its component parts, and returns a NULL-terminated array. For example, the DN cal.sun.com will return { "cal", "sun", "com", NULL }. The result can be freed by calling ldap_value_free().

Syntax

#include <ldap-to-be-deprecated.h>
char ** ldap_explode_dns( const char *dn );

Parameters

This function has the parameter listed in Table 17-80.

Table 17-80  ldap_explode_dns() Function Parameter 

Parameter

Description

dn

DN that you want separated into components.

Returns

One of the following values:

Description

For more information, see "Getting the Components of a Distinguished Name" of Chapter 5, "Searching a LDAP Directory."


ldap_explode_rdn()

The ldap_explode_rdn() function converts a relative distinguished name (RDN) into its component parts.

Syntax

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

Parameters

This function has the parameters listed in Table 17-81.

Table 17-81  ldap_explode_rdn() Function Parameters 

Parameter

Description

dn

RDN that you want separated into components.

notypes

Specifies whether or not type names in the RDN 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:

Description

For more information, see "Getting the Components of a Distinguished Name" of Chapter 5, "Searching a LDAP Directory."

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

The ldap_extended_operation() function 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 parameters listed in Table 17-82.

Table 17-82  ldap_extended_operation() Function Parameters 

Parameter

Description

ld

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. (After processing an LDAPv3 extended operation, an LDAP server can return an OID and data in the result. To parse the OID and data from the result, call the ldap_parse_extended_result() function.)

requestdata

Pointer to a berval structure containing the data that you want passed to the server to perform the extended operation. The data in the berval is a buffer of the BER encoded datatype, usually optained using the ber_flatten() function.

serverctrls

Pointer to an array of LDAPControl structures representing LDAP server controls that apply to this 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 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.

Returns

One of the following values:

Description

The ldap_extended_operation() function sends a request to the server to perform an LDAPv3 extended operation. 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().

For additional information on asynchronous extended operations, see "Asynchronous Extended Operation" of Chapter 15, "Extended Operations." For a list of possible result codes for an LDAP extended operation, see ldap_extended_operation_s().

See Also

ldap_extended_operation_s(), ldap_result(), ldap_parse_extended_result(), ldap_get_lderrno(), ber_flatten()


ldap_extended_operation_s()

The ldap_extended_operation_s() function 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 parameters listed in Table 17-83.

Table 17-83  ldap_extended_operation_s() Function Parameters 

Parameter

Description

ld

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. The data in the berval is a buffer of the BER encoded datatype, usually optained using the ber_flatten() function.

serverctrls

Pointer to an array of LDAPControl structures representing LDAP server controls that apply to this 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 operation. If you do not want to pass any client controls, specify NULL for this argument.

retoidp

Pointer to the 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 for 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:

Description

The ldap_extended_operation_s() function sends a request to the server to perform an LDAPv3 extended operation.


Note

The LDAP server must support the extended operation. Sun Java System Directory Server supports a server plug-in interface that you can use to add support for extended operations. For details, see the Sun ONE Directory Server Plug-In Programming Guide.


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

For information on determining the extended operations supported by a server, see "Determining Supported Extended Operations" of Chapter 15, "Extended Operations."

See Also

ldap_extended_operation(), ber_flatten()


ldap_first_attribute()

The ldap_first_attribute() function returns the name of the first attribute in an entry returned by the ldap_first_entry(), the ldap_next_entry(), or the ldap_result() functions.

Syntax

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

Parameters

This function has the parameters listed in Table 17-84.

Table 17-84  ldap_first_attribute() Function Parameters

Parameter

Description

ld

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

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:

See Chapter 18, "Result Codes" for a complete listing of error codes.

Description

For more information, see "Getting Attribute Names from an Entry" of Chapter 5, "Searching a LDAP Directory."

Example

Code Example 17-14 retrieves each attribute for an entry.

Code Example 17-14  ldap_first_attribute() Code Example 

#include <stdio.h>

#include <ldap.h>

...

LDAP *ld;

LDAPMessage *result, *e;

BerElement *ber;

char *a;

char *my_searchbase = "dc=example,dc=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(), BerElement


ldap_first_disptmpl()

The ldap_first_disptmpl() function returns the first template in a list.

Syntax

#include <disptmpl.h>
ldap_first_disptmpl( struct ldap_disptmpl *tmpllist );

Parameters

This function has the parameter listed in Table 17-85.

Table 17-85  ldap_first_disptmpl() Function Parameter

Parameter

Description

tmpllistp

Pointer to a list of template data structures.

Description

ldap_first_disptmpl() returns the first template in the list of templates pointed to by the parameter tmpllistp. tmpllistp is typically obtained by calling ldap_init_templates().

See Also

ldap_next_disptmpl(), ldap_init_templates(), ldap_init_templates_buf()


ldap_first_entry()

The ldap_first_entry() function 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 parameters listed in Table 17-86.

Table 17-86  ldap_first_entry() Function Parameters

Parameter

Description

ld

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:

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.


Caution

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 Chapter 5, "Searching a LDAP Directory."

See Also

ldap_result(), ldap_search_ext(), ldap_search_ext_s(), ldap_next_entry()


ldap_first_message()

The ldap_first_message() function 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 parameters listed in Table 17-87.

Table 17-87  ldap_first_message() Function Parameters

Parameter

Description

ld

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:

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


Caution

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 Chapter 5, "Searching a LDAP Directory."

Example

See Code Example 5-4 and Code Example 5-7 in Chapter 5, "Searching a LDAP Directory."

See Also

ldap_result(), ldap_search_ext(), ldap_search_ext_s(), ldap_next_message(), ldap_first_entry(), ldap_first_reference()


ldap_first_reference()

The ldap_first_reference() function 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 parameters listed in Table 17-88.

Table 17-88  ldap_first_reference() Function Parameters

Parameter

Description

ld

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:

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.


Caution

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 Chapter 5, "Searching a LDAP Directory."

See Also

ldap_result(), ldap_search_ext(), ldap_search_ext_s(), ldap_next_reference(), ldap_first_message()


ldap_first_searchobj()

The ldap_first_searchobj() function returns the first search preference configuration from a data structure defined in the list solist.

Syntax

#include <ldap.h>
ldap_searchobj * ldap_first_searchobj( struct ldap_searchobj *solist );

Parameters

This function has the parameter listed in Table 17-89.

Table 17-89  ldap_first_searchobj() Function Parameter

Parameter

Description

solist

Pointer to the search preference data structures, typically obtained by calling ldap_init_searchprefs().

Description

ldap_first_searchobj provides access to LDAP search preference configuration data. LDAP search preference configurations are typically used by LDAP client programs to specify which attributes a user may search by, the labels for the attributes, and the LDAP filters and scopes associated with those searches.

See Also

ldap_init_searchprefs(), ldap_init_searchprefs_buf()


ldap_first_tmplcol()

The ldap_first_tmplcol() function returns a pointer to the first item within a template.

Syntax

#include <disptmpl.h>
struct ldap_tmplitem * ldap_first_tmplcol( struct ldap_disptmpl *tmpl,
  struct ldap_tmplitem *row );

Parameters

This function has the parameters listed in Table 17-90.

Table 17-90  ldap_first_tmplcol() Function Parameters 

Parameter

Description

tmpl

The name of the template to be retrieved.

row

The row in which the item is to be retrieved from.

Returns
Description

ldap_first_tmplcol() returns a pointer to the first item (in the first column) of the row, defined by row, within the template defined by tmpl.

See Also

ldap_first_tmplrow(), ldap_next_tmplcol()


ldap_first_tmplrow()

The ldap_first_tmplrow() function returns a pointer to the first row of items in a template.

Syntax

#include <disptmpl.h>
struct ldap_tmplitem * ldap_first_tmplrow( struct ldap_disptmpl *tmpl );

Parameters

This function has the parameter listed in Table 17-91.

Table 17-91  ldap_first_tmplrow() Function Parameter 

Parameter

Description

tmpl

The name of the template to be retrieved.

Returns
See Also

ldap_next_tmplrow(), ldap_first_tmplcol()


ldap_free_friendlymap()

The ldap_free_friendlymap() function frees the FriendlyMap structures allocated by the ldap_friendly_name() function when no more calls to it are to be made.

Syntax

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

Parameters

This function has the parameter listed in Table 17-92.

Table 17-92  ldap_free_friendlymap() Function Parameter

Parameter

Description

map

Pointer to the FriendlyMap mapping structure in memory.

Example

Code Example 17-15 frees memory allocated by the ldap_friendly_name() function.

Code Example 17-15  ldap_free_friendlymap() Code Example 

#include <ldap.h>

#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 file is in memory, 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 );

...

ldap_free_friendlymap( map );

...

See Also

ldap_friendly_name(), FriendlyMap


ldap_free_searchprefs()

The ldap_free_searchprefs() function disposes of the data structures allocated by ldap_init_searchprefs().

Syntax

#include <ldap.h>
void ldap_free_searchprefs( struct ldap_searchobj *solist );

Parameters

This function has the parameter listed in Table 17-93.

Table 17-93  ldap_free_searchprefs() Function Parameter

Parameter

Description

solist

Pointer to the data structures, typically obtained by calling ldap_init_searchprefs().

See Also

ldap_init_searchprefs(), ldap_init_searchprefs_buf()


ldap_free_sort_keylist()

The ldap_free_sort_keylist() function 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 parameter listed in Table 17-94.

Table 17-94  ldap_free_sort_keylist() Function Parameter

Parameter

Description

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 done sorting results, call this function to free the memory that you have allocated. This function must be called after the ldap_create_sort_control() function has completed.

See Also

ldap_create_sort_keylist(), ldap_create_sort_control()


ldap_free_templates()

The ldap_free_templates() function disposes of the templates allocated by ldap_init_templates().

Syntax

#include <disptmpl.h>
void ldap_free_templates( struct ldap_disptmpl *tmpllist );

Parameters

This function has the parameter listed in Table 17-95.

Table 17-95  ldap_free_templates() Function Parameter

Parameter

Description

tmpllistp

Pointer to a list of template data structures.

Description

ldap_free_templates() releases the templates allocated by ldap_init_templates(). Each template defined in the file is an ldap_disptmpl structure.


ldap_free_urldesc()

The ldap_free_urldesc() function frees memory allocated by the ldap_url_parse() function.

Syntax

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

Parameters

This function has the parameter listed in Table 17-96.

Table 17-96  ldap_free_urldesc() Function Parameter

Parameter

Description

ludp

Pointer to a LDAPURLDesc structure.

Description

For more information, see "Freeing the Components of an LDAP URL" of Chapter 9, "Working with LDAP URLs."

Example

Code Example 17-16 parses an LDAP URL and then frees the LDAPURLDesc structure from memory after verifying that the LDAP URL is valid.

Code Example 17-16  ldap_free_urldesc() Code Example 

#include <stdio.h>

#include <ldap.h>

...

char *my_url = "ldap://ldap.example.com:5000/dc=example,dc=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 standard identifiers to their user-friendly counterparts. For example, you can represent the list of two-letter state codes (CA, IA) with their corresponding state names (California, Iowa), or map country ISO codes to the full country names.


Note

ldapfriendly, located in DSRK_base/lib/ldapcsdk/etc, is a sample file that maps two letter country codes to their full names. It can be used in context with ldap_friendly_name().


Syntax

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

Parameters

This function has the parameters listed in Table 17-97.

Table 17-97  ldap_friendly_name() function parameters 

Parameter

Description

filename

Name of the file mapping the standard identifiers to the user-friendly names.

uname

Standard identifier name for which you want to find the user-friendly name.

map

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

Returns

One of the following values:

Description

This function relies on the existence of a text file mapping standard identifiers to user-friendly names. The names in the file are tab-delimited, as shown in Code Example 17-17.

Code Example 17-17  Unfriendly to Friendly Name Mapping File 

<unfriendly_name> <friendly_name>

AD Andorra

AE United Arab Emirates

AF Afghanistan

AG Antigua and Barbuda

AI Anguilla

Example

Code Example 17-18 reads in a map of user-friendly names and prints the name corresponding to the standard identifier IS.

Code Example 17-18  ldap_friendly_name() Code Example 

#include <ldap.h>

#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 file is in memory, 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(), FriendlyMap


ldap_get_dn()

The ldap_get_dn() routine returns the DN for an entry in a chain of search results.

Syntax

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

Parameters

This function has the parameters listed in Table 17-98.

Table 17-98  ldap_get_dn() Function Parameters 

Parameter

Description

ld

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:

See Chapter 18, "Result Codes" for a complete listing of error codes.

Description

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 the Distinguished Name of an Entry" of Chapter 5, "Searching a LDAP Directory."

Example

Code Example 17-19 prints the DN for each entry found in a search.

Code Example 17-19  ldap_get_dn() Code Example 

#include <stdio.h>

#include <ldap.h>

...

LDAP *ld;

LDAPMessage *result, *e;

char *dn;

char *my_searchbase = "dc=example,dc=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_lderrno()


ldap_get_entry_controls()

The ldap_get_entry_controls() function 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 parameters listed in Table 17-99.

Table 17-99  ldap_get_entry_controls() Function Parameters

Parameter

Description

ld

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:

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 with each structure representing one LDAP control. 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.

Syntax

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

Parameters

This function has the parameter listed in Table 17-100.

Table 17-100  ldap_getfilter_free() Function Parameter 

Parameter

Description

lfdp

Pointer to a LDAPFiltDesc structure.

Description

Once you call ldap_getfilter_free(), the LDAPFiltDesc structure is no longer valid and cannot be used again.

For more information, see "Freeing Filters from Memory" of Chapter 17, "Function Reference."

Example

Code Example 17-20 frees the LDAPFiltDesc structure from memory after all searches are completed.

Code Example 17-20  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.

Syntax

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

Parameters

This function has the parameters listed in Table 17-101.

Table 17-101  ldap_getfirstfilter() Function Parameters 

Parameter

Description

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:

Description

For more information, see "Retrieving Filters" of Chapter 6, "Using Filter Configuration Files."

Example

Code Example 17-21 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 and, based on the criteria entered, it retrieves filters that match the criteria. Code Example 17-21 uses the filter configuration file shown in "The Filter Configuration File Syntax" of Chapter 6, "Using Filter Configuration Files."

Code Example 17-21  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, "dc=example,dc=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()


Caution

This function is deprecated and should not be used. It is included in ldap-deprecated.h for backward-compatibility. Please use ldap_get_values().


The ldap_get_lang_values() function returns a NULL-terminated array of an attribute’s string values that match a specified language subtype.

Syntax

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

Parameters

This function has the parameters listed in Table 17-102.

Table 17-102  ldap_get_lang_values() Function Parameters 

Parameters

Description

ld

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:

See Chapter 18, "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). If you want to retrieve binary data from an attribute, call the ldap_get_lang_values_len() function.

See Also

ldap_first_entry(), ldap_first_attribute(), ldap_get_lang_values_len(), ldap_get_values(), ldap_next_entry(), ldap_next_attribute()


ldap_get_lang_values_len()


Caution

This function is deprecated and should not be used. It is included in ldap-deprecated.h for backward-compatibility. Please use ldap_get_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.

Syntax

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

Parameters

This function has the parameters listed in Table 17-103.

Table 17-103  ldap_get_lang_values_len() Function Parameters 

Parameter

Description

ld

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:

See Chapter 18, "Result Codes" for a complete listing of error codes.

Description

Use the ldap_get_lang_values() routine if the attribute values are string values.

For more information, see "Getting the Values of an Attribute" of Chapter 5, "Searching a LDAP Directory."

See Also

ldap_first_attribute(), ldap_first_entry(), ldap_get_lang_values(), ldap_next_entry(), ldap_next_attribute()


ldap_get_lderrno()

The ldap_get_lderrno() function gets information about the last error that occurred for an LDAP operation.

Syntax

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

Parameters

This function has the parameters listed in Table 17-104.

Table 17-104  ldap_get_lderrno() Function Parameters 

Parameter

Description

ld

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 Matching Portion of a DN" of Chapter 4, "Using the LDAP API.")

s

The text of the error message.

Returns

The LDAP error code for the last operation. See Chapter 18, "Result Codes" for a complete listing of error codes.

Description

ldap_get_lderrno() 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 an Error" of Chapter 4, "Using the LDAP API."

Example

Code Example 17-22 attempts to add a new user to the directory. If the entry identified by a DN does not exist, the server returns the portion of the DN that matches an existing entry; this is the variable matched. (See "Receiving the Matching Portion of a DN" of Chapter 4, "Using the LDAP API" for details.)

Code Example 17-22  ldap_get_lderrno() Code Example

#include <ldap.h>

LDAP *ld;

char *dn = "uid=bjensen,ou=People,dc=example,dc=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 Code Example 17-22, if no organizational unit named People exists, the matched variable is set to dc=example,dc=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.

Syntax

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

Parameters

This function has the parameter listed in Table 17-105.

Table 17-105  ldap_getnextfilter() Function Parameter

Parameter

Description

lfdp

Pointer to an LDAPFiltDesc structure.

Returns

One of the following values:

Description

Call this function to get subsequent filters after calling ldap_getfirstfilter().

For more information, see "Retrieving Filters" of Chapter 6, "Using Filter Configuration Files."

Example

See Code Example 17-21 under ldap_getfirstfilter().

See Also

ldap_getfirstfilter()


ldap_get_option()

The function ldap_get_option() retrieves session preferences from an LDAP structure.

Syntax

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

Parameters

This function has the parameters listed in Table 17-106.

Table 17-106  ldap_get_option() Function Parameters 

Parameter

Description

ld

Pointer to an LDAP structure containing information about the connection to the LDAP server.

option

Option that you want to retrieve. This parameter must be set to one of the option values, as detailed in Table 17-107.

optdata

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

Table 17-107 describes the options that you can retrieve with ldap_get_option().

Table 17-107  Options for the ldap_get_options() Function 

Option

Description

LDAP_OPT_API_FEATURE_INFO

Retrieves information about the revision of a supported LDAP feature. This option is READ-ONLY and cannot be set.

The data type for the optdata parameter is (LDAPAPIFeatureInfo *).

LDAP_OPT_API_INFO

Retrieves information about the API implementation at execution time (API version, protocol version, the names of supported API extensions with their vendor name version, etc.). For details on the structure returned, refer to the ldap.h header file. This option is READ-ONLY and cannot be set.

The data type for the optdata parameter is (LDAPAPIInfo *).

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 LBER_SOCKET data type depends on the platform that you are using:

  • int in UNIX.
  • SOCKET in Windows.

The data type for the optdata parameter is (LBER_SOCKET *).

LDAP_OPT_DEREF

Determines how aliases work during a search. 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.

The data type for the optdata parameter is (int *).

LDAP_OPT_DNS_FN_PTRS

DEPRECATED OPTION: 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

Retrieves the result code for the most recent LDAP error that occurred in this session.

The data type for the optdata parameter is (int *).

LDAP_OPT_ERROR_STRING

Retrieves the error message returned with the result code for the most recent LDAP error that occurred in 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 14, "Writing Multithreaded Clients" for details.)

The data type for the optdata parameter is (struct ldap_extra_thread_fns *).

LDAP_OPT_HOST_NAME

Sets the host name (or list of hosts) for the primary LDAP server.

The data type for the optdata parameter is (char **).

LDAP_OPT_IO_FN_PTRS

DEPRECATED OPTION: 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.

The data type for the optdata parameter is (char **)

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

The data type for the optdata parameter is (int *).

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. By default, this option is off. For details, see "Handling Failover" of Chapter 4, "Using the LDAP API." 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.

The data type for the optdata parameter is (int *).

LDAP_OPT_REFERRALS

Determines whether or not the client should follow referrals. By default, the client follows referrals. 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.

The data type for the optdata parameter is (int *).

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. By default, the maximum number of referrals that the client can follow in a sequence is 5 for the initial connection. This limit does not apply to individual requests that generate multiple referrals in parallel.

The data type for the optdata parameter is (int *).

LDAP_OPT_RESTART

Determines whether or not LDAP I/O operations should be restarted automatically if they are prematurely aborted. 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.

The data type for the optdata parameter is (int *).

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 LDAP server may impose a smaller size limit than the limit you specify as the server administrator also has the ability to set this limit.

The data type for the optdata parameter is (int *).

LDAP_OPT_SSL

Determines whether or not SSL is enabled. optdata can be one of the following values:

  • LDAP_OPT_ON specifies that SSL is enabled.
  • LDAP_OPT_OFF specifies that SSL is disabled.

The data type for the optdata parameter is (int *).

LDAP_OPT_THREAD_FN_PTRS

Lets you specify the thread function pointers. (See Chapter 14, "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 LDAP server may impose a shorter time limit than the limit you specify as the server administrator also has the ability to set this limit.

The data type for the optdata parameter is (int *).

LDAP_X_OPT_EXTIO_FN_PTRS

Extended I/O function callback option.

LDAP_X_OPT_CONNECT_TIMEOUT

Value of a timeout (expressed in milliseconds) for nonblocking connect call.

The data type for the optdata parameter is (int *).

LDAP_X_OPT_SOCKBUF

Socket buffer structure associated to the LDAP connection.

Returns

One of the following values:

Description

For more information, see "Retrieving SDK Information" of Chapter 4, "Using the LDAP API."

Examples

Code Example 17-23 gets the session preference for the maximum number of entries to be returned from search operations.

Code Example 17-23  ldap_get_option() Code Example 

#include <ldap.h>

...

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

}

Code Example 17-24 contains two small sections of code that show how to use the LDAP_OPT_API_FEATURE_INFO and the LDAP_OPT_API_INFO options, respectively.

Code Example 17-24  LDAP_OPT_API_FEATURE_INFO and LDAP_OPT_API_INFO Usage 

LDAPIIFeatureInfo ldfi;

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.

Syntax

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

Parameters

This function has the parameters listed in Table 17-108.

Table 17-108  ldap_get_values() Function Parameters 

Parameters

Description

ld

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:

See Chapter 18, "Result Codes" for a complete listing of error codes.

Description

Use the ldap_get_values_len() function if the attribute values are binary.

For more information, see "Getting the Values of an Attribute" of Chapter 5, "Searching a LDAP Directory."

Example

Code Example 17-25 gets and prints the values of an attribute in an entry. This example assumes that all attributes have string values.

Code Example 17-25  ldap_get_values() Code Example 

#include <stdio.h>

#include <ldap.h>

...

LDAP *ld;

LDAPMessage *result, *e;

BerElement *ber;

char *a;

char **vals;

char *my_searchbase = "dc=example,dc=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_first_attribute(), ldap_get_values_len(), ldap_next_entry(), ldap_next_attribute()


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.

Syntax

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

Parameters

This function has the parameters listed in Table 17-109.

Table 17-109  ldap_get_values_len() Function Parameters 

Parameter

Description

ld

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:

See Chapter 18, "Result Codes" for a complete listing of error codes.

Description

Use the ldap_get_values() routine if the attribute values are string values.

For more information, see "Getting the Values of an Attribute" of Chapter 5, "Searching a LDAP Directory."

Example

Code Example 17-26 gets the first value of the jpegPhoto attribute and saves the JPEG data to a file.

Code Example 17-26  ldap_get_values_len() Code Example 

#include <stdio.h>

#include <ldap.h>

...

LDAP *ld;

LDAPMessage *result, *e;

BerElement *ber;

struct berval photo_data;

struct berval **list_of_photos;

FILE *out;

char *my_searchbase = "dc=example,dc=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_first_attribute(), ldap_get_values(), ldap_next_entry(), ldap_next_attribute()


ldap_init()

The ldap_init() function 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 parameters listed in Table 17-110.

Table 17-110  ldap_init() Function Parameters 

Parameter

Description

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:

Description

The ldap_init() function initializes a session with an LDAP server by allocating 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. (The LDAP structure defaults to LDAPv2. It is highly recommended to set it to LDAPv3 using the ldap_set_option().)


Caution

ldap_init() does not open a connection to the LDAP server. The actual connection opening will occur when the first operation is attempted. Certain fields in the LDAP structure can be set using ldap_set_option().


You can specify a list of LDAP servers to which you want to attempt to connect by passing a space-delimited list of the host names as the defhost argument. 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. In Code Example 17-27, the LDAP client will attempt to connect to the LDAP server on ld1.example.com, port 389. If that server does not respond, the client will attempt to connect to the LDAP server on ld2.example.com, port 389. If that server does not respond, the client will use the server on ld3.example.com, port 389.

Code Example 17-27  Space-Delimited List for ldap_init() 

...

LDAP *ld

...

ld = ldap_init( "ld1.example.com ld2.example.com \

ld3.example.com", LDAP_PORT );

If any of the servers do not use the default port specified by the defport argument, use the hostname:portnumber format to specify the server name. In Code Example 17-28, the LDAP client will attempt to connect to the LDAP server on ld1.example.com, port 389. If that server does not respond, the client will attempt to connect to the LDAP server on ld2.example.com, port 38900.

Code Example 17-28  ldap_init() Example Using Variable Argument

...

LDAP *ld

...

ld = ldap_init( "ld1.example.com ld2.example.com:38900", \ LDAP_PORT );

For more information, see "Initializing an LDAP Session" of Chapter 3, "Writing an LDAP Client."


Note

If you are connecting to a secure LDAP server over SSL, you should be calling the ldapssl_init() function. For details, see Chapter 11, "Connecting Over SSL."


Example

Code Example 17-29 initializes a session with the LDAP server at ldap.example.com:389, and sets a session preference that identifies the client as an LDAPv3 client.

Code Example 17-29  ldap_init() Code Example 

#include <ldap.h>

...

LDAP *ld;

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

char *ldap_host = "ldap.example.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.example.com:389 */

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

perror( "ldap_init" );

return( 1 );

}

/* Specify the LDAP version supported by the client. */

version = LDAP_VERSION3;

ldap_set_option( ld, LDAP_OPT_PROTOCOL_VERSION, &version );

...

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

...

See Also

ldap_unbind(), ldap_unbind_s(), ldap_simple_bind(), ldap_simple_bind_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.


Note

ldapfilter.conf, the sample LDAP filter configuration file located in the DSRK_base/lib/ldapcsdk/etc directory, can be used in context with ldap_init_getfilter().


Syntax

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

Parameters

This function has the parameters listed in Table 17-111.

Table 17-111  ldap_init_getfilter() Function Parameter 

Parameter

Description

fname

Name of the LDAP filter configuration file to use.

Returns

One of the following values:

Description

For more information, see "Loading a Filter Configuration File" of Chapter 6, "Using Filter Configuration Files."

Example

Code Example 17-30 loads a filter configuration file named myfilters.conf into memory.

Code Example 17-30  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.

Syntax

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

Parameters

This function has the parameters listed in Table 17-112.

Table 17-112  ldap_init_getfilter_buf() Function Parameters 

Parameter

Description

buf

Buffer containing LDAP filter configuration information.

buflen

Size of the buffer

Returns

One of the following values:

Description

The configuration information in the buffer must use the correct syntax, as specified in "The Filter Configuration File Syntax" of Chapter 6, "Using Filter Configuration Files."

Example

Code Example 17-31 copies the following filter configuration to a buffer in memory and uses this buffer to fill an LDAPFiltDesc structure.

"ldap-example"

"@" " " "(mail=%v)" "email address"

"(mail=%v*)" "start of email address"

Code Example 17-31  ldap_init_getfilter() Code Example

#include <string.h>

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

The ldap_init_searchprefs() function reads a sequence of search preference configurations from a valid LDAP searchpref configuration file.

Syntax

#include <ldap.h>
int ldap_init_searchprefs( char *file, struct ldap_searchobj **solistp );

Parameters

This function has the parameters listed in Table 17-113.

Table 17-113  ldap_init_searchprefs() Function Parameters 

Parameter

Description

file

Pointer to a valid LDAP searchpref configuration file.

solistp

Pointer to a list of search preference data structures.

Returns

One of the following values:

Description

ldap_init_searchprefs() provides a standard way to access LDAP search preference configuration data.


Note

LDAP search preference configurations are typically used by LDAP client programs to specify which attributes a user may search by, labels for the attributes, and LDAP filters and scopes associated with those searches. Client software presents these choices to a user, who can then specify the type of search to be performed. See the man page for ldapsearchprefs.conf for more information.


See Also

ldap_free_searchprefs(), ldap_init_searchprefs_buf()


ldap_init_searchprefs_buf()

The ldap_init_searchprefs_buf() function reads a sequence of search preference configurations from the parameter, buf.

Syntax

#include <ldap.h>
int ldap_init_searchprefs_buf( char *buf, long buflen,
  struct ldap_searchobj **solistp );

Parameters

This function has the parameters listed in Table 17-114.

Table 17-114  ldap_init_searchprefs_buf() Function Parameters 

Parameter

Description

buf

Pointer to data in the format defined for an LDAP search preference configuration file.

buflen

The size of buf.

solistp

Pointer to a list of search preference data structures.

Returns

One of the following values:

Description

ldap_init_searchprefs_buf() reads a sequence of search preference configurations from buf.


Note

LDAP search preference configurations are typically used by LDAP client programs to specify which attributes a user may search by, labels for the attributes, and LDAP filters and scopes associated with those searches. Client software presents these choices to a user, who can then specify the type of search to be performed. See the man page for ldapsearchprefs.conf for more information.


See Also

ldap_init_searchprefs(), ldap_free_searchprefs()


ldap_init_templates()

The ldap_init_templates() function reads a sequence of templates from a valid LDAP template configuration file.

Syntax

#include <disptmpl.h>
int ldap_init_templates( char *file, struct ldap_disptmpl **tmpllistp );

Parameters

This function has the parameters listed in Table 17-115.

Table 17-115  ldap_init_templates() Function Parameters 

Parameter

Description

file

Pointer to a valid LDAP template configuration file.

tmpllistp

Pointer to a list of template data structures.

Returns
Description

ldap_init_templates() reads a sequence of templates from a valid LDAP template configuration file. Each template defined in the file is an ldap_disptmpl structure.

See Also

ldap_init_templates_buf(), ldap_free_templates()


ldap_init_templates_buf()

The ldap_init_templates_buf() function reads a sequence of templates from a buffer.

Syntax

#include <disptmpl.h>
int ldap_init_templates_buf( char *buf, long buflen,
  struct ldap_disptmpl **tmpllistp );

Parameters

This function has the parameters listed in Table 17-116.

Table 17-116  ldap_init_templates_buf() Function Parameters 

Parameter

Description

buf

Pointer to data in the format defined for a valid LDAP template configuration file.

buflen

The size of buf.

tmpllistp

Pointer to a list of template data structures.

Returns
Description

The ldap_init_templates_buf() function reads a sequence of templates from a buffer.

See Also

ldap_init_templates(), ldap_free_templates()


ldap_is_dns_dn()


Caution

This function is deprecated and should not be used. It is included in ldap-to-be-deprecated.h for backward-compatibility.


The ldap_is_dns_dn() function determines whether a DN string is of the experimental DNS-style DN (generally in the form of an RFC 822 e-mail address) or the RFC 1779 formatted DN.

Description

This function is specific to LDAPv2 and should not be used when dealing with LDAPv3 servers or data.


Note

More information can be found in RFC 1779 - A String Representation of Distinguished Names (http://www.faqs.org/rfcs/rfc1779.html) and RFC 822 - Standard for the Format of ARPA Internet Text Messages (http://www.faqs.org/rfcs/rfc822.html).



ldap_is_ldap_url()

The ldap_is_ldap_url() function determines whether or not a URL is an LDAP URL.

Syntax

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

Parameters

This function has the parameter listed in Table 17-117.

Table 17-117   ldap_is_ldap_url() Function Parameter

Parameter

Description

url

The URL that you want to check.

Returns

One of the following values:

Description

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 a SSL connection).

For more information, see "Determining an LDAP URL" of Chapter 9, "Working with LDAP URLs."

Example

Code Example 17-32 determines if a URL is a LDAP URL.

Code Example 17-32  ldap_is_ldap_url() Code Example 

#include <stdio.h>

#include <ldap.h>

...

char *my_url = "ldap://ldap.sun.com/dc=example,dc=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_keysort_entries()

The ldap_keysort_entries() function is used for sorting entries.

Syntax

#include <ldap-extension.h>
int ldap_keysort_entries( LDAP *ld, LDAPMessage **chain,
  void *arg, LDAP_KEYGEN_CALLBACK *gen, LDAP_KEYCMP_CALLBACK *cmp,
  LDAP_KEYFREE_CALLBACK *fre );

Parameters

This function has the parameters listed in Table 17-118.

Table 17-118   ldap_keysort_entries() Function Parameter

Parameter

Description

ld

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.

arg

Pointer to an additional argument that you want to pass.

gen

Callback used to generate the key(s) for sorting once the compare function has been applied.

cmp

Comparison function used when sorting the values. For details, see "Sorting Entries by an Attribute" of Chapter 5, "Searching a LDAP Directory."

fre

Callback used to free the key once the compare function has been applied.

See Also

LDAP_KEYGEN_CALLBACK, LDAP_KEYCMP_CALLBACK, LDAP_KEYFREE_CALLBACK


ldap_memcache_destroy()

The ldap_memcache_destroy() function frees an LDAPMemCache structure from memory.

Syntax

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

Parameters

This function has the parameter listed in Table 17-119.

Table 17-119   ldap_memcache_destroy() Function Parameter

Parameter

Description

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

The ldap_memcache_flush() function 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 parameters listed in Table 17-120.

Table 17-120   ldap_memcache_flush() Function Parameters 

Parameter

Description

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

The ldap_memcache_get() function 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 parameters listed in Table 17-121.

Table 17-121   ldap_memcache_get() Function Parameters

Parameter

Description

ld

Pointer to an LDAP structure containing information about the connection to the LDAP server.

cachep

When you call ldap_memcache_get(), it sets this parameter to the pointer to the LDAPMemCache structure associated with the connection handle.

Returns

One of the following values:

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

The ldap_memcache_init() function 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 parameters listed in Table 17-122.

Table 17-122   ldap_memcache_init() Function Parameters 

Parameter

Description

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, it sets this parameter to the pointer to the newly created LDAPMemCache structure.

Returns

One of the following values:

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

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.


Caution

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 LDAP SDK for C, v5.2.


See Also

LDAPMemCache, ldap_memcache_set(), ldap_memcache_flush(), ldap_memcache_destroy(), ldap_memcache_update()


ldap_memcache_set()

The ldap_memcache_set() function 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 parameters listed in Table 17-123.

Table 17-123   ldap_memcache_set() Function Parameters

Parameter

Description

ld

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:

Description

The ldap_memcache_set() function associates a cache (created by calling ldap_memcache_init()) with an 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 ldap_memcache_set() to associate the cache with another connection.

After you call this function, search requests made over the specified LDAP connection will use this cache. Calling the ldap_unbind() function will disassociate the cache from the LDAP connection handle.

See Also

ldap_memcache_init(), ldap_memcache_get()


ldap_memcache_update()

The ldap_memcache_update() function 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 parameter listed in Table 17-124.

Table 17-124   ldap_memcache_update() Function Parameter

Parameter

Description

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.


Tip

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

The ldap_memfree() function frees memory allocated by an LDAP API function call.

Syntax

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

Parameters

This function has the parameter listed in Table 17-125.

Table 17-125   ldap_memfree() Function Parameter

Parameter

Description

p

Pointer to memory used by the LDAP library.

Description

For more information, see "Managing Memory" of Chapter 4, "Using the LDAP API."

Example

Code Example 17-33 frees the memory allocated by the ldap_get_dn() function.

Code Example 17-33  ldap_memfree() Code Example 

#include <ldap.h>

...

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

The ldap_modify() function modifies an existing entry in the directory asynchronously.


Note

This is an older function included in the SDK 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 parameters listed in Table 17-126.

Table 17-126   ldap_modify() Function Parameters 

Parameter

Description

ld

Pointer to an LDAP structure containing information about the connection to the LDAP server.

dn

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

Description

Please use the newer version of this function, ldap_modify_ext().

Example

Code Example 17-34 uses the asynchronous ldap_modify() function to modify the entry for Barbara Jensen in the directory. It makes the following changes to the entry:

See Also

ldap_modify_ext()


ldap_modify_ext()

The ldap_modify_ext() function modifies an existing entry in the directory asynchronously.


Note

ldap_modify_ext() is a new version of the ldap_modify() function. If you are writing a new LDAP client, use ldap_modify_ext().


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 parameters listed in Table 17-127.

Table 17-127   ldap_modify_ext() Function Parameters 

Parameter

Description

ld

Pointer to an LDAP structure containing information about the connection to the LDAP server.

dn

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

Returns

One of the following values:

Description

The ldap_modify_ext() modifies an entry in the directory 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. In order to get the results of this LDAP modify operation, you need to call the ldap_result() and the ldap_parse_result() functions. To make changes to an entry to the directory, you need to specify the following information:

For more information on modifying entries in the directory, see "Modifying an Entry" of Chapter 17, "Function Reference." For a list of possible result codes for an LDAP modify operation, see ldap_modify_ext_s(). For information on using the LDAPMod structure to specify a change, see "LDAPMod" of Chapter 16, "Data Type Reference."

Example

See Code Example 7-17 of Chapter 7, "Adding, Modifying and Deleting Entries."

See Also

ldap_modify_ext_s(), ldap_result(), ldap_parse_result(), LDAPMod


ldap_modify_ext_s()

The ldap_modify_ext_s() modifies an existing entry in the directory synchronously.


Note

ldap_modify_ext_s() is a new version of the ldap_modify_s() function. If you are writing a new LDAP client, use ldap_modify_ext_s().


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 parameters listed in Table 17-128.

Table 17-128   ldap_modify_ext_s() Function Parameters 

Parameter

Description

ld

Pointer to an LDAP structure containing information about the connection to the LDAP server.

dn

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 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 operation. If you do not want to pass any client controls, specify NULL for this argument.

Returns

One of the following values:

Description

The ldap_modify_ext_s() modifies an entry in the directory. 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.

To make changes to an entry to the directory, you need to specify the following information:

For more information on modifying entries in the directory, see "Modifying an Entry" of Chapter 17, "Function Reference." For information on using the LDAPMod structure to specify a change, see "LDAPMod" of Chapter 16, "Data Type Reference."

Example

See Code Example 7-15 of Chapter 7, "Adding, Modifying and Deleting Entries."

See Also

ldap_modify_ext(), LDAPMod


ldap_modify_s()

The ldap_modify_s() function modifies an existing entry in the directory synchronously.


Note

This is an older function that is included in the SDK 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 parameters listed in Table 17-129.

Table 17-129   ldap_modify_s() Function Parameters 

Parameter

Description

ld

Pointer to an LDAP structure containing information about the connection to the LDAP server.

dn

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

For a list of possible result codes for an LDAP modify operation, see ldap_modify_ext_s().

Description

Please use the newer version of this function, ldap_modify_ext_s().

Example

Code Example 17-35 uses the synchronous ldap_modify_s() function to makes the following changes to the Barbara Jensen entry:

See Also

ldap_modify_ext_s()


ldap_modrdn()


Caution

This function is deprecated and should not be used. It is included in ldap-deprecated.h for backward-compatibility. Please use ldap_rename().



ldap_modrdn_s()


Caution

This function is deprecated and should not be used. It is included in ldap-deprecated.h for backward-compatibility. Please use ldap_rename_s().



ldap_modrdn2()


Caution

This function is deprecated and should not be used. It is included in ldap-deprecated.h for backward-compatibility. Please use ldap_rename() instead.


The ldap_modrdn2() function changes the relative distinguished name (RDN) of an entry in the directory asynchronously.

Syntax

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

Parameters

This function has the parameters listed in Table 17-130.

Table 17-130   ldap_modrdn2() Function Parameters

Parameter

Description

ld

Pointer to an LDAP structure containing information about the connection to the LDAP server.

dn

DN of the entry to modify.

newrdn

New 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 ldap_rename().

Description

Please use the newer version of this function, ldap_rename().

Example

Code Example 17-36 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 17-36  ldap_modrdn2() Code Example 

#include <ldap-deprecated.h>

...

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,dc=example,dc=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()


Caution

This function is deprecated and should not be used. It is included in ldap-deprecated.h for backward-compatibility. Please use ldap_rename_s() instead.


The ldap_modrdn2_s() function changes the relative distinguished name (RDN) of an entry in the directory synchronously.

Syntax

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

Parameters

This function has the parameters listed in Table 17-131.

Table 17-131   ldap_modrdn2_s() Function Parameters

Parameter

Description

ld

Pointer to an LDAP structure containing information about the connection to the LDAP server.

dn

DN of the entry to modify.

newrdn

New 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 ldap_rename_s().

Description

Please use the newer version of this function, ldap_rename_s().

Example

Code Example 17-37 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 17-37  ldap_modrdn2_s() Code Example 

#include <ldap.h>

...

LDAP *ld;

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

char *dn = "uid=bjensen,ou=People,dc=example,dc=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.


Note

You need to call this function only if you’ve allocated memory for these structures yourself. For more information, see the ldap-extension.h header file.


Syntax

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

Parameters

This function has the parameters listed in Table 17-132

Table 17-132   ldap_mods_free() Function Parameters 

Parameter

Description

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

Code Example 17-38 allocates memory for LDAPMod structures and frees them when done.

Code Example 17-38  ldap_mods_free() Code Example 

#include <stdio.h>

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

Syntax

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

Parameters

This function has the parameter listed in Table 17-133.

Table 17-133   ldap_msgfree() Function Parameter

Parameter

Description

lm

Pointer to the result to be freed from memory.

Returns

One of the following values:

See Chapter 18, "Result Codes" for a complete listing.

Description

For more information, see "Freeing the Search Results" of Chapter 5, "Searching a LDAP Directory."

Example

Code Example 17-39 frees the results of a search.

Code Example 17-39  ldap_msgfree() Code Example

#include <stdio.h>

#include <ldap.h>

...

LDAP *ld;

LDAPMessage *result;

char *my_searchbase = "dc=example,dc=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 parameter listed in Table 17-134.

Table 17-134   ldap_msgid() Function Parameter

Parameter

Description

lm

Pointer to the result to check.

Returns

One of the following values:

Example

Code Example 17-40 prints the message ID from the result obtained from a synchronous LDAP search operation.

Code Example 17-40  ldap_msgid() Code Example

#include <stdio.h>

#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 parameter listed in Table 17-135.

Table 17-135   ldap_msgtype() Function Parameter

Parameter

Description

lm

Pointer to the LDAPMessage structure to check.

Returns

One of the following values:

Example

Code Example 17-41 prints the message type for a result obtained from a synchronous LDAP search operation.

Code Example 17-41  ldap_msgtype() Code Example

#include <stdio.h>

#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 either a specified set of attributes in the entries or DN.

Syntax

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

Parameters

This function has the parameters listed in Table 17-136.

Table 17-136   ldap_multisort_entries() Function Parameters

Parameter

Description

ld

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 for sorting the results. If NULL, results are sorted by DN.

cmp

Comparison function used when sorting the values. For details, see "Sorting Entries by an Attribute" of Chapter 5, "Searching a LDAP Directory."

Returns

One of the following values:

Example

Code Example 17-42 sorts entries first by the roomNumber attribute, then by the telephoneNumber attribute.

Code Example 17-42  ldap_multisort_entries() Code Example 

#include <stdio.h>

#include <string.h>

#include <ldap.h>

...

LDAP *ld;

LDAPMessage *result;

char *my_searchbase = "dc=example,dc=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_CMP_CALLBACK


ldap_name2template()

The ldap_name2template() function obtains a pointer to the correct ldap_disptmpl structure.

Syntax

#include <disptmpl.h>
struct ldap_disptmpl * ldap_name2template( char *name
  struct ldap_disptmpl *tmpllist );

Parameters

This function has the parameters listed in Table 17-137.

Table 17-137   ldap_name2template() Function Parameters

Parameter

Description

name

Name of the template.

tmpllistp

Pointer to a list of template data structures.

Returns
Description

ldap_name2template() obtains a pointer to the correct ldap_disptmpl structure. Links to templates can be defined by name.


ldap_next_attribute()

The ldap_next_attribute() function returns the name of the next attribute in an entry returned by ldap_first_entry() or ldap_next_entry().

Syntax

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

Parameters

This function has the parameters listed in Table 17-138.

Table 17-138   ldap_next_attribute() Function Parameters

Parameter

Description

ld

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:

See Chapter 18, "Result Codes" for a complete listing of error codes.

Description

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 Attribute Names from an Entry" of Chapter 5, "Searching a LDAP Directory."

Example

See the example under ldap_first_attribute().

See Also

ldap_first_attribute(), ldap_getfirstfilter(), ldap_next_entry()


ldap_next_disptmpl()

The ldap_next_disptmpl() function returns the next template in a list.

Syntax

#include <disptmpl.h>
struct ldap_disptmpl * ldap_next_disptmpl( struct ldap_disptmpl *tmpllist,
  struct ldap_disptmpl *tmpl );;

Parameters

This function has the parameters listed in Table 17-139.

Table 17-139   ldap_next_disptmpl() Function Parameters 

Parameter

Description

tmpl

Defines a template from the template list tmpllist. A NULL pointer is returned if tmpl is the last template in the list.

tmpllistp

Pointer to a list of template data structures typically obtained by calling ldap_init_templates().

Returns
Description

ldap_next_disptmpl() returns the template following the previous one in the list of templates pointed to by the parameter tmpllistp. tmpllistp is typically obtained by calling ldap_init_templates().

See Also

ldap_first_disptmpl()


ldap_next_entry()

The ldap_next_entry() function 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 parameters listed in Table 17-140.

Table 17-140   ldap_next_entry() Function Parameters

Parameter

Description

ld

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:

Description

The ldap_next_entry() function returns a pointer to the LDAPMessage structure representing the next directory entry in a chain of search results. 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 as messages containing directory entries have the type LDAP_RES_SEARCH_ENTRY.

For more information, see "Sorting the Search Results" in Chapter 5, "Searching a LDAP Directory."

See Also

ldap_first_entry()


ldap_next_message()

The ldap_next_message() function 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 parameters listed in Table 17-141.

Table 17-141   ldap_next_message() Function Parameters

Parameter

Description

ld

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:

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 also 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 "Sorting the Search Results" in Chapter 5, "Searching a LDAP Directory."

Example

See Code Example 5-4 and Code Example 5-7 of Chapter 5, "Searching a LDAP Directory."

See Also

ldap_first_message(), ldap_msgtype()


ldap_next_reference()

The ldap_next_reference() function 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 parameters listed in Table 17-142.

Table 17-142   ldap_next_reference() Function Parameters

Parameter

Description

ld

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:

Description

The ldap_next_reference() function returns a pointer to the LDAPMessage structure representing the next search reference in a chain of search results. 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 as messages containing search references have the type LDAP_RES_SEARCH_REFERENCE.

For more information, see "Sorting the Search Results" in Chapter 5, "Searching a LDAP Directory."

See Also

ldap_first_reference()


ldap_next_searchobj()

The ldap_next_searchobj() function returns the following search preference in a defined list.

Syntax

#include <ldap.h>
struct ldap_searchobj * ldap_next_searchobj
  ( struct ldap_searchobj *sollist, struct ldap_searchobj *so );

Parameters

This function has the parameters listed in Table 17-143.

Table 17-143   ldap_next_searchobj() Function Parameters 

Parameter

Description

sollist

Pointer to a list of data structures, typically obtained by calling ldap_init_searchprefs().

so

Pointer to the most recent search object returned in the template list sollist. The search object returned by ldap_next_searchobj() follows this one.

Returns
Description

The search object returned by ldap_next_searchobj() follows the one defined by the so parameter.

See Also

ldap_init_searchprefs(), ldap_first_searchobj()


ldap_next_tmplcol()

The ldap_next_tmplcol() function returns a pointer to the following item (in the column) within a template.

Syntax

#include <disptmpl.h>
struct ldap_tmplitem * ldap_next_tmplcol( struct ldap_disptmpl *tmpl,
  struct ldap_tmplitem *row, struct ldap_tmplitem *col );

Parameters

This function has the parameters listed in Table 17-144.

Table 17-144   ldap_next_tmplcol() Function Parameters 

Parameter

Description

tmpl

The name of the template to be retrieved.

row

The row in which the item is to be retrieved from.

col

The column in which the item is to be retrieved from.

Returns
Description

ldap_next_tmplcol() returns a pointer to the next item (in the column) of the row, defined by row, within the template defined by tmpl.

See Also

ldap_first_tmplcol()


ldap_next_tmplrow()

The ldap_next_tmplrow() function returns a pointer to the following row in a template.

Syntax

#include <disptmpl.h>
struct ldap_tmplitem * ldap_next_tmplrow( struct ldap_disptmpl *tmpl,
  struct ldap_tmplitem *row );

Parameters

This function has the parameters listed in Table 17-145.

Table 17-145   ldap_next_tmplrow() Function Parameters 

Parameter

Description

tmpl

The name of the template to be retrieved.

row

The row in the template to be retrieved.

Returns
Description

ldap_next_tmplrow() returns a pointer to the row that follows the one defined by row in the template defined by tmpl.


ldap_oc2template()

The ldap_oc2template() function obtains a pointer to the correct ldap_disptmpl structure.

Syntax

#include <disptmpl.h>
struct ldap_disptmpl * ldap_oc2template( char **oclist,
  struct ldap_disptmpl *tmpllist );

Parameters

This function has the parameters listed in Table 17-146.

Table 17-146   ldap_oc2template() Function Parameters 

Parameter

Description

oclist

A NULL-terminated array of strings that contains the values of the objectClass attribute of the entry.

tmpllistp

Pointer to a list of template data structures.

Returns
Description

ldap_oc2template()searches tmpllist for the best template to use to display an entry that has a specific set of objectClass values.


ldap_open()


Caution

This function is deprecated and should not be used. Please use ldap_init().


The ldap_open() function opens a connection to an LDAP server and allocates an LDAP structure which is used to identify the connection and maintain per-connection information.

Syntax

#include <ldap-deprecated.h>
ldap_open( const char *host, int port );

Parameters

This function has the parameters listed in Table 17-148.

Table 17-147   ldap_open() Function Parameters 

Parameter

Description

host

The hostname on which the LDAP server is running. It may contain a blank-separated list of hosts to try to connect to, and each host may optionally be of the form host:port. If present, port overrides the port parameter. Upon successfully making a connection to an LDAP server, ldap_open() returns a pointer to an LDAP structure, which should be passed to subsequent calls (ldap_bind(), ldap_search(), and so forth).

port

The port number to which to connect. If the default IANA-assigned port of 389 is desired, LDAP_PORT should be specified as the value of port.

Description

Please use the newer version of this function, ldap_init().


ldap_parse_entrychange_control()

The ldap_parse_entrychange_control() function 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).


Note

This function implements an extension to the LDAPv3. Entry change notification is an optional feature; it may not be supported on all LDAP servers. Call this function when interacting with LDAP servers that support this LDAPv3 extension. See "Determining Supported Extended Operations" of Chapter 15, "Extended Operations" to determine if the server supports extended operations.


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 parameters listed in Table 17-148.

Table 17-148   ldap_parse_entrychange_control() Function Parameters 

Parameter

Description

ld

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:

Description

The ldap_parse_entrychange_control() function can be called:

See Also

ldap_create_persistentsearch_control(), ldap_get_entry_controls()


ldap_parse_extended_result()

The ldap_parse_extended_result() function parses the results of an LDAP extended operation and retrieves the object identifier (OID) and data returned by the server.


Note

This function implements an extension to the LDAPv3. Extended operations might not be supported on all LDAP servers. Call this function only when interacting with LDAP servers that support this LDAPv3 extension. See "Determining Supported Extended Operations" of Chapter 15, "Extended Operations" 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 parameters listed in Table 17-149.

Table 17-149   ldap_parse_extended_result() Function Parameters 

Parameters

Description

ld

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

Description

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

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


Note

The LDAP server must support the extended operation. Sun Java System Directory Server supports a server plug-in interface that you can use to add support for extended operations. For details, see the Sun ONE Directory Server Plug-In Programming Guide.


See Also

ldap_extended_operation_s(), ldap_get_lderrno()


ldap_parse_reference()

The ldap_parse_reference() function parses search references from the results received from an LDAP server.


Note

Search references are part of the LDAPv3. When calling this function, make sure that you are working with a server that supports the LDAPv3.


Syntax

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

Parameters

This function has the parameters listed in Table 17-150.

Table 17-150   ldap_parse_reference() Function Parameters 

Parameter

Description

ld

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:

Description

The ldap_parse_reference() function parses the referral URLs from an LDAPMessage structure of the type LDAP_RES_SEARCH_REFERENCE.


ldap_parse_result()

The ldap_parse_result() function 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 parameters listed in Table 17-151.

Table 17-151   ldap_parse_result() Function Parameters

Parameter

Description

ld

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 Matching Portion of a DN" of Chapter 4, "Using the LDAP API" 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:

Description

The ldap_parse_result() function parses the results of an LDAP operation (received from an LDAP server) and retrieves:

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.

For more information, see "Performing an Asynchronous Authentication Operation" in Chapter 3, "Writing an LDAP Client."


Note

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 as follow:

See the example in Chapter 3, "Writing an LDAP Client" as follows:

See the example in Chapter 4, "Using the LDAP API" as follows:

See the example in Chapter 5, "Searching a LDAP Directory" as follows:

See Also

ldap_result()


ldap_parse_sasl_bind_result()

The ldap_parse_sasl_bind_result() function parses the results of an LDAP SASL bind operation and retrieves data returned by the server.


Note

SASL authentication is part of the LDAPv3. When calling this function, make sure that you are working with a server that supports the LDAPv3.


Syntax

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

Parameters

This function has the parameters listed in Table 17-152.

Table 17-152   ldap_parse_sals_bind_result() Function Parameters 

Parameter

Description

ld

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:

Description

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

See Also

ldap_sasl_bind(), ldap_get_lderrno()


ldap_parse_sort_control()

The parse_sort_control() function parses the result returned from a search operation that used a server control for sorting search results.


Note

This function implements an extension to the LDAPv3. Server-pside sorting is an optional feature; it may not be supported on all LDAP servers. Call this function when interacting with LDAP servers that support this LDAPv3 extension. See "Determining Supported Extended Operations" of Chapter 15, "Extended Operations" to determine if the server supports extended operations.


Syntax

#include <ldap.h>
int ldap_parse_sort_control( LDAP *ld, LDAPControl **ctrls,
  unsigned long *result, char **attribute );

Parameters

This function has the parameters listed in Table 17-153.

Table 17-153   ldap_parse_sort_control() Function Parameters 

Parameters

Description

ld

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, which indicates the result of parsing the server’s response:

Description

Call the ldap_parse_sort_control() function as part of the process of retrieving sorted search results from a server. First, though, call ldap_result() to get the results, and ldap_parse_result() to parse the server controls from the results.

See Also

ldap_create_sort_control()


ldap_parse_virtuallist_control()

The ldap_parse_virtuallist_control() function parses the result returned from a search operation that used a server control for virtual list views.


Note

This function implements an extension to the LDAPv3. A virtual list view is an optional LDAP server feature that may not be supported on all LDAP servers. For more information about this control, see "Using the Virtual List View Control" of Chapter 13, "Working with LDAP Controls." For information on determining if a server supports this or other LDAPv3 controls, see "Determining LDAPv3 Support" of Chapter 10, "Retrieving Server Information."


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 parameters listed in Table 17-154.

Table 17-154   ldap_parse_virtuallist_control() Function Parameters 

Parameters

Description

ld

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:

Description

The ldap_parse_virtuallist_control() function can be called:

See Also

ldap_create_virtuallist_control()


ldap_perror()


Caution

This function is deprecated and should not be used. It is included in ldap-deprecated.h for backward-compatibility. Please use ldap_get_lderrno() instead.


The ldap_perror() function prints, to standard output, the last LDAP error message.

Syntax

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

Parameters

This function has the parameters listed in Table 17-155.

Table 17-155   ldap_perror() Function Parameters

Parameter

Description

ld

Pointer to an LDAP structure containing information about the connection to the LDAP server.

s

Optional text to print out before printing the error message.

Description

Please use the newer version of this function, ldap_get_lderrno().

For more information, see "Printing Out Error Messages" of Chapter 4, "Using the LDAP API."

Example

Code Example 17-43 prints out an error message if the search operation cannot complete successfully.

Code Example 17-43  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()

The ldap_rename() function changes the DN of an entry in the directory asynchronously.


Note

ldap_rename() is a new version of the ldap_modrdn2() function. If you are writing a new LDAP client, you should call ldap_rename().


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 parameters listed in Table 17-156.

Table 17-156   ldap_rename() Function Parameters 

Parameter

Description

ld

Pointer to an LDAP structure containing information about the connection to the LDAP server.

dn

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

Specifies whether or not the old RDN is retained as an attribute of the entry. For example, 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

So, 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. To check the result of this operation, call the ldap_result() and ldap_parse_result() functions.

Returns

One of the following values:

Description

The ldap_rename() changes the DN of an entry in the directory and allows you to move the entry under a different parent entry in the directory tree. ldap_rename() is an asynchronous function; it does not directly return results. 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. If you want the results to be returned directly by the function, call the synchronous function ldap_rename_s() instead.

For more information on changing the DN of an entry, see "Changing the DN of an Entry" of Chapter 17, "Function Reference." For a list of possible result codes for an LDAP rename operation, see the RETURNS section of the ldap_rename_s() function.

Example

See Code Example 7-24 in Chapter 7, "Adding, Modifying and Deleting Entries."

See Also

ldap_rename_s(), ldap_result(), ldap_parse_result()


ldap_rename_s()

The ldap_rename_s() function changes the DN of an entry in the directory synchronously.


Note

ldap_rename_s() is a new version of the ldap_modrdn2_s() function. If you are writing a new LDAP client, you should call ldap_rename_s().


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 parameters listed in Table 17-157.

Table 17-157   ldap_rename() Function Parameters 

Parameter

Description

ld

Pointer to an LDAP structure containing information about the connection to the LDAP server.

dn

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

Specifies whether or not the old RDN is retained as an attribute of the entry. For example, 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

So, 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 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 operation. If you do not want to pass any client controls, specify NULL for this argument.

Returns

One of the following values:

Description

The ldap_rename_s() changes the DN of an entry in the directory and allows you to move the entry under a different parent entry in the directory tree. 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().

For more information on changing the DN of an entry, see "Changing the DN of an Entry" of Chapter 17, "Function Reference."

Example

See Code Example 7-25 in Chapter 7, "Adding, Modifying and Deleting Entries."

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.

Syntax

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

Parameters

This function has the parameters listed in Table 17-158.

Table 17-158   ldap_result() Function Parameters 

Parameter

Description

ld

Pointer to an LDAP structure containing information about the connection to the LDAP server.

msgid

Asynchronous functions return a unique message ID. This parameter takes 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:

Description

For more information, see "Performing an Asynchronous Authentication Operation" in Chapter 3, "Writing an LDAP Client" and "To Retrieve the Server Response" in Chapter 4, "Using the LDAP API."

Example

See the examples in the following sections:

See Also

ldap_add_ext(), ldap_compare_ext(), ldap_delete_ext(), ldap_modify_ext(), ldap_rename(), ldap_simple_bind(), ldap_url_search()


ldap_result2error()


Caution

This function is deprecated and should not be used. It is included in ldap-deprecated.h for backward-compatibility. Please use the newer version, ldap_parse_result().


The ldap_result2error() function returns the corresponding error code for a result produced by the ldap_result() and ldap_search_s() functions.

Syntax

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

Parameters

This function has the parameters listed in Table 17-159.

Table 17-159   ldap_result2error() Function Parameters 

Parameter

Description

ld

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:

Example

See ldap_result().

See Also

ldap_parse_result(), ldap_get_lderrno(), ldap_err2string(), ldap_result(), ldap_set_lderrno()


ldap_sasl_bind()

The ldap_sasl_bind() function authenticates your client to an LDAP server using an Simple Authentication and Security Layer (SASL) mechanism.


Note

The LDAP server must support authentication through SASL. Sun Java System Directory Server supports a server plug-in interface that you can use to add SASL support to the server. For details, see the Sun ONE Directory Server Plug-In Programming Guide (http://docs.sun.com/doc/816-6702-10).


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 parameters listed in Table 17-160.

Table 17-160   ldap_sasl_bind() Function Parameters 

Parameter

Description

ld

Pointer to an LDAP structure containing information about the connection to the LDAP server.

dn

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

Description

The ldap_sasl_bind() function authenticates your client to an LDAP server by using a specified SASL mechanism. 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(). In order to get the results of the LDAP SASL bind operation, call the ldap_result(), the ldap_parse_sasl_bind_result(), and the ldap_get_lderrno() functions.

For more details, see "Binding and Authenticating to an LDAP Server" of Chapter 3, "Writing an LDAP Client." For additional information on authenticating through SASL mechanisms, see Chapter 12, "Using SASL Authentication." For a list of possible result codes for an LDAP SASL bind operation, see ldap_sasl_bind_s().

See Also

ldap_result(), ldap_parse_sasl_bind_result(), ldap_get_lderrno(), ldap_sasl_bind_s()


ldap_sasl_bind_s()

The ldap_sasl_bind_s() function authenticates your client to an LDAP server synchronously using an SASL mechanism.


Note

The LDAP server must support authentication through SASL. Sun Java System Directory Server supports a server plug-in interface that you can use to add SASL support to the server. For details, see the Sun ONE Directory Server Plug-In Programming Guide (http://docs.sun.com/doc/816-6702-10).


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 parameters listed in Table 17-161.

Table 17-161   ldap_sasl_bind_s() Function Parameters 

Parameter

Description

ld

Pointer to an LDAP structure containing information about the connection to the LDAP server.

dn

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 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 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_alloc() function.

Returns

One of the following values:

Description

The ldap_sasl_bind_s() function authenticates your client to an LDAP server by using a specified SASL mechanism. It 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(). 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.

For more details, see "Binding and Authenticating to an LDAP Server" of Chapter 3, "Writing an LDAP Client." For additional information on authenticating through SASL mechanisms, see Chapter 12, "Using SASL Authentication."

See Also

ldap_sasl_bind()


ldap_search()

The ldap_search() function searches the directory asynchronously.


Note

This is an older function that is included in the SDK 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 parameters detailed in Table 17-162.

Table 17-162   ldap_search() Function Parameters 

Parameter

Description

ld

Pointer to an LDAP structure containing information about the connection to the LDAP server.

base

DN of the entry that serves as the starting point for the search. For example, setting base to dc=example,dc=com restricts the search to entries at example.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 "Defining a Search Filter" of Chapter 5, "Searching a LDAP Directory."

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.


Note

To check the result of this operation, call ldap_result() and ldap_result2error(). See ldap_search_ext_s() for a list of possible result codes.


Description

Please use the newer version of this function, ldap_search_ext().

Example

Code Example 17-44 searches a directory.

Code Example 17-44  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()

The ldap_search_ext() function searches the directory asynchronously.


Note

ldap_search_ext() is a new version of the ldap_search() function. If you are writing a new LDAP client, you should call ldap_search_ext().


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 parameters listed in Table 17-163.

Table 17-163   ldap_search_ext() Function Parameters 

Parameter

Description

ld

Pointer to an LDAP structure containing information about the connection to the LDAP server.

base

DN of the entry that serves as the starting point for the search. For example, setting base to dc=example,dc=com restricts the search to entries at example.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 "Defining a Search Filter" of Chapter 5, "Searching a LDAP Directory."

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 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 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. See "Setting Search Preferences" of Chapter 5, "Searching a LDAP Directory."

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.

Returns

One of the following values:

Description

The ldap_search_ext() function searches the directory for matching entries. 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(). You can also 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.) In order to get the results of the ldap_search_ext() operation, you need to call the ldap_result() and the ldap_parse_result() functions.

For more information on searching the directory, see Chapter 5, "Searching a LDAP Directory." For a list of possible result codes for an LDAP search operation, see ldap_search_ext_s().

Example

See Code Example 5-7 of Chapter 5, "Searching a LDAP Directory."

See Also

ldap_search_ext_s(), ldap_result(), ldap_parse_result()


ldap_search_ext_s()

The ldap_search_ext_s() function searches the directory synchronously.


Note

ldap_search_ext_s() is a new version of the ldap_search_s() function. If you are writing a new LDAP client, you should call ldap_search_ext_s().


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 parameters listed in Table 17-164.

Table 17-164   ldap_search_ext_s() Function Parameters 

Parameter

Description

ld

Pointer to an LDAP structure containing information about the connection to the LDAP server.

base

DN of the entry that serves as the starting point for the search. For example, setting base to dc=example,dc=com restricts the search to entries at example.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 "Defining a Search Filter" of Chapter 5, "Searching a LDAP Directory."

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 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 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. See "Setting Search Preferences" of Chapter 5, "Searching a LDAP Directory."

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:

Description

The ldap_search_ext_s() searches the directory for matching entries. 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(). You can also use ldap_search_ext_s() 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.)

For more information on searching the directory, see Chapter 5, "Searching a LDAP Directory."

Example

See Code Example 5-4 of Chapter 5, "Searching a LDAP Directory."

See Also

ldap_search_ext()


ldap_search_s()

The ldap_search_s() function searches the directory synchronously.


Note

This is an older function that is included in the SDK 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 parameters listed in Table 17-165.

Table 17-165   ldap_search_s() Function Parameters 

Parameter

Description

ld

Pointer to an LDAP structure containing information about the connection to the LDAP server.

base

DN of the entry that serves as the starting point for the search. For example, setting base to dc=example,dc=com restricts the search to entries at example.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 "Defining a Search Filter" of Chapter 5, "Searching a LDAP Directory."

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

Description

Please use the newer version of this function, ldap_search_ext_s().

Example

Code Example 17-45 searches the directory for all people whose surname (last name) is “Jensen”.

Code Example 17-45  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()

The ldap_search_st() function searches the directory synchronously within a specified time limit.


Note

This is an older function that is included in the SDK 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 parameters listed in Table 17-166.

Table 17-166   ldap_search_st() Function Parameters 

Parameter

Description

ld

Pointer to an LDAP structure containing information about the connection to the LDAP server.

base

DN of the entry that serves as the starting point for the search. For example, setting base to dc=example,dc=com restricts the search to entries at example.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 "Defining a Search Filter" of Chapter 5, "Searching a LDAP Directory."

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

Description

Please use the newer version of this function, ldap_search_ext_s().

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 parameters listed in Table 17-167.

Table 17-167   ldap_set_filter_additions() Function Parameters

Parameter

Description

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:

Example

Code Example 17-46 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 17-46  ldap_set_filter_additions() Code Example 

#include <ldap.h>

...

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


Caution

This function is deprecated and should not be used. It is included in ldap-deprecated.h for backward-compatibility. Please use ldap_set_filter_additions().


For more information, see the man page for ldap_setfilteraffixes.

See Also

ldap_set_filter_additions()


ldap_set_lderrno()

The ldap_set_lderrno() function sets an error code and information about an error in an LDAP structure.

Syntax

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

Parameters

This function has the parameters listed in Table 17-168.

Table 17-168   ldap_set_lderrno() Function Parameters 

Parameter

Description

ld

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, set this parameter to the portion of the DN that identifies an existing entry. (See "Receiving the Matching Portion of a DN" of Chapter 4, "Using the LDAP API" for details.)

s

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

Returns

One of the following values: