Mozilla LDAP SDK Programmer's Guide/LDAP C SDK Function Reference

This section contains detailed reference material for each public function of LDAP C SDK. 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.

Typographic Conventions

The general purpose of a function is usually given by its name. The following table lists the naming conventions used when adding suffixes to function names.

Function Naming Conventions

Suffix	Description
_ext	Identifies extended functions introduced for LDAP v3. These functions are augmented through additional parameters, as compared to the functions they replace. As LDAP v3 has become widely adopted, it is recommended you use extended functions whenever possible in your new applications.
_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.

Function Summary by Task

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

Working with Basic Encoding Rules

The functions listed in the following table may be used to encode and decode with Basic Encoding Rules (BER). They are often used inside of control and extension values.

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 the following table manage the different phases of an LDAP session: initialization, configuration, authentication (binding) and termination (unbinding).

Functions to Manage an LDAP Session

Function	Description
ldap_init(), prldap_init() (IPv6)	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 an extension to the API.
ldap_unbind_ext()	Ends an LDAP session and frees the associated data structures.

Performing LDAP Operations

The functions listed in the following table perform LDAP operations on a server and retrieve the results.

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() orldap_rename_s()	Renames or moves one or more entries.
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 LDAP v3 extended operation.
ldap_parse_extended_result()	Parses the results of an LDAP v3 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 the following table retrieve the results of a search operation and process the data structures which are returned.

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 the following table are used to access the contents of an entry returned as a search result.

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 the following table, your LDAP client can sort the data structures returned as search results.

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

Directory Server and others also provide server-side sorting through LDAP v3 controls.

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 the following table retrieve and build filters using a filter configuration file. Use this mechanism to create complex filters to pass to the search functions.

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 LDAP v3 Controls

Directory Server and others also provide additional functionality through LDAP v3 controls. The functions listed in the following table configure LDAP v3 control structures which ask the server to perform advanced operations.

Functions to Manage LDAP v3 Controls

Function	Description
ldap_create_authzid_control(), ldap_parse_authzid_control()	Examine the authorization ID used for the operation.
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_proxiedauth_control()	Define a proxy authorization control to perform an operation under a different bind DN
ldap_create_pwdpolicy_control(), ldap_parse_pwdpolicy_control()	Examine password policy information for an entry.
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_userstatus_control(), ldap_parse_userstatus_control()	Examine account availability information for an entry.
ldap_create_virtuallist_control(), ldap_parse_virtuallist_control()	Use in conjunction with server-side sorting to limit and handle the number of results returned to the client.
ldap_parse_result()	Parse an LDAP response from the server to extract the result and the response to the control.

Using Extensions

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

Extensions Provided

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 the following table interpret LDAP URLs, universal resource locators of the form ldap://... .

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 the following table work with strings and characters that use UTF-8 encoding.

Functions to Handle UTF-8 Encoding

Function	Description
ldap_utf8len()	Function to determine byte 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 the following table handle errors returned by the functions. See LDAP C SDK Result Codes for a list of all of the error and status codes used in the LDAP C SDK. You can also find details about possible errors in the reference section for each function.

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 the following table free memory allocated by the LDAP C SDK functions.

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 the following table.

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 NSPR

The functions listed in the following table tie libldap into Netscape Portable Runtime, NSPR.

Functions to Work with NSPR

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 the following table should no longer be used; they have been superseded by the newer functions listed in the second column. Deprecated functions are those being dropped from the standard or from extensions to LDAP C SDK. Outdated functions are those which are not officially deprecated but which have newer, extended functions for performing the same operation.

Deprecated Functions and Their Replacements

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 ldap_create_geteffectiveRights_control().
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 LDAP v2 functions are outdated now that LDAP v3 has been widely adopted. The following table lists both the outdated function and its new equivalent. Although LDAP v2 functions remain in the standard specification, you should use the LDAP v3 functions in any new client applications. Again, for maintenance reasons, the outdated functions have often been implemented to call the newer function.

Outdated LDAP v2 Functions and New Equivalents

LDAP v2 Functions	LDAP v3 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

This section lists the functions in alphabetical order.

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

• If successful, a pointer to the newly allocated BerElement structure.
• If unsuccessful, a NULL pointer.

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

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

• If successful, a pointer to the newly allocated BerElement structure.
• If unsuccessful, a NULL pointer.

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

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

ber_bvdup() Function Parameter

Parameter	Description
bv	Pointer to the berval structure to be duplicated.

Returns

• If successful, a pointer to the newly allocated berval structure.
• If unsuccessful, a NULL pointer.

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

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

ber_dup() Function Parameter

Parameter	Description
ber	Pointer to the BerElement to be duplicated.

Returns

• If successful, a pointer to the newly allocated BerElement structure.
• If unsuccessful, a NULL pointer.

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

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

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 LDAP v3 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

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

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

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

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

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

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.

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

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

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

ber_init() Function Parameter

Parameter	Description
bv	Pointer to a berval.

Returns

• If successful, returns a new BerElement containing a copy of the data in the bv argument.
• If not, returns a NULL pointer.

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

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

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

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

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

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

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

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.

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

Parameters

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:

• LDAP_SUCCESS if successful.
• -1 if unsuccessful.

Note: The appropriate LDAP error code is also set in the LDAP structure. You can retrieve the error code by calling ldap_get_lderrno(). Some possible codes are:

• LDAP_PARAM_ERROR if any of the arguments are invalid.
• LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request.
• LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.
• LDAP_NO_MEMORY if memory cannot be allocated.

Description

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

Example

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

LDAP *ld;
char *url = "ldap://ldap.example.com/c=US?o,description?one?o=sales";
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.

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

Parameters

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:

• LDAP_SUCCESS if successful.
• LDAP_PARAM_ERROR if any of the arguments are invalid.
• LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request.
• LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.
• LDAP_NO_MEMORY if memory cannot be allocated.

Description

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

Example

the following example cancels an ldap_url_search() operation, abandoning the results of the operation. Using ldap_abandon_ext()

LDAP *ld;
char *url = "ldap://ldap.example.com/c=US?o,description?one?o=sales";
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

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. Please use the newer version of this function, ldap_add_ext() .

Example

the following example adds a new entry to the directory. Using ldap_add()

#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

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:

• LDAP_SUCCESS if successful.
• LDAP_PARAM_ERROR if any of the arguments are invalid.
• LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request.
• LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.
• LDAP_NO_MEMORY if memory cannot be allocated.
• LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function.

Description

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

To add a new entry to the directory, you need to specify:

• A unique DN identifying the new entry.
  Use the dn argument to specify the DN of the new entry. The parents of the entry should already exist. For example, if you are adding the entry uid=bjensen,ou=People,dc=example,dc=com , the entries ou=People and dc=example,dc=com must already exist in the directory.
• A set of attributes for the new entry.
  Create an LDAPMod structure for each attribute. Set the mod_op field to 0 if the attribute values are string values. To specify values that consist of binary data (such as a sound file or a JPEG file), set the mod_op field to LDAP_MOD_BVALUES. Create an array of these LDAPMod structures and pass the array as the attrs argument. ldap_add_ext() is an asynchronous function; it does not directly return results. 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.

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.

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

Parameters

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:

• LDAP_SUCCESS if successful.
• LDAP_PARAM_ERROR if any of the arguments are invalid.
• LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request.
• LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.
• LDAP_NO_MEMORY if memory cannot be allocated.
• LDAP_LOCAL_ERROR if an error occurred when receiving the results from the server.
• LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded results from the server.
• LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function.

Note: Directory Server and other LDAP server products may send result codes in addition to those described. For example, the server may have loaded a plug-in that returns custom result codes. Check your LDAP server documentation for other result codes.

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:

• A unique DN identifying the new entry.
  Use the dn argument to specify the DN of the new entry. The parents of the entry should already exist. For example, if you are adding the entry uid=bjensen,ou=People,dc=example,dc=com , the entries ou=People and dc=example,dc=com must already exist in the directory.
• A set of attributes for the new entry.
  Create an LDAPMod structure for each attribute. Set the mod_op field to 0 if the attribute values are string values. To specify values that consist of binary data (such as a sound file or a JPEG file), set the mod_op field to LDAP_MOD_BVALUES. Create an array of these LDAPMod structures and pass the array as the attrs argument. ldap_add_ext_s() is a synchronous function; 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().

See Also

ldap_add_ext(), LDAPMod

ldap_add_s()

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

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

Parameters

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

The following example adds a new entry to the directory.

#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

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

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

Parameters

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

See Also

ldap_open(), ldap_init(), prldap_init() (IPv6), ldap_bind_s()

ldap_bind_s()

Note: This function is deprecated and should not be used. It is included in ldap-deprecated.h for backward-compatibility. Use ldap_simple_bind_s() instead.

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

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

See Also

ldap_open(), ldap_init(), prldap_init() (IPv6), ldap_bind()

ldap_build_filter()

See also ldap_create_filter().

ldap_cache_flush()

Note: This function is deprecated and should not be used. It is included in ldap-deprecated.h for backward-compatibility. Use the ldap_memcache_* functions instead.

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

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

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

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

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

Parameters

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

the following example checks to see if Barbara Jensen has the email address bjensen@example.com.

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

#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

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:

• LDAP_SUCCESS if successful.
• LDAP_PARAM_ERROR if any of the arguments are invalid.
• LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request.
• LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.
• LDAP_NO_MEMORY if memory cannot be allocated.
• LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function.

Note: To check the result of this operation, call ldap_result() and ldap_parse_result().

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

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

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:

• LDAP_COMPARE_TRUE if the entry contains the attribute value.
• LDAP_COMPARE_FALSE if the entry does not contain the attribute value.
• LDAP_PARAM_ERROR if any of the arguments are invalid.
• LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request.
• LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.
• LDAP_NO_MEMORY if memory cannot be allocated.
• LDAP_LOCAL_ERROR if an error occurred when receiving the results from the server.
• LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded results from the server.
• LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function.

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

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

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

The following example checks to see if Barbara Jensen has the email address bjensen@example.com.

#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

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

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

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:

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

• -1 if ld is not a valid connection handle.

Description

The ldap_count_entries() function returns the number of LDAPMessage structures representing directory entries in a chain of search results. These messages have the type LDAP_RES_SEARCH_ENTRY .

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

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:

• The number of LDAPMessage structures in a chain of search results, if successful. If there are no structures, returns 0.
• -1 if ld is not a valid connection handle.

Description

The ldap_count_messages() function returns the number of LDAPMessage structures in a chain of search results. 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.

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

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:

• The number of LDAPMessage structures of the type LDAP_RES_SEARCH_REFERENCE in a chain of search results, if successful. (If there are no structures of this type, returns 0.)
• -1 if ld is not a valid connection handle.

Description

The ldap_count_references() function returns the number of LDAPMessage structures representing search references in a chain of search results. These messages have the type LDAP_RES_SEARCH_REFERENCE, continuation references as specified in LDAPv3 that are stored as referral entries. Like a referral, each continuation reference itself may contain a number of URLs assumed to be equivalent, and the client should use one of those URLs.

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

ldap_count_values() Function Parameter

Parameter	Description
values	Array of values.

Returns

One of the following values:

• The number of values in the array, if successful.
• -1 if unsuccessful.

Example

The following example counts the number of values assigned to an attribute.

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

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

Parameters

ldap_count_values_len() Function Parameter

Parameter	Description
values	Array of berval structures.

Returns

One of the following values:

• The number of values in the array, if successful.
• -1 if unsuccessful.

Example

The following example counts the number of values assigned to an attribute.

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

The ldap_create_authzid_control() function creates a control that requests the authorization ID for a bind operation. This is defined in RFC 3829.

Note: In order for the control to work, the LDAP server that you are connecting to must support the server controls for authorization bind identity (OID 2.16.840.1.113730.3.4.16 or LDAP_CONTROL_AUTHZID_REQ, and OID 2.16.840.1.113730.3.4.15 or LDAP_CONTROL_AUTHZID_RES).

Calling ldap_create_authzid_control() creates an LDAP control that you can pass to the ldap_simple_bind() function to retrieve the authorization ID in the response. You call ldap_parse_authzid_control() function on the controls returned with an entry to retrieve a char * containing the authorization ID. When you are done with the search, you should free the control by calling the ldap_control_free() function.

Syntax

#include <ldap.h>
LDAP_API(int) LDAP_CALL ldap_create_authzid_control( LDAP *ld,
  const char ctl_iscritical, LDAPControl **ctrlp );

Parameters

ldap_create_authzid_control() Function Parameters

Parameter	Description
ld	Pointer to an LDAP structure containing information about the connection to the LDAP 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 returns 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:

• LDAP_SUCCESS if successful.
• LDAP_PARAM_ERROR if an invalid parameter was passed to the function.
• LDAP_NO_MEMORY if memory cannot be allocated.
• LDAP_ENCODING_ERROR if an error occurred when BER-encoding the control.

See Also

ldap_parse_authzid_control()

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

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:

• LDAP_SUCCESS if successful.
• LDAP_SIZELIMIT_EXCEEDED if the created filter exceeds the size of the buffer.
• LDAP_PARAM_ERROR if an invalid parameter was passed to the function.

Example

The following example builds the filter (mail=bjensen@example.com).

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

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

Syntax

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

Parameters

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	List of attributes to return, such as aclRights and aclRightsInfo.
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().

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.

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

Parameters

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:

• LDAP_SUCCESS if successful.
• LDAP_PARAM_ERROR if an invalid parameter was passed to the function.
• LDAP_NO_MEMORY if memory cannot be allocated.
• LDAP_ENCODING_ERROR if an error occurred

when BER-encoding the control.

Description

The ldap_create_persistentsearch_control() function allows you to perform persistent searches. A persistent search provides the means to track changes to a set of entries that match the search criteria. After the initial search is performed, the server keeps track of the search criteria and sends back information when any entry that matches the criteria is added, deleted, modified, or renamed. Calling 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_passwordpolicy_control()

The ldap_create_passwordpolicy_control() function creates a control that requests information about the status of a user account.

Note: ldap_create_passwordpolicy_control() implements an extension to the LDAP v3 supported by Directory Server. In order for the control to work, the LDAP server that you are connecting to must support the server control for password policy (OID 1.3.6.1.4.1.42.2.27.8.5.1, or LDAP_CONTROL_PASSWD_POLICY).

Calling ldap_create_passwordpolicy_control() creates an LDAP control that you can pass to the ldap_simple_bind() functions to retrieve password policy information from bind, modify, add, compare, and potentially extended operation responses including password policy response controls. You call ldap_parse_passwordpolicy_control() function on the controls returned with an entry to retrieve a LDAPPasswordPolicyError structure containing information about the status of the account. When you are done with the search, you should free the control by calling the ldap_control_free() function.

Syntax

#include <ldap.h>
LDAP_API(int) LDAP_CALL ldap_create_passwordpolicy_control( LDAP *ld,
  LDAPControl **ctrlp );

Parameters

ldap_create_passwordpolicy_control() Function Parameters

Parameter	Description
ld	Pointer to an LDAP structure containing information about the connection to the LDAP server.
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:

• LDAP_SUCCESS if successful.
• LDAP_PARAM_ERROR if an invalid parameter was passed to the function.
• LDAP_NO_MEMORY if memory cannot be allocated.
• LDAP_ENCODING_ERROR if an error occurred when BER-encoding the control.

See Also

ldap_parse_passwordpolicy_control(), LDAPPasswordPolicyError

ldap_create_passwordpolicy_control_ext()

The ldap_create_passwordpolicy_control_ext() function creates a control that requests information about the status of a user account.

Note: ldap_create_passwordpolicy_control_ext() implements an extension to the LDAP v3 supported by Directory Server. In order for the control to work, the LDAP server that you are connecting to must support the server control for password policy (OID 1.3.6.1.4.1.42.2.27.8.5.1, or LDAP_CONTROL_PASSWD_POLICY).

Calling ldap_create_passwordpolicy_control_ext() creates an LDAP control that you can pass to the ldap_simple_bind() functions to retrieve password policy information from bind, modify, add, compare, and potentially extended operation responses including password policy response controls. You call ldap_parse_passwordpolicy_control() function on the controls returned with an entry to retrieve a LDAPPasswordPolicyError structure containing information about the status of the account. When you are done with the search, you should free the control by calling the ldap_control_free() function.

Syntax

#include <ldap.h>
LDAP_API(int) LDAP_CALL ldap_create_passwordpolicy_control_ext( LDAP *ld,
  const char ctl_iscritical, LDAPControl **ctrlp );

Parameters

ldap_create_passwordpolicy_control_ext() Function Parameters

Parameter	Description
ld	Pointer to an LDAP structure containing information about the connection to the LDAP 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 returns 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:

• LDAP_SUCCESS if successful.
• LDAP_PARAM_ERROR if an invalid parameter was passed to the function.
• LDAP_NO_MEMORY if memory cannot be allocated.
• LDAP_ENCODING_ERROR if an error occurred when BER-encoding the control.

See Also

ldap_parse_passwordpolicy_control(), LDAPPasswordPolicyError

ldap_create_proxiedauth_control()

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

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

Parameters

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) from RFC 4513: ; 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 ; syntax from RFC 4514 ; 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).

ldap_create_proxyauth_control()

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

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

Parameters

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:

• LDAP_SUCCESS if successful.
• LDAP_PARAM_ERROR if an invalid parameter was passed to the function.
• LDAP_NO_MEMORY if memory cannot be allocated.
• LDAP_ENCODING_ERROR if an error occurred when BER-encoding the control.
• LDAP_UNAVAILABLE_CRITICAL_EXTENSION if the server does not support proxy authorization and ctl_iscritical is set to a non-zero value.

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 LDAP v3. 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 LDAP v3 extension.

Syntax

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

Parameters

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:

• LDAP_SUCCESS if successful.
• LDAP_PARAM_ERROR if an invalid parameter was passed to the function.
• LDAP_NO_MEMORY if memory cannot be allocated.
• LDAP_ENCODING_ERROR if an error occurred when BER-encoding the control.

Description

The ldap_create_sort_control() function allows you to specify the order in which you want to receive data from the server. Calling this function creates an LDAP control that you can pass to the ldap_search_ext() and ldap_search_ext_s() functions.

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

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: cn (sorts by the cn attribute) -cn (sorts by the cn attribute in reverse order) -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:

• LDAP_SUCCESS if successful.
• LDAP_PARAM_ERROR if an invalid parameter was passed to the function.
• LDAP_NO_MEMORY if memory cannot be allocated.
• -1 if an error occurred.

Description

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.

See Also

ldap_create_sort_control(), ldap_free_sort_keylist()

ldap_create_userstatus_control()

The ldap_create_userstatus_control() function creates a control that requests information about the status of a user account.

Note: ldap_create_userstatus_control() implements an extension to the LDAP v3 supported by Directory Server. In order for the control to work, the LDAP server that you are connecting to must support the server control for account availability (OID 1.3.6.1.4.1.42.2.27.9.5.8, or LDAP_CONTROL_ACCOUNT_USABLE).

Calling ldap_create_userstatus_control() creates an LDAP control that you can pass to the ldap_search_ext() and ldap_search_ext_s() functions. You call ldap_parse_userstatus_control() function on the controls returned with an entry to retrieve a LDAPuserstatus structure containing information about the status of the account. When you are done with the search, you should free the control by calling the ldap_control_free() function.

Syntax

#include <ldap.h>
LDAP_API(int) LDAP_CALL ldap_create_userstatus_control( LDAP *ld,
  const char ctl_iscritical, LDAPControl **ctrlp );

Parameters

ldap_create_userstatus_control() Function Parameters

Parameter	Description
ld	Pointer to an LDAP structure containing information about the connection to the LDAP 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 returns 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:

• LDAP_SUCCESS if successful.
• LDAP_PARAM_ERROR if an invalid parameter was passed to the function.
• LDAP_NO_MEMORY if memory cannot be allocated.
• LDAP_ENCODING_ERROR if an error occurred when BER-encoding the control.

See Also

ldap_parse_userstatus_control(), LDAPuserstatus()

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.

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

Parameters

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:

• LDAP_SUCCESS if successful.
• LDAP_PARAM_ERROR if an invalid parameter was passed to the function.
• LDAP_NO_MEMORY if memory cannot be allocated.
• LDAP_ENCODING_ERROR if an error occurred when BER-encoding the control.

Description

The ldap_create_virtuallist_control() function allows you to retrieve a subset of entries from the server for use in a virtual list box. 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).

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.

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.

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

Parameters

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

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

The following example uses the asynchronous ldap_delete() function to remove the entry for Barbara Jensen from the directory.

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

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

Parameters

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:

• LDAP_SUCCESS if successful.
• LDAP_PARAM_ERROR if an invalid parameter was passed to the function.
• LDAP_NO_MEMORY if memory cannot be allocated.
• LDAP_ENCODING_ERROR if an error occurred when BER-encoding the control.
• LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.
• LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function.

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

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

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.

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

Parameters

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:

• LDAP_SUCCESS if successful.
• LDAP_PARAM_ERROR if an invalid parameter was passed to the function.
• LDAP_NO_MEMORY if memory cannot be allocated.
• LDAP_ENCODING_ERROR if an error occurred when BER-encoding the control.
• LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.
• LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function.
• LDAP_LOCAL_ERROR if an error occurred when receiving the results from the server.
• LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded results from the server.

Note: Directory Server and other LDAP server products may send result codes in addition to those described. For example, the server may have loaded a plug-in that returns custom result codes. Check your LDAP server documentation for other result codes.

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.

See Also

ldap_delete_ext()

ldap_delete_s()

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

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

Parameters

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

The following example uses the synchronous ldap_delete_s() function to delete the entry for Barbara Jensen from the directory.

#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

ldap_dn2ufn() Function Parameter

Parameter	Description
dn	The DN that you want converted.

Returns

One of the following values:

• If successful, returns the DN in its friendlier form.
• If unsuccessful, returns NULL.

Description

For more information on user friendly naming (UFN), see RFC 1781,<citetitle> Using the OSI Directory to Achieve User Friendly Naming </citetitle> (<ulink url="http://www.faqs.org/rfcs/rfc1781.html" type="text_url"></ulink>).

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

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

• LDAP_SUCCESS if successful.
• An LDAP error code on error.

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

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

• LDAP_SUCCESS if successful.
• An LDAP error code on error.

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

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

• LDAP_SUCCESS if successful.
• An LDAP error code on error.

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

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

• LDAP_SUCCESS if successful.
• An LDAP error code on error.

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

ldap_err2string() Function Parameter

Parameter	Description
err	Error code that you want interpreted into an error message.

Returns

One of the following values:

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

Example

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

#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

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:

• If successful, returns a NULL terminated array containing the components of the DN.
• If unsuccessful, returns NULL.

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

Note: 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 ldap.example.com will return { "ldap", "example", "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

ldap_explode_dns() Function Parameter

Parameter	Description
dn	DN that you want separated into components.

Returns

One of the following values:

• If successful, returns a NULL terminated array containing the components of the DN.
• If unsuccessful, returns NULL.

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

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:

• If successful, returns a NULL terminated array containing the components of the RDN.
• If unsuccessful, returns NULL.

Example

The following function call:

ldap_explode_rdn( "ou=Sales + cn=Barbara Jensen", 0 );

returns this array:

{ "ou=Sales", "cn=Barbara Jensen", NULL }

See Also

ldap_explode_dn(), ldap_get_dn

ldap_extended_operation()

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

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 LDAP v3 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 data type, usually obtained 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:

• LDAP_SUCCESS if successful.
• LDAP_PARAM_ERROR if an invalid parameter was passed to the function.
• LDAP_NO_MEMORY if memory cannot be allocated.
• LDAP_ENCODING_ERROR if an error occurred when BER-encoding the control.
• LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.
• LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function.

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

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

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 data type, usually obtained 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:

• LDAP_SUCCESS if successful.
• LDAP_PARAM_ERROR if an invalid parameter was passed to the function.
• LDAP_NO_MEMORY if memory cannot be allocated.
• LDAP_ENCODING_ERROR if an error occurred when BER-encoding the control.
• LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.
• LDAP_LOCAL_ERROR if an error occurred when receiving the results from the server.
• LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded results from the server.
• LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function.

Note: Directory Server and other LDAP server products may send result codes in addition to those described. For example, the server may have loaded a plug-in that returns custom result codes. Check your LDAP server documentation for other result codes.

Description

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

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:

• If successful, returns the pointer to the name of the first attribute in an entry. When you are done using this data, you should free the memory by calling the ldap_memfree() function.
• If unsuccessful, returns a NULL and sets the appropriate error code in the LDAP structure. To get the error code, call the ldap_get_lderrno() function.

Example

The following example retrieves each attribute for an entry.

#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

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

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:

• If successful, returns the pointer to the first LDAPMessage structure of the type LDAP_RES_SEARCH_ENTRY in the chain of search results.
• If no LDAPMessage structure of the type LDAP_RES_SEARCH_ENTRY are in the chain of the search results or if the function is unsuccessful, returns a NULLMSG.

Description

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

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

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:

• If successful, returns the pointer to the first LDAPMessage structure in the chain of search results.
• If no LDAPMessage structures are in the chain or if the function is unsuccessful, returns a NULLMSG.

Description

The ldap_first_message() function returns a pointer to the first LDAPMessage structure in a chain of search results. You can use this function in conjunction with the ldap_next_message() function to iterate through the chain of search results. You can 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. 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.

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

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:

• If successful, returns the pointer to the first LDAPMessage structure of the type LDAP_RES_SEARCH_REFERENCE in the chain of search results.
• If no LDAPMessage structures of the type LDAP_RES_SEARCH_REFERENCE are in the chain of the search results or if the function is unsuccessful, returns a NULLMSG.

Description

The ldap_first_reference() function returns a pointer to the LDAPMessage structure representing the first search reference in a chain of search results. Search references are in messages of the type LDAP_RES_SEARCH_REFERENCE, continuation references as specified in LDAPv3 that are stored as referral entries. Like a referral, each continuation reference itself may contain a number of URLs assumed to be equivalent, and the client should use one of those URLs. You can use this function in conjunction with the ldap_next_reference function to iterate through the search references in a chain of search results. These functions skip over any messages in the chain that do not have the type LDAP_RES_SEARCH_REFERENCE. Do not free the LDAPMessage structure returned by this function. Because this is a structure within a chain of search results, freeing this structure will free part of the chain of search results. When you are done working with the search results, you can free the chain itself, rather than individual structures within the chain.

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

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

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

• If successful, a pointer to an ldap_tmplitem structure.
• A NULL pointer on error.

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

ldap_first_tmplrow() Function Parameter

Parameter	Description
tmpl	The name of the template to be retrieved.

Returns

• If successful, a pointer to an ldap_tmplitem structure.
• A NULL pointer on error.

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

ldap_free_friendlymap() Function Parameter

Parameter	Description
map	Pointer to the FriendlyMap() mapping structure in memory.

Example

The following example frees memory allocated by the ldap_friendly_name() function.

#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

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

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

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

ldap_free_urldesc() Function Parameter

Parameter	Description
ludp	Pointer to a LDAPURLDesc structure.

Example

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

#include <stdio.h>
#include <ldap.h>
...
char *my_url =
"ldap://ldap.example.com:1389/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 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

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:

• If successful, returns the user-friendly name for the specified identifier.
• If unsuccessful‚Äö√Ñ√Æfor example, if the file cannot be read, if the file is in a bad format, or if the map parameter is set to NULL‚Äö√Ñ√Æreturns the original identifier (the value passed as the uname parameter).

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

The following example reads in a map of user-friendly names and prints the name corresponding to the standard identifier IS.

#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

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:

• If successful, returns the DN for the specified entry.
• If unsuccessful, returns a NULL and sets the appropriate error code in the LDAP structure. To get the error code, call the ldap_get_lderrno() function.

Description

You can get an entry from a chain of search results by calling the ldap_first_entry() and ldap_next_entry() functions.

Example

The following example prints the DN for each entry found in a search.

#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

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 LDAP v3 server controls returned by the server.

Returns

One of the following values:

• LDAP_SUCCESS if successful.
• LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded results from the server.
• LDAP_PARAM_ERROR if an invalid parameter was passed to the function.
• LDAP_NO_MEMORY if memory cannot be allocated.

Description

The ldap_get_entry_controls() function retrieves the LDAP v3 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

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.

Example

The following example frees the LDAPFiltDesc structure from memory after all searches are completed.

#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

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:

• If successful, returns a pointer to an LDAPFiltInfo() structure.
• If no more filters can be returned, returns a NULL.
• If unsuccessful, returns a NULL.

Example

The following example is based on the getfilt command-line program example provided with the LDAP C SDK. The program prompts the user to enter search criteria and, based on the criteria entered, it retrieves filters that match the criteria.

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

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

Parameters

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:

• If successful, returns a NULL terminated array of the attribute‚Äö√Ñ√¥s values.
• If unsuccessful or if no such attribute exists in the entry, returns a NULL and sets the appropriate error code in the LDAP structure. To get the error code, call the ldap_get_lderrno() function.

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

Note: 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

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:

• If successful, returns a NULL terminated array of pointers to berval structures, which, in turn, contain pointers to the attribute‚Äö√Ñ√¥s binary values.
• If unsuccessful or if no such attribute exists in the entry, returns a NULL and sets the appropriate error code in the LDAP structure. To get the error code, call the ldap_get_lderrno() function.

Description

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

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

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.
s	The text of the error message.

Returns

The LDAP error code for the last operation.

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

Example

The following example 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.

#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 );
}
...

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

ldap_getnextfilter() Function Parameter

Parameter	Description
lfdp	Pointer to an LDAPFiltDesc structure.

Returns

One of the following values:

• If successful, returns a pointer to an LDAPFiltInfo() structure.
• If no more filters can be returned, returns a NULL.
• If unsuccessful, returns a NULL.

Description

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

Example

See the following example.

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

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.
optdata	Pointer to the buffer in which the value of the option will be put.

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

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 LDAP v3 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. 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 LDAP v3 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. You handle failover with 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 LDAP v3 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. 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 time out (expressed in milliseconds) for non-blocking connect call. The data type for the optdata parameter is (int *).
LDAP_X_OPT_SOCKBUF	Socket buffer structure associated to the LDAP connection.

See also ldap_get_option() for details on LDAP_OPT_X_SASL* parameters.

Returns

One of the following values:

• LDAP_SUCCESS if successful.
• -1 if unsuccessful.

Examples

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

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

This example could also include the following two small sections of code that show how to use the LDAP_OPT_API_FEATURE_INFO and the LDAP_OPT_API_INFO options, respectively.

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(), prldap_init() (IPv6), 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

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:

• If successful, returns a NULL terminated array of the attribute‚Äö√Ñ√¥s values.
• If unsuccessful or if no such attribute exists in the entry, returns a NULL and sets the appropriate error code in the LDAP structure. To get the error code, call the ldap_get_lderrno() function.

Description

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

Example

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

#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

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:

• If successful, returns a NULL terminated array of pointers to berval structures, which in turn contains pointers to the attribute‚Äö√Ñ√¥s binary values.
• If unsuccessful or if no such attribute exists in the entry, returns NULL and sets the appropriate error code in the LDAP structure. To get the error code, call the ldap_get_lderrno() function.

Description

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

Example

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

#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

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:

• If successful, returns a pointer to an LDAP() structure.
• If unsuccessful, returns a NULL.

Description

The ldap_init() function initializes a session with an LDAP server 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 LDAP v2. It is highly recommended to set it to LDAP v3 using the ldap_set_option().

...
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 the following example 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 1389.

...
LDAP *ld
...
ld = ldap_init( "ld1.example.com ld2.example.com:1389", LDAP_PORT );

Note: If you are connecting to a secure LDAP server over SSL, you should be calling the ldapssl_init() function.

Example

The following example initializes a session with the LDAP server at ldap.example.com:389, and sets a session preference that identifies the client as an LDAP v3 client.

#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 */
/* Use prldap_init() for IPv6 support. */
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

prldap_init() (IPv6), 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.

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

Parameters

ldap_init_getfilter() Function Parameter

Parameter	Description
fname	Name of the LDAP filter configuration file to use.

Returns

One of the following values:

• If successful, returns a pointer to an LDAPFiltDesc() structure.
• If unsuccessful (for example, if there is an error reading

the file), returns a NULL.

Example

The following example loads a filter configuration file named myfilters.conf into memory.

#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

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:

• If successful, returns a pointer to an LDAPFiltDesc() structure.
• If unsuccessful‚Äö√Ñ√Æfor example, if there is an error reading the file‚Äö√Ñ√Æreturns a NULL.

Example

The following example 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"

Using ldap_init_getfilter()

#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

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:

• LDAP_SEARCHPREF_ERR_VERSION.
• LDAP_SEARCHPREF_ERR_MEM if there is a memory allocation problem.
• Upon success, 0 is returned and solistp is set to point to a list of search preference data structures.

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

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:

• LDAP_SEARCHPREF_ERR_VERSION if buf points to data that is newer than can be handled.
• LDAP_SEARCHPREF_ERR_MEM if there is a memory allocation problem.
• Upon success, 0 is returned and solistp is set to point to a list of search preference data structures.

Description

ldap_init_searchprefs_buf() reads a sequence of search preference configurations from buf. 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

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

• If successful, 0 is returned and tmpllistp is configured.
• Upon error:
  • LDAP_TMPL_ERR_VERSION if buf points to data that is newer than can be handled.
  • LDAP_TMPL_ERR_MEM if there is a memory allocation problem.
  • LDAP_TMPL_ERR_SYNTAX if there is a problem with the format of the templates buffer or file.
  • LDAP_TMPL_ERR_FILE if the file cannot be read.

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

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

If successful, 0 is returned and tmpllistp is configured. Upon error:

• LDAP_TMPL_ERR_VERSION if buf points to data that is newer than can be handled.
• LDAP_TMPL_ERR_MEM if there is a memory allocation problem.
• LDAP_TMPL_ERR_SYNTAX if there is a problem with the format of the templates buffer or file.
• LDAP_TMPL_ERR_FILE if the file cannot be read.

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

Note: 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 email address) or the RFC 1779 formatted DN.

Description

This function is specific to LDAP v2 and should not be used when dealing with LDAP v3 servers or data.

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

ldap_is_ldap_url() Function Parameter

Parameter	Description
url	The URL that you want to check.

Returns

One of the following values:

• 1 if the URL is an LDAP URL.
• 0 if the URL is not an LDAP URL.

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

Example

The following example determines if a URL is a LDAP URL.

#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

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

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

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

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:

• LDAP_SUCCESS if the cache for the specified connection handle was retrieved successfully.
• LDAP_PARAM_ERROR if an invalid parameter was passed to the function.

Description

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

See Also

ldap_memcache_set()

ldap_memcache_init()

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

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:

• LDAP_SUCCESS if the cache for the specified connection handle was retrieved successfully.
• LDAP_PARAM_ERROR if an invalid parameter was passed to the function.
• LDAP_NO_MEMORY if memory cannot be allocated.
• LDAP_SIZELIMIT_EXCEEDED if the initial size of the cache (specified by the size argument) is too small.

Description

The ldap_memcache_init() function creates an in-memory, client-side cache that you can use to cache search requests. The function passes back a pointer to an LDAPMemCache structure, which represents the cache. You should call the ldap_memcache_set() function to associate this cache with an LDAP connection handle (an LDAP structure). 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.

Note: On Windows systems, 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 C SDK.

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

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:

• LDAP_SUCCESS if the cache for the specified connection handle was retrieved successfully.
• LDAP_PARAM_ERROR if an invalid parameter was passed to the function.
• LDAP_SIZELIMIT_EXCEEDED if the initial size of the cache (specified by the size argument) is too small.

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

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.

Note: 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

ldap_memfree() Function Parameter

Parameter	Description
p	Pointer to memory used by the LDAP library.

Example

the following example frees the memory allocated by the ldap_get_dn() function. Using ldap_memfree()

#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. */
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.

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

Parameters

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

The following example uses the asynchronous ldap_modify() function to modify the entry for Barbara Jensen in the directory. It makes the following changes to the entry:

• Adds the homePhone attribute.
• Changes the telephoneNumber attribute.
• Removes the facsimileTelephoneNumber attribute.

#include <ldap.h>
...
LDAP *ld;
LDAPMod *list_of_attrs[4];
LDAPMod attribute1, attribute2, attribute3;
LDAPMessage *result;
int msgid, rc;
struct timeval tv;
/* Distinguished name of the entry that you want to modify. */
char *dn = "uid=bjensen,ou=People,dc=example,dc=com";
/* Values to add or change */
char *homePhone_values[] = { "555-1212", NULL };
char *telephoneNumber_values[] = { "869-5309", NULL };
...
/* Specify each change in separate LDAPMod structures */
attribute1.mod_type = "homePhone";
attribute1.mod_op = LDAP_MOD_ADD;
attribute1.mod_values = homePhone_values;
attribute2.mod_type = "telephoneNumber";
attribute2.mod_op = LDAP_MOD_REPLACE;
attribute2.mod_values = telephoneNumber_values;
attribute3.mod_type = "facsimileTelephoneNumber";
attribute3.mod_op = LDAP_MOD_DELETE;
attribute3.mod_values = NULL;
/* NOTE: When removing entire attributes, you need to specify a NULL value
* for the mod_values field. */
/* Add the pointers to these LDAPMod structures to an array */
list_of_attrs[0] = &attribute1;
list_of_attrs[1] = &attribute2;
list_of_attrs[2] = &attribute3;
list_of_attrs[3] = NULL;
...
/* Set up the timeout period to wait for the "modify" operation */
tv.tv_sec = tv.tv_usec = 0;
/* Change the entry */
if ( ( msgid = ldap_modify( ld, dn, list_of_attrs ) ) == -1 ) {
  ldap_perror( ld, "ldap_modify" );
  return( 1 );
}
/* Check to see if the operation has completed */
while ( ( rc = ldap_result( ld, msgid, 0, &tv, &result ) ) == 0 ) {
  ...
  /* do other work while waiting for the operation to complete */
  ...
}
/* Check the result to see if any errors occurred */
ldap_result2error( ld, result, 1 );
ldap_perror( ld, "ldap_modify" );
...

See Also

ldap_modify_ext()

ldap_modify_ext()

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

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:

• LDAP_SUCCESS if successful.
• LDAP_PARAM_ERROR if an invalid parameter was passed to the function.
• LDAP_ENCODING_ERROR if an error occurred when BER-encoding the control.
• LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.
• LDAP_NO_MEMORY if memory cannot be allocated.
• LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function.

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:

• A unique DN identifying the new entry

Use the dn argument to specify the DN of the entry you want to modify.

• A set of attributes for the new entry

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

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.

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

Parameters

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:

• LDAP_SUCCESS if successful.
• LDAP_PARAM_ERROR if an invalid parameter was passed to the function.
• LDAP_ENCODING_ERROR if an error occurred when BER-encoding the control.
• LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.
• LDAP_NO_MEMORY if memory cannot be allocated.
• LDAP_LOCAL_ERROR if an error occurred when receiving the results from the server.
• LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded results from the server.
• LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function.

Note: Directory Server and other LDAP server products may send result codes in addition to those described. For example, the server may have loaded a plug-in that returns custom result codes. Check your LDAP server documentation for other result codes.

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:

• A unique DN identifying the new entry

Use the dn argument to specify the DN of the entry that you want to modify.

• A set of attributes for the new entry

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

See Also

ldap_modify_ext(), LDAPMod

ldap_modify_s()

The ldap_modify_s() function modifies an existing entry in the directory synchronously.

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

Parameters

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

Use the newer version of this function, ldap_modify_ext_s() .

Example

The following example uses the synchronous ldap_modify_s() function to makes the following changes to the Barbara Jensen entry:

• Adds the homePhone attribute.
• Changes the telephoneNumber attribute.
• Removes the facsimileTelephoneNumber attribute.

#include <ldap.h>
...
LDAP *ld;
LDAPMod *list_of_attrs[4];
LDAPMod attribute1, attribute2, attribute3;
LDAPControl **srvrctrls, **clntctrls;
/* Distinguished name of the entry that you want to modify. */
char *dn = "uid=bjensen,ou=People,dc=example,dc=com";
/* Values to add or change */
char *homePhone_values[] = { "555-1212", NULL };
char *telephoneNumber_values[] = { "869-5309", NULL };
...
/* Specify each change in separate LDAPMod structures */
attribute1.mod_type = "homePhone";
attribute1.mod_op = LDAP_MOD_ADD;
attribute1.mod_values = homePhone_values;
attribute2.mod_type = "telephoneNumber";
attribute2.mod_op = LDAP_MOD_REPLACE;
attribute2.mod_values = telephoneNumber_values;
attribute3.mod_type = "facsimileTelephoneNumber";
attribute3.mod_op = LDAP_MOD_DELETE;
attribute3.mod_values = NULL;
/* NOTE: When removing entire attributes, you need to specify a NULL value
* for the mod_values or mod_bvalues field. */
/* Add the pointers to these LDAPMod structures to an array */
list_of_attrs[0] = &attribute1;
list_of_attrs[1] = &attribute2;
list_of_attrs[2] = &attribute3;
list_of_attrs[3] = NULL;
...
/* Change the entry */
if ( ldap_modify_s( ld, dn, list_of_attrs ) != LDAP_SUCCESS ) {
  ldap_perror( ld, "ldap_modify_s" );
  return( 1 );
}
...

See Also

ldap_modify_ext_s()

ldap_modrdn()

Note: This function is deprecated and should not be used. It is included in ldap-deprecated.h for backward-compatibility. Use ldap_rename() instead.

ldap_modrdn_s()

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

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

The following example 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.

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

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

Parameters

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

The following example 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.

#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

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

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

#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

ldap_msgfree() Function Parameter

Parameter	Description
lm	Pointer to the result to be freed from memory.

Returns

One of the following values:

• LDAP_RES_BIND indicates that the LDAPMessage structure contains the result of an LDAP bind operation.
• LDAP_RES_SEARCH_ENTRY indicates that the LDAPMessage structure contains an entry found during an LDAP search operation.
• LDAP_RES_SEARCH_REFERENCE indicates that the LDAPMessage structure contains an LDAP v3 search reference (a referral to another LDAP server) found during an LDAP search operation.
• LDAP_RES_SEARCH_RESULT indicates that the LDAPMessage structure contains the result of an LDAP search operation.
• LDAP_RES_MODIFY indicates that the LDAPMessage structure contains the result of an LDAP modify operation.
• LDAP_RES_ADD indicates that the LDAPMessage structure contains the result of an LDAP add operation.
• LDAP_RES_DELETE indicates that the LDAPMessage structure contains the result of an LDAP delete operation.
• LDAP_RES_MODRDN or LDAP_RES_RENAME indicates that the LDAPMessage structure contains the result of an LDAP modify DN operation.
• LDAP_RES_COMPARE indicates that the LDAPMessage structure contains the result of an LDAP compare operation.
• LDAP_RES_EXTENDED indicates that the LDAPMessage structure contains the result of an LDAP v3 extended operation.
• LDAP_SUCCESS if the operation times out.
• -1 indicates that the lm argument is not a pointer to a valid LDAPMessage structure.
• If unsuccessful, returns the LDAP error code for the operation.

Example

The following example frees the results of a search.

#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

ldap_msgid() Function Parameter

Parameter	Description
lm	Pointer to the result to check.

Returns

One of the following values:

• The message ID if successful.
• -1 if unsuccessful.

Example

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

#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

ldap_msgtype() Function Parameter

Parameter	Description
lm	Pointer to the LDAPMessage structure to check.

Returns

One of the following values:

• LDAP_RES_BIND indicates that the LDAPMessage structure contains the result of an LDAP bind operation.
• LDAP_RES_SEARCH_ENTRY indicates that the LDAPMessage structure contains an entry found during an LDAP search operation.
• LDAP_RES_SEARCH_REFERENCE indicates that the LDAPMessage structure contains an LDAP v3 search reference (a referral to another LDAP server) found during an LDAP search operation.
• LDAP_RES_SEARCH_RESULT indicates that the LDAPMessage structure contains the result of an LDAP search operation.
• LDAP_RES_MODIFY indicates that the LDAPMessage structure contains the result of an LDAP modify operation.
• LDAP_RES_ADD indicates that the LDAPMessage structure contains the result of an LDAP add operation.
• LDAP_RES_DELETE indicates that the LDAPMessage structure contains the result of an LDAP delete operation.
• LDAP_RES_MODRDN or LDAP_RES_RENAME indicates that the LDAPMessage structure contains the result of an LDAP modify DN operation.
• LDAP_RES_COMPARE indicates that the LDAPMessage structure contains the result of an LDAP compare operation.
• LDAP_RES_EXTENDED indicates that the LDAPMessage structure contains the result of an LDAP v3 extended operation.
• -1 indicates that the lm argument is not a pointer to a valid LDAPMessage structure.

Example

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

#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

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.

Returns

One of the following values:

• 0 if successful.
• -1 if memory cannot be allocated by this function. (The error code LDAP_NO_MEMORY is set in the LDAP structure. To get the error code, call the ldap_get_lderrno() function.)
• LDAP_PARAM_ERROR if an invalid parameter was passed to the function

Example

The following example sorts entries first by the roomNumber attribute, then by the telephoneNumber attribute.

#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

ldap_name2template() Function Parameters

Parameter	Description
name	Name of the template.
tmpllistp	Pointer to a list of template data structures.

Returns

• If successful, 0 is returned and tmpllistp is configured.
• Upon error:
  • LDAP_TMPL_ERR_VERSION if buf points to data that is newer than can be handled.
  • LDAP_TMPL_ERR_MEM if there is a memory allocation problem.
  • LDAP_TMPL_ERR_SYNTAX if there is a problem with the format of the templates buffer or file.
  • LDAP_TMPL_ERR_FILE if the file cannot be read.

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

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:

• If successful, returns the name of the next attribute in an entry. When you are done using this data, you should free the memory by calling the ldap_memfree() function.
• If no more attributes exist in the entry, returns a NULL .
• If unsuccessful, returns a NULL and sets the appropriate error code in the LDAP structure. To get the error code, call the ldap_get_lderrno() function.

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

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

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

• If successful, 0 is returned and tmpllistp is configured.
• Upon error:
  • LDAP_TMPL_ERR_VERSION if buf points to data that is newer than can be handled.
  • LDAP_TMPL_ERR_MEM if there is a memory allocation problem.
  • LDAP_TMPL_ERR_SYNTAX if there is a problem with the format of the templates buffer or file.
  • LDAP_TMPL_ERR_FILE if the file cannot be read.

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

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:

• If successful, returns the pointer to the next LDAPMessage structure of the type LDAP_RES_SEARCH_ENTRY in a chain of search results.
• If no more LDAPMessage structures of the type LDAP_RES_SEARCH_ENTRY are in the chain or if the function is unsuccessful, returns a NULLMSG.

Description

The ldap_next_entry() function returns a pointer to the LDAPMessage structure representing the next directory entry in a chain of search results. 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.

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

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:

• If successful, returns the pointer to the next LDAPMessage structure in a chain of search results.
• If no more LDAPMessage structures are in the chain or if the function is unsuccessful, returns a NULLMSG.

Description

The ldap_next_message() function returns a pointer to the next LDAPMessage structure in a chain of search results. You can use this function in conjunction with the ldap_first_message() function to iterate through the chain of search results. You can 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).

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

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:

• If successful, returns the pointer to the next LDAPMessage structure of the type LDAP_RES_SEARCH_REFERENCE in a chain of search results.
• If no more LDAPMessage structures of the type LDAP_RES_SEARCH_REFERENCE are in the chain or if the function is unsuccessful, returns a NULLMSG.

Description

The ldap_next_reference() function returns a pointer to the LDAPMessage structure representing the next search reference in a chain of search results. 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. Messages containing search references have the type LDAP_RES_SEARCH_REFERENCE, continuation references as specified in LDAPv3 that are stored as referral entries. Like a referral, each continuation reference itself may contain a number of URLs assumed to be equivalent, and the client should use one of those URLs.

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

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

• If successful, a pointer to an ldap_searchobj structure.
• A NULL pointer is returned if so is the last entry in the list.

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

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

• If successful, a pointer to an ldap_tmplitem structure.
• A NULL pointer on error or if col was the last item.

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

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

• If successful, a pointer to an ldap_tmplitem structure.
• A NULL pointer on error.

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

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

• Pointer to the first template where all of the object classes listed in one of the template's dt_oclist elements are contained in oclist.
• A NULL pointer if no appropriate template is found.

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

#include <ldap-deprecated.h>
ldap_open( const char *host, int port );

Parameters

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()
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 a newer version of this function, ldap_init() or prldap_init() (IPv6).

ldap_parse_authzid_control()

The ldap_parse_authzid_control() function parses the authorization identity bind response control retrieved from the server to extract the authorization ID.

Syntax

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

Parameters

ldap_parse_authzid_control() Function Parameters

Parameter	Description
ld	Pointer to an LDAP structure containing information about the connection to the LDAP server.
ctrlp	Pointer to an LDAPControl structure retrieved from the server.
authzid	Pointer to string holding the authorization ID.

Returns

One of the following values:

• LDAP_SUCCESS if successful.
• LDAP_PARAM_ERROR if any of the arguments are invalid.
• LDAP_NO_MEMORY if memory cannot be allocated to decode the control returned by the server.
• LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded message.
• LDAP_CONTROL_NOT_FOUND if no control can be found in the response returned from the server.
• LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function.

See Also

ldap_create_authzid_control()

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 LDAP v3. 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 LDAP v3 extension.

Syntax

#include <ldap.h>
int ldap_parse_entrychange_control( LDAP *ld,
  LDAPControl **ctrls, int *chgtypep, char **prevdnp,
  int *chgnumpresentp, long *chgnump );

Parameters

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:

• LDAP_SUCCESS if successful.
• LDAP_NO_MEMORY if memory cannot be allocated.
• LDAP_DECODING_ERROR if an error occurred when BER-decoding the control.

Description

The ldap_parse_entrychange_control() function can be called:

• To parse an entry returned from a persistent search operation and retrieve an entry change control.
• After receiving an entry from a persistent search and retrieving the controls from the entry. Call ldap_get_entry_controls() to get the controls.

See Also

ldap_create_persistentsearch_control(), ldap_get_entry_controls()

ldap_parse_extended_result()

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.

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

Parameters

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:

• LDAP_SUCCESS if successful.
• LDAP_PARAM_ERROR if any of the arguments are invalid.
• LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded results from the server.
• LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function. Note: This value does not apply to the operation itself.

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:

• The extended operation OID received from the server is passed back as the retoidp argument.
• The data received from the server is passed back in the berval structure as the retdatap argument.
• The LDAP result code for the LDAP extended operation is placed in the ld structure. You can get the result code by calling the ldap_get_lderrno() function. For a list of possible result codes for an LDAP extended operation, see ldap_extended_operation_s() . See also ldap_extended_operation_s(), ldap_get_lderrno().

ldap_parse_passwd()

The ldap_parse_passwd() function lets you examine the result of an LDAP Password Modify extended operation to obtain the password generated by the server when you reset a password without providing a new password value.

Syntax

#include <ldap.h>
LDAP_API(int) LDAP_CALL ldap_parse_passwd( LDAP *ld, LDAPMessage *result,
  struct berval *genpasswd );

Parameters

ldap_parse_passwd() Function Parameters

Parameter	Description
ld	Pointer to an LDAP structure containing information about the connection to the LDAP server.
result	Pointer to the message retrieved using the message ID from ldap_passwd().
genpasswd	Pointer to the BER value structure to hold the password generated by the server.

Returns

One of the following values:

• LDAP_SUCCESS if successful.
• LDAP_PARAM_ERROR if any of the arguments are invalid.
• LDAP_NO_MEMORY if memory cannot be allocated for the authorization identity.
• LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded message.
• LDAP_NOT_SUPPORTED if your LDAP client does not specify that it is using LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function.

ldap_parse_passwd_result()

The ldap_parse_passwd_result() function lets you examine the result of an LDAP Password Modify extended operation to obtain the password generated by the server when you reset a password without providing a new password value.

Syntax

#include <ldap.h>
LDAP_API(int) LDAP_CALL ldap_parse_passwd_result( LDAP *ld, int *msgidp,
  struct timeval *timeout, struct berval *genpasswd );

Parameters

ldap_parse_passwd_result() Function Parameters

Parameter	Description
ld	Pointer to an LDAP structure containing information about the connection to the LDAP server.
msgidp	Pointer to the message ID retrieved using ldap_passwd().
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 <structname> timeval</structname> structure.
genpasswd	Pointer to the BER value structure to hold the password generated by the server.

Returns

One of the following values:

• LDAP_SUCCESS if successful.
• LDAP_PARAM_ERROR if any of the arguments are invalid.
• LDAP_NO_MEMORY if memory cannot be allocated for the authorization identity.
• LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded message.
• LDAP_NOT_SUPPORTED if your LDAP client does not specify that it is using LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function.

ldap_parse_passwordpolicy_control()

The ldap_parse_passwordpolicy_control() function parses information about the password policy relative to a user account contained in a control returned with a bind, add, modify, or compare result after the ldap_create_passwordpolicy_control() is used to create a request control sent to the server. The ldap_parse_passwordpolicy_control() function populates an LDAPPasswordPolicyError structure, an expiration time counter, and a grace logins remaining counter.

Syntax

#include <ldap.h>
LDAP_API(int) LDAP_CALL ldap_parse_passwordpolicy_control( LDAP *ld,
    LDAPControl *ctrlp, ber_int_t *expirep, ber_int_t *gracep,
    LDAPPasswordPolicyError *errorp );

Parameters

ldap_parse_passwordpolicy_control() Function Parameters

Parameter	Description
ld	Pointer to an LDAP structure containing information about the connection to the LDAP server.
ctrlp	Pointer to an LDAPControl structure retrieved from the server.
expirep	Pointer to an ber_int_t structure to hold password expiration time in seconds.
gracep	Pointer to an ber_int_t structure to hold number of grace logins remaining.
pp	Pointer to an LDAPPasswordPolicyError structure to hold information about the password policy state.

Returns

One of the following values:

• LDAP_SUCCESS if successful.
• LDAP_PARAM_ERROR if any of the arguments are invalid.
• LDAP_NO_MEMORY if memory cannot be allocated to decode the control returned by the server.
• LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded message.
• LDAP_CONTROL_NOT_FOUND if no control can be found in the response returned from the server.
• LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function.

See Also

ldap_create_pwdpolicy_control(), LDAPPasswordPolicyError

ldap_parse_passwordpolicy_control_ext()

The ldap_parse_passwordpolicy_control_ext() function parses information about the password policy relative to a user account contained in a control returned with a bind, add, modify, or compare result after the ldap_create_passwordpolicy_control() is used to create a request control sent to the server. The ldap_parse_passwordpolicy_control_ext() function populates an LDAPPasswordPolicyError structure, an expiration time counter, and a grace logins remaining counter.

Syntax

#include <ldap.h>
LDAP_API(int) LDAP_CALL ldap_parse_passwordpolicy_control_ext( LDAP *ld,
    LDAPControl *ctrlp, ber_int_t *expirep, ber_int_t *gracep,
    LDAPPasswordPolicyError *errorp );

Parameters

ldap_parse_passwordpolicy_control_ext() Function Parameters

Parameter	Description
ld	Pointer to an LDAP structure containing information about the connection to the LDAP server.
ctrlp	Pointer to an LDAPControl structure retrieved from the server.
expirep	Pointer to an ber_int_t structure to hold password expiration time in seconds.
gracep	Pointer to an ber_int_t structure to hold number of grace logins remaining.
pp	Pointer to an LDAPPasswordPolicyError structure to hold information about the password policy state.

Returns

One of the following values:

• LDAP_SUCCESS if successful.
• LDAP_PARAM_ERROR if any of the arguments are invalid.
• LDAP_NO_MEMORY if memory cannot be allocated to decode the control returned by the server.
• LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded message.
• LDAP_CONTROL_NOT_FOUND if no control can be found in the response returned from the server.
• LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function.

See Also

ldap_create_pwdpolicy_control(), LDAPPasswordPolicyError

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 LDAP v3. When calling this function, make sure that you are working with a server that supports the LDAP v3.

Syntax

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

Parameters

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 LDAP v3 server controls returned by the server. When done, you can free this by calling the ldap_controls_free() function.
freeit	Specifies whether or not to free the results of the operation (the LDAPMessage structure specified by the res argument). The parameter can have the following possible values: *0 specifies that the result should not be freed. *A non-zero value specifies that the result should be freed.

Returns

One of the following values:

• LDAP_SUCCESS if successful.
• LDAP_PARAM_ERROR if any of the arguments are invalid.
• LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded results from the server.
• LDAP_NO_MEMORY if memory cannot be allocated.

Description

The ldap_parse_reference() function parses the referral URLs from an LDAPMessage structure of the type LDAP_RES_SEARCH_REFERENCE, continuation references as specified in LDAPv3 that are stored as referral entries. Like a referral, each continuation reference itself may contain a number of URLs assumed to be equivalent, and the client should use one of those URLs.

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

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). When done, you can free this by calling the ldap_memfree() function.
errmsgp	Pointer to an additional error message string sent from the server. When done, you can free this by calling the ldap_memfree() function.
referralsp	Pointer to an array of strings representing the referrals returned by the server. When done, you can free this by calling the ldap_value_free function.
serverctrlsp	Pointer to an array of LDAPControl structures, which represent the LDAPv3 server controls returned by the server. When done, you can free this by calling the ldap_controls_free() function.
freeit	Specifies whether or not to automatically free the results of the operation (the LDAPMessage structure specified by the res argument). The parameter can have the following possible values: 0 specifies that the result should not be freed. A non-zero value specifies that the result should be freed.

Returns

One of the following values:

• LDAP_SUCCESS if successful.
• LDAP_NO_RESULTS_RETURNED if the specified LDAPMessage structure does not contain the result of an LDAP operation (for example, if it contains an entry, search reference, or chain of search results instead of the result of an LDAP operation).
• LDAP_MORE_RESULTS_TO_RETURN if the result in the LDAPMessage structure is part of a chain of results and the last result is not included.
• LDAP_PARAM_ERROR if any of the arguments are invalid.
• LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded results from the server.
• LDAP_NO_MEMORY if memory cannot be allocated.

Description

The ldap_parse_result() function parses the results of an LDAP operation (received from an LDAP server) and retrieves:

• The LDAP result code that indicates the result of the LDAP operation (errcodep).
• An additional error message (optional) sent by the server (errmsgp).
• The portion of the DN that finds an entry, if the server is unable to find an entry from a DN that you specify (matcheddnp).
• A set of referrals, if the server does not contain the entries that you‚Äö√Ñ√¥ve specified and if the server is configured to refer clients to other servers (referralsp).
• A set of server response controls that are relevant to the operation (serverctrlsp). Calling this function creates an array of LDAPControl structures that you can pass to subsequent API functions (such as the ldap_parse_sort_control() function.

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 LDAP v3. When calling this function, make sure that you are working with a server that supports the LDAP v3.

Syntax

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

Parameters

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:

• LDAP_SUCCESS if successful.
• LDAP_PARAM_ERROR if any of the arguments are invalid.
• LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded message.
• LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function.

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:

• The challenge or credentials sent back from the server are passed back in the berval structure as the servercredp argument.
• The LDAP result code for the SASL bind operation is placed in the ld structure. You can get the result code by calling the ldap_get_lderrno() function. (If the result code is LDAP_SASL_BIND_IN_PROGRESS , you can call ldap_sasl_bind() again to send a response to the server‚Äö√Ñ√¥s challenge and call ldap_result() and ldap_parse_sasl_bind_result() again to get the next challenge from the server. For a list of possible result codes for an LDAP SASL bind operation, see ldap_sasl_bind().

Note: The LDAP server must support authentication through SASL mechanisms. Directory Server supports a plug-in interface that you can use to add SASL support to the server.

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.

#include <ldap.h>
int ldap_parse_sort_control( LDAP *ld, LDAPControl **ctrls,
  unsigned long *result, char **attribute );

Parameters

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:

• LDAP_SUCCESS if successful.
• LDAP_PARAM_ERROR if any of the arguments are invalid.
• LDAP_NO_MEMORY if memory cannot be allocated to decode the control returned by the server.
• LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded message.
• LDAP_CONTROL_NOT_FOUND if no control can be found in the response returned from the server.

Description

Call the ldap_parse_sort_control() function as part of the process of retrieving sorted search results from a server. 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_userstatus_control()

The ldap_parse_userstatus_control() function parses information about the status of a user account contained in a control returned with an entry resulting from a search request that included the control created with ldap_create_userstatus_control(). The ldap_parse_userstatus_control() function populates an LDAPuserstatus structure.

Syntax

#include <ldap.h>
LDAP_API(int) LDAP_CALL ldap_parse_userstatus_control( LDAP *ld,
  LDAPControl **ctrlp, LDAPuserstatus *us );

Parameters

ldap_parse_userstatus_control() Function Parameters

Parameter	Description
ld	Pointer to an LDAP structure containing information about the connection to the LDAP server.
ctrlp	Pointer to an LDAPControl structure retrieved with ldap_get_entry_controls().
us	Pointer to an LDAPuserstatus structure to hold the information about account status.

Returns

One of the following values:

• LDAP_SUCCESS if successful.
• LDAP_PARAM_ERROR if any of the arguments are invalid.
• LDAP_NO_MEMORY if memory cannot be allocated to decode the control returned by the server.
• LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded message.
• LDAP_CONTROL_NOT_FOUND if no control can be found in the response returned from the server.
• LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function.

See Also

ldap_create_userstatus_control(), LDAPuserstatus()

ldap_parse_whoami()

The ldap_parse_whoami() function retrieves the authorization identity from the result of an asynchronous Who am I? extended operation request.

Syntax

#include <ldap.h>
LDAP_API(int) LDAP_CALL ldap_parse_whoami_result( LDAP *ld,
  LDAPMessage *result, char **authzid );

Parameters

ldap_parse_whoami() Function Parameters

Parameter	Description
ld	Pointer to an LDAP structure containing information about the connection to the LDAP server.
result	Pointer to the message retrieved using the message ID from ldap_whoami().
authzid	Pointer to the string to hold the authorization identity retrieved for the connection.

Returns

One of the following values:

• LDAP_SUCCESS if successful.
• LDAP_PARAM_ERROR if any of the arguments are invalid.
• LDAP_NO_MEMORY if memory cannot be allocated for the authorization identity.
• LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded message.
• LDAP_NOT_SUPPORTED if your LDAP client does not specify that it is using LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function.

ldap_parse_whoami_result()

The ldap_parse_whoami_result() function retrieves the authorization identity from the result of an asynchronous Who am I? extended operation request.

Syntax

#include <ldap.h>
LDAP_API(int) LDAP_CALL ldap_parse_whoami_result( LDAP *ld, int *msgidp,
  struct timeval *timeout, char **authzid );

Parameters

ldap_parse_whoami_result() Function Parameters

Parameter	Description
ld	Pointer to an LDAP structure containing information about the connection to the LDAP server.
msgidp	Pointer to the message ID retrieved using ldap_whoami().
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 <structname> timeval</structname> structure.
authzid	Pointer to the string to hold the authorization identity retrieved for the connection.

Returns

One of the following values:

• LDAP_SUCCESS if successful.
• LDAP_PARAM_ERROR if any of the arguments are invalid.
• LDAP_NO_MEMORY if memory cannot be allocated for the authorization identity.
• LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded message.
• LDAP_NOT_SUPPORTED if your LDAP client does not specify that it is using LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function.

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 LDAP v3. A virtual list viewis an optional LDAP server feature that may not be supported on all LDAP servers.

Syntax

#include <ldap.h>
int ldap_parse_virtuallist_control( LDAP *ld,
  LDAPControl **ctrls, unsigned long *target_posp,
  unsigned long *list_sizep, int *errcodep );

Parameters

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:

• LDAP_SUCCESS if successful.
• LDAP_PARAM_ERROR if any of the arguments are invalid.
• LDAP_NO_MEMORY if memory cannot be allocated to decode the control returned by the server.
• LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded message.
• LDAP_CONTROL_NOT_FOUND if no control can be found in the response returned from the server.
• LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function.

Description

The ldap_parse_virtuallist_control() function can be called:

• As part of the process of retrieving a subset of entries from a list when working with a virtual list view box.
• After, calling ldap_result() to get the results, and ldap_parse_result() to parse the server controls from the results.

See Also

ldap_create_virtuallist_control()

ldap_passwd()

The ldap_passwd() asynchronous function allows you to perform an LDAP Password Modify extended operation, as defined in RFC 3062.

Syntax

#include <ldap.h>
int ldap_passwd( LDAP *ld, struct berval *userid,
  struct berval *oldpasswd, struct berval *newpasswd,
  LDAPControl **serverctrls, LDAPControl **clientctrls,
  int *msgidp );

Parameters

ldap_passwd() Function Parameters

Parameter	Description
ld	Pointer to an LDAP structure containing information about the connection to the LDAP server.
userid	DN of the user whose password you want to modify.
oldpasswd	Old password used before expiration. If the password has not yet expired, this is the current password.
newpasswd	New password to use after modification
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 to be set to the message ID of the operation. To check the result of this operation, call the ldap_result() and ldap_parse_passwd() function, or ldap_parse_passwd_result() function.

Returns

One of the following values:

• LDAP_SUCCESS if successful.
• LDAP_PARAM_ERROR if an invalid parameter was passed to the function.
• LDAP_NO_MEMORY if memory cannot be allocated.
• LDAP_ENCODING_ERROR if an error occurred when BER-encoding the control.
• LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.
• LDAP_NOT_SUPPORTED if your LDAP client does not specify that it is using LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function.

ldap_passwd_s()

The ldap_passwd_s() synchronous function allows you to perform an LDAP Password Modify extended operation, as defined in RFC 3062.

Syntax

#include <ldap.h>
int ldap_passwd_s( LDAP *ld, struct berval *userid,
  struct berval *oldpasswd, struct berval *newpasswd,
  struct berval *genpasswd, LDAPControl **serverctrls,
  LDAPControl **clientctrls );

Parameters

ldap_passwd() Function Parameters

Parameter	Description
ld	Pointer to an LDAP structure containing information about the connection to the LDAP server.
userid	DN of the user whose password you want to modify.
oldpasswd	Old password used before expiration. If the password has not yet expired, this is the current password.
newpasswd	New password to use after modification
genpasswd	New password generated by the server when an expired password is reset, but no newpasswd value is provided.
serverctrls	Pointer to an array of LDAPControl structures representing LDAP server controls that apply to this LDAP operation. If you do not want to pass any server controls, specify NULL for this argument.
clientctrls	Pointer to an array of LDAPControl structures representing LDAP client controls that apply to this LDAP operation. If you do not want to pass any client controls, specify NULL for this argument.

Returns

One of the following values:

• LDAP_SUCCESS if successful.
• LDAP_PARAM_ERROR if an invalid parameter was passed to the function.
• LDAP_NO_MEMORY if memory cannot be allocated.
• LDAP_ENCODING_ERROR if an error occurred when BER-encoding the control.
• LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.
• LDAP_NOT_SUPPORTED if your LDAP client does not specify that it is using LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function.

ldap_passwordpolicy_err2txt()

The ldap_passwordpolicy_err2txt() function extracts textual information from an LDAPPasswordPolicyError about password policy state.

Syntax

#include <ldap.h>
LDAP_API(const char *) LDAP_CALL ldap_passwordpolicy_err2txt(
                LDAPPasswordPolicyError err );

Parameters

ldap_passwordpolicy_err2txt() Function Parameter

Parameter	Description
err	The LDAPPasswordPolicyError structure containing information about the password policy state.

Returns

A string having one of the following values:

• Password expired
• Account locked
• Password must be changed
• Policy prevents password modification
• Policy requires old password in order to change password
• Password fails quality checks
• Password is too short for policy
• Password has been changed too recently
• New password is in list of old passwords
• No error
• Unknown error code

See Also

ldap_parse_passwordpolicy_control(), LDAPPasswordPolicyError

ldap_perror()

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

Parameters

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

Use the newer version of this function, ldap_get_lderrno() .

Example

The following example prints out an error message if the search operation cannot complete successfully.

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

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:

• LDAP_SUCCESS if successful.
• LDAP_PARAM_ERROR if any of the arguments are invalid.
• LDAP_NO_MEMORY if memory cannot be allocated to decode the control returned by the server.
• LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request.
• LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.
• LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function.

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.

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.

#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

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:

• LDAP_SUCCESS if successful.
• LDAP_PARAM_ERROR if any of the arguments are invalid.
• LDAP_NO_MEMORY if memory cannot be allocated to decode the control returned by the server.
• LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request.
• LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.
• LDAP_LOCAL_ERROR if an error occurred when receiving the results from the server.
• LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded results from the server.
• LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAPv3. Make sure that you set the version of your LDAP client to version 3 before calling this function.

Note: Directory Server and other LDAP server products may send result codes in addition to those described. For example, the server may have loaded a plug-in that returns custom result codes. Check your LDAP server documentation for other result codes.

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

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

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:

• LDAP_RES_BIND indicates that the LDAPMessage structure contains the result of an LDAP bind operation.
• LDAP_RES_SEARCH_ENTRY indicates that the LDAPMessage structure contains an entry found during an LDAP search operation.
• LDAP_RES_SEARCH_REFERENCE indicates that the LDAPMessage structure contains an LDAPv3 search reference (a referral to another LDAP server) found during an LDAP search operation.
• LDAP_RES_SEARCH_RESULT indicates that the LDAPMessage structure contains the result of an LDAP search operation.
• LDAP_RES_MODIFY indicates that the LDAPMessage structure contains the result of an LDAP modify operation.
• LDAP_RES_ADD indicates that the LDAPMessage structure contains the result of an LDAP add operation.
• LDAP_RES_DELETE indicates that the LDAPMessage structure contains the result of an LDAP delete operation.
• LDAP_RES_MODDN or LDAP_RES_RENAME indicates that the LDAPMessage structure contains the result of an LDAP modify DN operation.
• LDAP_RES_COMPARE indicates that the LDAPMessage structure contains the result of an LDAP compare operation.
• LDAP_RES_EXTENDED indicates that the LDAPMessage structure contains the result of an LDAP v3 extended operation.
• -1 indicates that an error occurred. The error code is set in the LDAP structure. To get the error code, call the ldap_get_lderrno() function.
• 0 indicates that the operation has timed out.

See Also

ldap_add_ext(), ldap_compare_ext() , ldap_delete_ext(), ldap_modify_ext(), ldap_rename(), ldap_simple_bind(), ldap_url_search()

ldap_result2error()

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

Parameters

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:

• If successful, sets the error code and other error information in the LDAP structure and returns the error code.
• If unsuccessful, returns LDAP_PARAM_ERROR.

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. Directory Server supports a server plug-in interface that you can use to add SASL support to the server.

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

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:

• LDAP_SUCCESS if the SASL bind request was sent successfully.
• LDAP_PARAM_ERROR if an invalid parameter was passed to the function.
• LDAP_NOT_SUPPORTED if controls are included in your request‚Äö√Ñ√Æfor example, as a session preference‚Äö√Ñ√Æand your LDAP client does not specify that it is using the LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function.
• LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request to send to the server.
• LDAP_NO_MEMORY if memory cannot be allocated.
• LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.

Description

The ldap_sasl_bind() function authenticates your client to an LDAP server by using a specified SASL mechanism. 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.

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.

#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

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:

• LDAP_SUCCESS if the SASL bind request was sent successfully.
• LDAP_PARAM_ERROR if an invalid parameter was passed to the function.
• LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAPv3. Make sure that you set the version of your LDAP client to version 3 before calling this function.
• LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request to send to the server.
• LDAP_DECODING_ERROR if an error occurred when the LDAP API library was decoding the BER-encoded results received from the server.
• LDAP_NO_MEMORY if memory cannot be allocated.
• LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.
• LDAP_LOCAL_ERROR if an error occurred when receiving the results from the server.

Note: Directory Server and other LDAP server products may send result codes in addition to those described. For example, the server may have loaded a plug-in that returns custom result codes. Check your LDAP server documentation for other result codes.

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.

See Also

ldap_sasl_bind()

ldap_search()

The ldap_search() function searches the directory asynchronously.

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

Parameters

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

The following example searches a directory.

#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. Use prldap_init() for IPv6. */
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.

#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

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

• LDAP_SUCCESS if the SASL bind request was sent successfully.
• LDAP_PARAM_ERROR if an invalid parameter was passed to the function.
• LDAP_NOT_SUPPORTED if controls are included in your request‚Äö√Ñ√Æfor example, as a session preference‚Äö√Ñ√Æand your LDAP client does not specify that it is using the LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function.
• LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request to send to the server.
• LDAP_NO_MEMORY if memory cannot be allocated.
• LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.

Description

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

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

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)
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.
sizelimit	Maximum number of results to return in the search.
res	Results of the search (when the call is completed).

Returns

One of the following values:

• LDAP_SUCCESS if the SASL bind request was sent successfully.
• LDAP_PARAM_ERROR if an invalid parameter was passed to the function.
• LDAP_NOT_SUPPORTED if controls are included in your request‚Äö√Ñ√Æfor example, as a session preference‚Äö√Ñ√Æand your LDAP client does not specify that it is using the LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function.
• LDAP_FILTER_ERROR if an error occurred when parsing and BER-encoding the search filter specified by the filter argument.
• LDAP_TIMEOUT if the search exceeded the time specified by the timeoutp argument.
• LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request to send to the server.
• LDAP_DECODING_ERROR if an error occurred when the LDAP API library was decoding the BER-encoded results received from the server.
• LDAP_NO_MEMORY if memory cannot be allocated.
• LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.
• LDAP_LOCAL_ERROR if an error occurred when receiving the results from the server.

The 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 <function> ldap_search_ext_s</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.)

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

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

Use the newer version of this function, ldap_search_ext_s() .

Example

The following example searches the directory for all people whose surname (last name) is Jensen.

#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. Use prldap_init() for IPv6. */
  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.

#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

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

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:

• LDAP_SUCCESS if successful.
• If unsuccessful, returns an LDAP error code.

Example

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

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

Note: This function is deprecated and should not be used. It is included in ldap-deprecated.h for backward-compatibility. Use ldap_set_filter_additions() instead.

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

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.
s	The text of the error message that you want associated with this error code.

Returns

One of the following values:

• LDAP_SUCCESS if successful.
• If unsuccessful, returns an LDAP error code.

Description

The ldap_set_lderrno() function sets an error code and information about an error in an LDAP structure. You can call this function to set error information that will be retrieved by subsequent ldap_get_lderrno() function calls.

Example

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

#include <ldap.h>
int rc;
char *errmsg = "Invalid parameter";
...
if ( ldap_my_function() != LDAP_SUCCESS ) {
  rc = ldap_set_lderrno( ld, LDAP_PARAM_ERROR, NULL, errmsg );
  if ( rc != LDAP_SUCCESS ) {
    printf( "Error: %d\nError code could not be set.\n", rc );
  }
  return( rc );
}
...

See Also

ldap_err2string(), ldap_perror, ldap_result2error()

ldap_set_option()

The function ldap_set_option() sets session preferences in the LDAP structure.

Syntax

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

Parameters

ldap_set_option() Function Parameters

Parameter	Description
ld	Pointer to an LDAP structure containing information about the connection to the LDAP server. If NULL, you are setting the default options that will apply to any new LDAP connection handles that are subsequently created.
option	Option that you want to set. See Table 21–182 for available options of this parameter.
optdata	Pointer to the value of the option that you want to set. Available data types are also listed in the following table.

The option parameter can have one of the values listed in the following table.

Options for ldap_set_option()

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 LDAP v3 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. 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 LDAP v3 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. To handle failover use 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 LDAP v3 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. 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 time out (expressed in milliseconds) for non-blocking connect call. The data type for the optdata parameter is (int *).
LDAP_X_OPT_SOCKBUF	Socket buffer structure associated to the LDAP connection.

See also ldap_set_option() for details on LDAP_OPT_X_SASL* parameters.

Returns

One of the following values:

• LDAP_SUCCESS if successful.
• -1 if unsuccessful.

Example

#include <stdio.h>
#include <ldap.h>
...
LDAP *ld;
int max_ret = 100, max_tim = 30;
char *host = "ldap.sun.com";
...
/* Initialize a session with the LDAP server ldap.sun.com:389 */
/* Use prldap_init() for IPv6 support. */
if ( ( ld = ldap_init( host, LDAP_PORT ) ) == NULL ) {
  perror( "ldap_init" );
  return( 1 );
}
/* Set the maximum number of entries returned */
if ( ldap_set_option( ld, LDAP_OPT_SIZELIMIT, &max_ret) !
  LDAP_SUCCESS) {
  ldap_perror( ld, "ldap_set_option" );
  return( 1 );
}
...

See Also

ldap_init(), prldap_init() (IPv6), ldap_get_option()

ldap_set_rebind_proc()

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

Syntax

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

Parameters

ldap_set_rebind_proc() Function Parameters

Parameter	Description
ld	Pointer to an LDAP structure containing information about the connection to the LDAP server.
rebindproc	Pointer to a function called back to obtain bind credentials when a new server is contacted during an LDAP referral.
arg	Pointer to an additional argument that you want to pass to the rebind function.

Description

Call ldap_set_rebind_proc() to specify the rebind function. This rebind function is called by the LDAP client when following a referral to a new LDAP server. It is responsible for obtaining the credentials used to authenticate to the new server. For example, suppose LDAP server A sends a referral to your client. The referral points your client to LDAP server B. When automatically following the referral, your client calls the rebind function to obtain a DN and credentials; your client uses these to authenticate to server B. By default, if you do not call ldap_set_rebind_proc() or if you pass NULL for the rebindproc argument, your client authenticates anonymously when following referrals. The rebind function that you specify with ldap_set_rebind_proc() should have the following prototype:

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

1. The LDAP server sends a referral back to the client.
2. The client calls the rebind function, passing 0 as the freeit argument.
3. The rebind function sets the dnp, passwdp, and authmethodp arguments to point to the following information:
   • The dnp argument is set to point to the DN to be used to authenticate to the new LDAP server.
   • The passwdp argument is set to point to the credentials for this DN.
   • The authmethodp argument is set to point to the method of authentication used (for example, LDAP_AUTH_SIMPLE).
4. If successful, the rebind function returns LDAP_SUCCESS and referral processing continues. (If any other value is returned, referral processing stops, and that value is returned as the result code for the original LDAP request.)
5. The client gets the DN, credentials, and authentication method from the arguments of the rebind function and uses this information to authenticate to the new LDAP server.
6. The client calls the rebind function again, passing 1 as the freeit argument.
7. The rebind function frees any memory allocated earlier to specify the DN and credentials.

You need to write a rebind function that does the following:

• If freeit is 0, set the following pointers:
  • Set dnp to point to the DN to be used for authentication.
  • Set passwdp to point to the credentials to be used for authentication.
  • Set authmethodp to point to the method of authentication used (for example, LDAP_AUTH_SIMPLE).

You can also make use of the arg argument, which is a pointer to the argument specified in the ldap_set_rebind_proc() function. If successful, returns LDAP_SUCCESS. Otherwise, returns the appropriate LDAP error code. If freeit is 1, free any memory that you allocated to create the DN and credentials.

After you have defined this function, pass the function name to ldap_set_rebind_proc() to register your rebind function.

Note: In order to use the rebind function, the LDAP_OPT_REFERRALS option must be set to LDAP_OPT_ON, so that your client automatically follows referrals. This option is set to LDAP_OPT_ON by default.

Example

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

#include "ldap.h"
...
/* Declare your rebind function */
int rebindproc( LDAP *ld, char **dnp, char **passwdp,
  int *authmethodp, int freeit, void *arg );
...
int main( int argc, char **argv )
{
  LDAP *ld;
  /* Additional argument to be passed to the rebind function */
  char *testarg = "cn=admin,cn=Administrators,cn=config";
  /* Get a handle to an LDAP connection. Use prldap_init() for IPv6. */
  if ( (ld = ldap_init( "directory.example.com", 389 )) == NULL ) {
    perror( "ldap_init" );
    return( 1 );
  }
  /* Specify the function used for reauthentication on referrals */
  ldap_set_rebind_proc( ld, rebindproc, (void *)testarg );
  /* Authenticate */
  if ( ldap_simple_bind_s( ld, "uid=bjensen,ou=People,dc=example,dc=com",
      "hifalutin" ) != LDAP_SUCCESS ) {
    ldap_perror( ld, "ldap_simple_bind_s" );
    return( 1 );
  }
  ...
  /* Your code to interact with the LDAP server */
  ...
}
...
/* rebindproc is the rebind function responsible for providing the DN,
  credentials, and authentication method used for authenticating the
  client to other Directory Servers.
  The function should set the following arguments:
  - dnp should point to the DN that will be used for authentication.
  - passwdp should point to the credentials used for authentication.
  - authmethodp should point to the method of authentication to be used
  (for example, LDAP_AUTH_SIMPLE).
  The function should return LDAP_SUCCESS if successful or an LDAP
  error code if an error occurs.
  In order to demonstrate how the freeit argument works, this example
  uses strdup() to copy the DN and password.  You can also just copy
  string pointers if the DN and password are already available as
  global variables.
*/
int LDAP_CALL LDAP_CALLBACK rebindproc(
  LDAP *ld, char **dnp, char **passwdp,
  int *authmethodp, int freeit, void *arg )
{
  printf( "Rebind function called.\n" );
  switch ( freeit ) {
  /* Your client calls the rebind function with freeit==1 when it needs
    to free any memory you've allocated. */
  case 1:
    printf( "\tFreeing memory.\n" );
    if ( dnp  *dnp ) {
      free( *dnp );
    }
    if ( passwdp  *passwdp ) {
      free( *passwdp );
    }
    break;
  /* Your client calls the rebind function with freeit==0 when it needs
  to get the DN, credentials, and authentication method. */
  case 0:
    printf( "\tGetting DN and credentials.\n" );
    *dnp = strdup( "uid=username,o=OtherServerSuffix" );
    *passwdp = strdup( "23skidoo" );
    *authmethodp = LDAP_AUTH_SIMPLE;
    break;
  default:
    printf( "\tUnknown value of freeit argument: %d\n", freeit );
    break;
  }
  /* If you successfully set the DN and credentials, you should return
    LDAP_SUCCESS.  (Any other return code will stop the client from
    automatically following the referral. */
  return LDAP_SUCCESS;
}

See Also

ldap_simple_bind(), ldap_simple_bind_s()

ldap_simple_bind()

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

Syntax

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

Parameters

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

Returns

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

Description

The ldap_simple_bind() function authenticates to the LDAP server. It verifies that the password supplied for authentication matches the userPassword attribute of the given entry. <function> ldap_simple_bind</function> is an asynchronous function; it does not directly return results. If you want the results to be returned directly by the function, call the synchronous function ldap_simple_bind_s().

The following example calls ldap_simple_bind() to authenticate the user Barbara Jensen to the directory.

#include <stdio.h>
#include <ldap.h>
...
LDAP *ld;
char *host = "ldap.sun.com";
char *dn = "uid=bjensen,ou=People,dc=example,dc=com";
char *pw = "hifalutin";
struct timeval zerotime;
zerotime.tv_sec = zerotime.tv_usec = 0L;
...
/* Initialize a session with the LDAP server ldap.example.com:389 */
/* Use prldap_init() for IPv6 support. */
if ( ( ld = ldap_init( host, LDAP_PORT ) ) == NULL ) {
  perror( "ldap_init" );
  return( 1 );
}
/* Attempt to bind with the LDAP server */
msgid = ldap_simple_bind( ld, dn, pw );

/* Initialize the value returned by ldap_result() */
rc = 0;

/* While the operation is still running, do this: */
while ( rc == 0 ) {
  ... /* do other work while waiting */...

  /* Check the status of the LDAP operation */
  rc = ldap_result( ld, msgid, NULL, zerotime, result );
  switch( rc ) {
    /* If -1 was returned, an error occurred */
    case -1:
      ldap_perror( ld, "Error in results: " );
      return( 1 );
    /* If 0 was returned, the operation is still in progress */
    case 0:
      continue;
    /* If any other value is returned, assume we are done */
    default:
      /* Check if the "bind" operation was successful */
      if ( ldap_result2error( result ) != LDAP_SUCCESS ) {
        ldap_perror( ld, "Error binding to server: " );
        return( 1 );
        }
  }
}
...

See Also

ldap_simple_bind_s()

ldap_simple_bind_s()

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

Syntax

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

Parameters

ldap_simple_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.
passwd	Password of the user who wants to authenticate. For anonymous authentication, set this or the who argument to NULL.

Returns

One of the following values:

• LDAP_SUCCESS if successful.
• LDAP_PARAM_ERROR if an invalid parameter was passed to the function.
• LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function.
• LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request to send to the server.
• LDAP_DECODING_ERROR if an error occurred when the LDAP API library was decoding the BER-encoded results received from the server.
• LDAP_NO_MEMORY if memory cannot be allocated.
• LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.
• LDAP_LOCAL_ERROR if an error occurred when receiving the results from the server.

Note: Directory Server and other LDAP server products may send result codes in addition to those described. For example, the server may have loaded a plug-in that returns custom result codes. Check your LDAP server documentation for other result codes.

Description

The ldap_simple_bind_s() function authenticates to the LDAP server. It verifies that the password supplied for authentication matches the userPassword attribute of the given entry. <function> ldap_simple_bind_s</function> is a synchronous function, which directly returns the results of the operation. If you want to perform other operations while waiting for the results of this operation, call the asynchronous function ldap_simple_bind() instead.

The following example uses the synchronous ldap_simple_bind_s() function to authenticate to the directory as the user Barbara Jensen.

#include <stdio.h>
#include <ldap.h>
...
LDAP *ld;
char *host = "ldap.sun.com";
char *dn = "uid=bjensen,ou=People,dc=example,dc=com";
char *pw = "hifalutin";
...
/* Initialize a session with the LDAP server ldap.sun.com:389 */
/* Use prldap_init() for IPv6 support. */
if ( ( ld = ldap_init( host, LDAP_PORT ) ) == NULL ) {
  perror( "ldap_init" );
  return( 1 );
}
/* Attempt to bind with the LDAP server */
if ( ldap_simple_bind_s( ld, dn, pw ) != LDAP_SUCCESS ) {
  ldap_perror( ld, "Authentication failed: " );
  return( 1 );
}
...

See Also

ldap_simple_bind()

ldap_sort_entries()

The ldap_sort_entries() function sorts a chain of entries retrieved from an LDAP search call.

Syntax

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

Parameters

ldap_sort_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	Attribute to use when sorting the results. To sort by DN instead of by attribute, use NULL.
cmp	Comparison function used when sorting the values.

Returns

One of the following values:

• LDAP_SUCCESS if successful.
• If unsuccessful, returns a NULL and sets the appropriate error code in the LDAP structure. To get the error code, call ldap_get_lderrno().

Description

The ldap_sort_entries() function sorts a chain of entries retrieved from an LDAP search call (ldap_search_s() or ldap_result()) either by DN or a specified attribute in the entries.

Example

The following example sorts entries by the roomNumber attribute.

#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 *sortby = "roomNumber";
...
/* Search the directory */
if ( ldap_search_s( ld, my_searchbase, LDAP_SCOPE_SUBTREE, my_filter,
  NULL, 0, &result ) !=
  LDAP_SUCCESS ) {
  ldap_perror( ld, "ldap_search_s" );
  return( 1 );
}
/* Sort the results by room number, using strcasecmp */
if ( ldap_sort_entries( ld, &result, sortby, strcasecmp ) !=
  LDAP_SUCCESS ) {
  ldap_perror( ld, "ldap_sort_entries" );
  return( 1 );
}
...

See Also

ldap_multisort_entries(), ldap_result(), ldap_search_s(), LDAP_CMP_CALLBACK()

ldap_start_tls_s()

The ldap_start_tls_s() initiates a Start Transport Layer Security (TLS) operation as defined in RFC 4513. Before using this function, call ldapssl_client_init(), ldapssl_clientauth_init(), or ldapssl_advclientauth_init() to initialize use of the certificate database.

Syntax

#include <ldap_ssl.h>
int ldap_start_tls_s( LDAP *ld, LDAPControl **serverctrls,
  LDAPControl **clientctrls );

Parameters

ldap_start_tls_s() Function Parameters

Parameter	Description
ld	Pointer to an LDAP structure containing information about the connection to the LDAP server.
serverctrls	List of LDAP server controls.
clientctrls	List of client controls.

Returns

One of the following values:

• LDAP_SUCCESS if successful.
• LDAP_OPERATIONS_ERROR if TLS has already been established.
• LDAP_PROTOCOL_ERROR if TLS is not supported.
• LDAP_REFERRAL if this server does not support TLS, but the server referred to may.
• LDAP_UNAVAILABLE if the server is shutting down, or supports TLS but cannot provide it at this time.

ldap_sort_strcasecmp()

The ldap_sort_strcasecmp() routine compares two strings and ignores any differences in case when comparing uppercase and lowercase characters.

Syntax

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

Parameters

ldap_sort_strcasecmp() Function Parameters

Parameter	Description
a	Pointer to first string to compare
b	Pointer to second string to compare

Returns

One of the following values:

• If a is greater than b, returns a value greater than 0.
• If a is equal to b, returns 0.
• If a is less than b, returns a value less than 0.

Description

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

Note: This function works with ASCII values only. For UTF-8 data, the comparison result is unspecified.

See Also

ldap_sort_strcasecmp(), LDAP_VALCMP_CALLBACK()

ldap_sort_values()

The ldap_sort_values() function sorts an array of values retrieved from an ldap_get_values() call.

Syntax

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

Parameters

ldap_sort_values() Function Parameters

Parameter	Description
ld	Pointer to an LDAP structure containing information about the connection to the LDAP server.
vals	The array of values to sort.
cmp	Comparison function used when sorting the values. In the ldap_sort_strcasecmp() function, the comparison function must pass char ** parameters. Because of this, you need to use the ldap_sort_strcasecmp() function, rather than a function like strcasecmp().

Returns

One of the following values:

• LDAP_SUCCESS if successful.
• If unsuccessful, returns an LDAP error code.

Example

The following example sorts the values of attributes before printing them.

#include <stdio.h>
#include <string.h>
#include <ldap.h>
...
LDAP *ld;
LDAPMessage *result, *e;
BerElement *ber;
char *a, *dn;
char **vals;
int i;
char *my_searchbase = "dc=example,dc=com";
char *my_filter = "(sn=Jensen)";
...
if ( ( vals = ldap_get_values( ld, e, a ) ) != NULL ) {
  /* Sort the values of the attribute */
  if ( ldap_sort_values( ld, vals, strcasecmp ) ) != LDAP_SUCCESS ) {
    ldap_perror( ld, "ldap_sort_values" );
    return( 1 );
  }
  /* Print the values of the attribute */
  for ( i = 0; vals[i] != NULL; i++ ) {
    printf( "%s: %s\n", a, vals[i] );
  }
  /* Free the values from memory */
  ldap_value_free( vals );
}
...

See Also

ldap_get_values(), ldap_sort_strcasecmp, LDAP_VALCMP_CALLBACK().

ldapssl_advclientauth_init()

The ldapssl_advclientauth_init() function initialize the secure parts (Security and SSL) of the runtime for use by a client application that may want to do SSL client authentication.

Syntax

#include <ldap_ssl.h>
int LDAP_CALL ldapssl_advclientauth_init( char *certdbpath,
  void *certdbhandle, int needkeydb, char *keydbpath,
  void *keydbhandle, int needsecmoddb, char *secmodpath,
  const int sslstrength);

Parameters

ldapssl_advclientauth_init() Function Parameters

Parameter	Description
certdbpath	Specifies the path to the database containing certificates for your client. You can include the database filename in the path (for example, /usr/mozilla/ cert_file_name.db).
certdbhandle	Pass a NULL value for this. (This parameter is not currently used.)
needkeydb	Specifies whether or not the private key database needs to be opened for use. This parameter can have one of the following values: If it is a non-zero value, the function opens the private key database, which is identified by the keydbpath argument. If 0, the function does not open the private key database.
keydbpath	Specifies the path to the database containing the private key certified by your certificate. You can include the database filename in the path (for example, /usr/mozilla/key_file_name.db).
needsecmoddb	Specifies whether or not the security module database file needs to be opened for use. This parameter can have one of the following values: If it is a non-zero value, the function opens the security module database, which is identified by the keydbpath argument. If 0, the function does not open the security modules database.
secmodpath	Path to the database containing security modules. You can include the database filename in the path (for example, /usr/mozilla/secmod_file_name .db).
sslstrength	Specifies how the server certificate is evaluated. It takes one of the following: LDAPSSL_AUTH_WEAK indicates that you accept the server’s certificate without checking the for certificate authority (CA) that issued the certificate. LDAPSSL_AUTH_CERT indicates that you accept the server’s certificate only if you trust the CA that issued the certificate. LDAPSSL_AUTH_CNCHECK indicates that you accept the server’s certificate only if you trust the CA that issued the certificate and if the value of the cn attribute is the DNS hostname of the server. If this option is selected, ensure that the defhost parameter passed to ldapssl_init() consists of only one hostname and not a list of hosts. Furthermore, the port number must be passed via the defport parameter, and cannot be passed via a host:port option.

Returns

One of the following values:

• 0 if successful.
• -1 if unsuccessful.

Description

You can call ldapssl_advclientauth_init() to initialize your client application for SSL and certificate-based client authentication. This function is similar to ldapssl_clientauth_init() and allows you to:

• Specify the name and path of a security module database.
• Specify the method used to verify the server‚Äö√Ñ√¥s certificate.

Note: You must call ldapssl_advclientauth_init() before calling ldapssl_init() to connect to the server.

Example

The following example initializes a client before connecting with a secure LDAP server.

#include <ldap.h>
#include <ldap_ssl.h>
#include <stdio.h>
...
/* Initialize client, using mozilla’s certificate database */
if ( ldapssl_advclientauth_init( "/u/mozilla/.netscape/
  ''cert_file_name''.db",
  NULL, 1, "/u/mozilla/.netscape/
  ''key_file_name''.db", NULL , 1,
  "/u/mozilla/.netscape/
  ''secmod_file_name''.db", LDAPSSL_AUTH_CNCHECK) < 0 ) {
  perror( "ldap_advclientauth_init" );
  return( 1 );
  }
}
...

See Also

ldap_init(), prldap_init() (IPv6), ldapssl_clientauth_init(), ldapssl_init(), ldapssl_install_routines()

ldapssl_client_init()

The ldapssl_client_init() function initializes the secure parts (Security and SSL) of the runtime for use by your client application to connect to a secure LDAP server over SSL.

Syntax

#include <ldap_ssl.h>
int ldapssl_client_init( const char *certdbpath, void *certdbhandle );

Parameters

ldapssl_client_init() Function Parameters

Parameter	Description
certdbpath	Specifies the path to the database containing certificates for your client.
certdbhandle	Pass a NULL value for this. (This parameter is not used currently.)

Returns

One of the following values:

• 0 if successful.
• -1 if unsuccessful.

Description

You can call the ldapssl_client_init() function to initialize your client application for SSL. It is only called once and returns 0 if all goes well. If you plan to use certificate-based authentication, you should call either the ldapssl_clientauth_init() or the ldapssl_advclientauth_init() function.

The following example initializes a client before connecting with a secure LDAP server.

#include <ldap.h> 
#include <ldap_ssl.h> 
#include <stdio.h>

... /* Initialize client using a certificate database copied from Directory Server. */
if ( ldapssl_client_init( "/local/client/alias/", NULL ) < 0) { 
  printf( "Failed to initialize SSL client...\n" );
  return( 1 );
}

The certdbpath is a path to the file system directory containing the certificate database files. For example:

$ ls /local/client/alias/*.db
/local/client/alias/cert8.db
/local/client/alias/key3.db
/local/client/alias/secmod.db
$

See Also

ldap_start_tls_s(), ldap_init(), prldap_init() (IPv6), ldapssl_init(), ldapssl_install_routines()

ldapssl_clientauth_init()

The ldapssl_clientauth_init() function initializes your client application to connect to a secure LDAP server over SSL and to use certificate-based client authentication.

Syntax

#include <ldap_ssl.h>
int ldapssl_clientauth_init( char *certdbpath, void *certdbhandle,
  int needkeydb, char *keydbpath, void *keydbhandle );

Parameters

ldapssl_clientauth_init() Function Parameters

Parameter	Description
certdbpath	Specifies the path to the database containing certificates for your client. You can include the database filename in the path (for example, /usr/mozilla/ cert_file_name.db).
needkeydb	Specifies whether or not the private key database needs to be opened for use. This parameter can have one of the following values: If it is a non-zero value, the function opens the private key database, which is identified by the keydbpath argument. If 0, the function does not open the private key database.
keydbpath	Specifies the path to the database containing the private key certified by your certificate. You can include the database filename in the path (for example, /usr/mozilla/ key_file_name.db).
certdbhandle	Pass a NULL value for this. (This parameter is not currently used.)

Returns

One of the following values:

• 0 if successful.
• -1 if unsuccessful.

Description

You can call the ldapssl_clientauth_init() function to initialize your client application for SSL and certificate-based client authentication. However, if you need to specify the name and path of the security modules database or if you need to specify how the server’s certificate will be verified, you should call the ldapssl_advclientauth_init() function instead.

Note: You must call ldapssl_clientauth_init() before calling ldapssl_init() to connect to the server.

Example

The following example initializes a client before connecting with a secure LDAP server.

#include <ldap.h>
#include <ldap_ssl.h>
#include <stdio.h>
...
/* Initialize client, using mozilla’s certificate database */
if ( ldapssl_clientauth_init( "/u/mozilla/.netscape/
  ''cert_file_name''.db", NULL, 1,
  "/u/mozilla/.netscape/
  ''key_file_name''.db", NULL ) < 0 ) {
  perror( "ldap_clientauth_init" );
  return( 1 );
  }
}
...

See Also

ldap_init(), prldap_init() (IPv6), ldapssl_init(), ldapssl_install_routines()

ldapssl_enable_clientauth()

The ldapssl_enable_clientauth() function enables SSL client authentication on the given connection (passed using the ld parameter).

Syntax

#include <ldap_ssl.h>
int ldapssl_enable_clientauth( LDAP *ld, char *keynickname,
  char *keypasswd, char *certnickname );

Parameters

ldapssl_enable_clientauth() Function Parameters

Parameter	Description
ld	Pointer to an LDAP structure containing information about the connection to the LDAP server.
keynickname	Pass an empty string, "", for this value. (This parameter is not currently used.)
keypasswd	Password to the encrypted private key database.
certnickname	Nickname of the certificate that you want to use for client authentication.

Returns

One of the following values:

• 0 if successful.
• -1 if unsuccessful.

See Also

ldapssl_clientauth_init()

ldapssl_err2string()

The ldapssl_err2string() function returns the corresponding error message for an SSL-specific error code.

Syntax

#include <ldap_ssl.h>
const char * LDAP_CALL ldapssl_err2string ( const int prerrno );

Parameters

ldapssl_err2string() Function Parameters

Parameter	Description
prerrno	The SSL error code that you want interpreted into an error message.

Returns

One of the following values:

• If successful, returns the corresponding error message for the given error code.
• If unsuccessful (for example, if the error code is not a known SSL error code), returns a pointer to the string Unknown error.

Description

ldapssl_err2string() provides support for SSL-specific error messages that are not covered by the regular message routine ldap_err2string(). If any ldapssl_*() function returns an error code that is unknown to ldap_err2string()–it returns Unknown error– this function should be called to determine the SSL-specific error message. To check for SSL errors, call ldapssl_err2string() after you call any of the following SSL initialization functions:

• ldapssl_client_init()
• ldapssl_clientauth_init()
• ldapssl_advclientauth_init()
• ldapssl_pkcs_init()

The errors returned by these functions are usually related to certificate database corruption, missing certificates in a certificate database, client authentication failures, and other general SSL errors.

See Also

ldapssl_client_init(), ldapssl_clientauth_init(), ldapssl_advclientauth_init(), ldapssl_pkcs_init(), ldap_err2string()

ldapssl_init()

The ldapssl_init() function initializes the LDAP library for SSL and installs the I/O routines for SSL.

Syntax

#include <ldap_ssl.h>
LDAP *ldapssl_init( const char *defhost, int defport, int defsecure );

Parameters

ldapssl_init() Function Parameters

Parameter	Description
defhost	Connect to this LDAP server, if no other server is specified.
defport	Connect to this server port, if no other port is specified. To specify the default port 389, use LDAP_PORT as the value for this parameter.
defsecure	Determines whether or not to establish the default connection over SSL. Set this to a non-zero value to establish the default connection over SSL.

Returns

One of the following values:

• If successful, returns a pointer to an LDAP() structure, which should be passed to subsequent calls to other LDAP API functions.
• If unsuccessful, returns -1.

Description

ldapssl_init() allocates an LDAP() structure but does not open an initial connection. Before calling this function, call ldapssl_client_init() to initialize your client for SSL.

The following example connects your client to a secure LDAP server.

#include <ldap.h>
#include <ldap_ssl.h>
#include <stdio.h>
...
/* Initialize client, using mozilla’s certificate database */
if ( ldapssl_client_init( "/u/mozilla/.netscape/
  ''cert_file_name''.db", NULL ) < 0) {
  printf( "Failed to initialize SSL client...\n" );
  return( 1 );
}
/* get a handle to an LDAP connection */
if ( (ld = ldapssl_init( "cert.example.com", LDAPS_PORT, 1 )) == NULL {
  perror( "ldapssl_init" );
  return( 1 );
}
...
/* Client can now perform LDAP operations on the secure LDAP server */
...

See Also

ldap_init(), prldap_init() (IPv6), ldapssl_client_init(), ldapssl_install_routines()

ldapssl_install_routines()

The ldapssl_install_routines() function installs the I/O routines that enable SSL over LDAP.

Syntax

#include <ldap_ssl.h>
int ldapssl_install_routines( LDAP *ld );

Parameters

ldapssl_install_routines() Function Parameter

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

Returns

One of the following values:

• 0 if successful.
• -1 if unsuccessful.

Description

You need to call ldapssl_install_routines() in combination with ldap_init() or prldap_init() (IPv6) and ldap_set_option(). As an alternative, you can call ldapssl_init() rather than these three functions.

Note: As is the case with the ldapssl_init() function, you need to call ldapssl_client_init() to initialize your client for SSL before calling ldapssl_install_routines().

Example

The following example connects your client to a secure LDAP server.

#include <ldap.h>
#include <ldap_ssl.h>
#include <stdio.h>
...
/* Initialize client, using mozilla’s certificate database */
if ( ldapssl_client_init( "/u/mozilla/.netscape/
  ''cert_file_name''.db", NULL ) < 0) {
  printf( "Failed to initialize SSL client...\n" );
  return( 1 );
}
/* Get the handle to an LDAP connection. Use prldap_init() for IPv6. */
if ( (ld = ldap_init( MY_HOST, 636 )) == NULL ) {
  perror( "ldap_init" );
  return( 1 );
}
/* Load SSL routines */
if ( ldapssl_install_routines( ld ) != LDAP_SUCCESS ) {
  ldap_perror( ld, "ldapssl_install_routines" );
  return( 1 );
}
/* Set the option to use SSL with the default connection */
if (ldap_set_option( ld, LDAP_OPT_SSL, LDAP_OPT_ON ) != LDAP_SUCCESS) {
  ldap_perror( ld, "ldap_set_option" );
  return( 1 );
}
...

See Also

ldap_init(), prldap_init() (IPv6), ldapssl_init(), ldapssl_client_init()

ldapssl_pkcs_init()

int ldapssl_pkcs_init( const struct ldapssl_pkcs_fns *pfns);

Description

The ldap_pkcs_init() structure sets up callbacks for the security library to obtain required runtime information. It should be used in place of ldapssl_client_init(), ldapssl_clientauth_init(), and ldapssl_advclientauth_init().

Note: The LDAP C SDK uses the Public Key Cryptography Standard (PKCS) API implemented in Network Security Services (NSS) to provide SSL security support. Specifically, NSS implements the security API as defined in the PKCS#11 standard.

Because ldap_pkcs_init() is based on the ldapssl_pkcs_fns structure, you do not need to know all of the security parameters at initialization, unlike the other SSL initialization functions (ldapssl_*_init()), which require all security parameters to be known at the time of initialization. The following example defines the ldapssl_pkcs_fns structure.

typedef int (LDAP_PKCS_GET_TOKEN_CALLBACK)
  (void *context, char **tokenname);
typedef int (LDAP_PKCS_GET_PIN_CALLBACK)
  (void *context, const char *tokenname, char **tokenpin);
typedef int (LDAP_PKCS_GET_CERTPATH_CALLBACK)
  (void *context, char **certpath);
typedef int (LDAP_PKCS_GET_KEYPATH_CALLBACK)(void *context,
  char **keypath);
typedef int (LDAP_PKCS_GET_MODPATH_CALLBACK)
  (void *context, char **modulepath);
typedef int (LDAP_PKCS_GET_CERTNAME_CALLBACK)
  (void *context, char **certname);
typedef int (LDAP_PKCS_GET_DONGLEFILENAME_CALLBACK)
  (void *context, char **filename);
#define PKCS_STRUCTURE_ID 1
struct ldapssl_pkcs_fns {
  int local_structure_id;
  void *local_data;
  LDAP_PKCS_GET_CERTPATH_CALLBACK *pkcs_getcertpath;
  LDAP_PKCS_GET_CERTNAME_CALLBACK *pkcs_getcertname;
  LDAP_PKCS_GET_KEYPATH_CALLBACK *pkcs_getkeypath;
  LDAP_PKCS_GET_MODPATH_CALLBACK *pkcs_getmodpath;
  LDAP_PKCS_GET_PIN_CALLBACK *pkcs_getpin;
  LDAP_PKCS_GET_TOKEN_CALLBACK *pkcs_gettokenname;
  LDAP_PKCS_GET_DONGLEFILENAME_CALLBACK *pkcs_getdonglefilename;
};

Parameters

ldapssl_pkcs_init() Function Parameters

Parameter	Description
pfns	Specifies the ldap_pkcs_fns structure for initialization.

Returns

One of the following values:

• 0 is successful.
• -1 if unsuccessful.
• n (a positive integer) denotes a Netscape Portable Runtime (NSPR) error as returned by the PR_GetError() NSPR function.

See Also

ldapssl_client_init(), ldapssl_clientauth_init(), ldapssl_advclientauth_init()

ldapssl_serverauth_init()

The ldapssl_serverauth_init() function is a server-authentication only version of ldapssl_clientauth_init().

Syntax

#include <ldap_ssl.h>
int ldapssl_serverauth_init(
  const char *certdbpath, void *certdbhandle, const int sslstrength );

Parameters

ldapssl_serverauth_init() Function Parameters

Parameter	Description
certdbpath	Specifies the path to the database containing certificates for your client. You can include the database filename in the path (for example, /usr/mozilla/cert_file_name.db).
certdbhandle	Pass a NULL value for this. (This parameter is not currently used.)
sslstrength	Specifies how the server certificate is evaluated. It takes one of the following: LDAPSSL_AUTH_WEAK indicates that you accept the server’s certificate without checking the for certificate authority (CA) that issued the certificate. LDAPSSL_AUTH_CERT indicates that you accept the server’s certificate only if you trust the CA that issued the certificate. LDAPSSL_AUTH_CNCHECK indicates that you accept the server’s certificate only if you trust the CA that issued the certificate and if the value of the cn attribute is the DNS hostname of the server. If this option is selected, please ensure that the defhost parameter passed to ldapssl_init consists of only one hostname and not a list of hosts. Furthermore, the port number must be passed via the defport parameter, and cannot be passed via a host:port option.

Returns

One of the following values:

• 0 if successful.
• -1 if unsuccessful.

Description

ldapssl_serverauth_init() is a server-authentication only version of ldapssl_clientauth_init(). This function allows the sslstrength parameter to be passed in.

See Also

ldap_init(), prldap_init() (IPv6), ldapssl_init(), ldapssl_install_routines(), ldapssl_clientauth_init()

ldapssl_set_strength()

The ldapssl_set_strength() sets the SSL strength for an existing SSL-enabled LDAP session handle.

Syntax

#include <ldap_ssl.h>
int LDAP_CALL ldapssl_set_strength( LDAP *ld, int sslstrength );

Parameters

Note: See the description of the sslstrength value and note the potential problems that can be caused by passing in wrong host and port name values.

ldapssl_set_strength() Function Parameters

Parameter	Description
ld	Pointer to an LDAP structure containing information about the connection to the LDAP server. If value is NULL, the default for the new LDAP session handles is set.
sslstrength	Specifies how the server certificate is evaluated. It takes one of the following: LDAPSSL_AUTH_WEAK indicates that you accept the server’s certificate without checking the for certificate authority (CA) that issued the certificate. LDAPSSL_AUTH_CERT indicates that you accept the server’s certificate only if you trust the CA that issued the certificate. LDAPSSL_AUTH_CNCHECK indicates that you accept the server’s certificate only if you trust the CA that issued the certificate and if the value of the cn attribute is the DNS hostname of the server. If this option is selected, please ensure that the defhost parameter passed to ldapssl_init consists of only one hostname and not a list of hosts. Furthermore, the port number must be passed via the defport parameter, and cannot be passed via a host:port option.

ldapssl_tls_start_s()

The ldapssl_tls_start_s() function starts an SSL handshake on a previously established non-secure connection.

Syntax

#include <ldap_ssl.h>
LDAP_API(int)  LDAP_CALL ldapssl_tls_start_s( LDAP *ld, int defsecure,
  char *certdbpath, char *keydbpath, char ***referralsp );

Parameters

ldapssl_tls_start_s() Function Parameter

Parameter	Description
ld	Pointer to an LDAP structure containing information about the connection to the LDAP server.
defsecure	Determines whether or not to establish the default connection over SSL. Set this to a non-zero value to establish the default connection over SSL.
certdbpath	Specifies the path to the database containing certificates for your client. You can include the database filename in the path (for example, /usr/mozilla/cert_file_name.db).
keydbpath	Specifies the path to the database containing the private key certified by your certificate. You can include the database filename in the path (for example, /usr/mozilla/key_file_name.db).
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.

Description

The ldapssl_tls_start_s() function starts an SSL handshake on a previously established non-secure connection.

ldap_str2charray()

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

ldap_tmplattrs()

The ldap_tmplattrs() function obtains a pointer to the correct ldap_disptmpl structure.

Syntax

#include <disptmpl.h>
char ** ldap_tmplattrs( struct ldap_disptmpl *tmpl, char **includeattrs,
  int exclude, unsigned long syntaxmask );

Parameters

ldap_tmplattrs() Function Parameters

Parameter	Description
tmpl	The name of the template to be retrieved.
includeattrs	A null terminated array of attributes that should always be included (it may be NULL if no extra attributes are required).
exclude	If 0, only attributes where the logical AND of the template item syntax id and the syntaxmask is non-zero are included. If non-zero, attributes where the logical AND of the template item syntax id and the syntaxmask is non-zero are excluded.
syntaxmask	When non-zero, it is used to restrict the attribute set returned.

Returns

• A NULL terminated array that contains the

names of attributes that need to be retrieved if the template, defined by tmpl , is to be used to display an entry.

• A NULL pointer on error.

Description

The attribute list should be freed using ldap_value_free() .

See Also

ldap_value_free()

ldap_tmplerr2string()

The ldap_templerr2string() function returns a string representation of the error passed in the parameter.

Syntax

#include <disptmpl.h>
char * ldap_tmplerr2string( int err );

Parameters

ldap_tmplerr2string() Function Parameter

Parameter	Description
err	Error returned.

ldap_ufn_search_c()

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

ldap_ufn_search_s()

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

ldap_ufn_setprefix()

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

ldap_unbind()

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

Syntax

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

Parameters

ldap_unbind() Function Parameter

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

Returns

For a list of possible results for an LDAP unbind operation, see ldap_unbind_s().

Description

The ldap_unbind() function unbinds from the directory, terminates the current association, and frees the resources contained in the LDAP structure. The three unbind functions (ldap_unbind() , ldap_unbind_s(), and ldap_unbind_ext()) all work synchronously in the sense that they send an unbind request to the server, close all open connections associated with the LDAP session handle, and dispose of all resources associated with the session handle before returning.

The following example closes the current connection with the LDAP server.

#include <ldap.h>
...
LDAP *ld;
...
/* After completing your LDAP operations with the server, close the
connection. */
if ( ldap_unbind( ld ) != LDAP_SUCCESS ) {
  ldap_perror( ld, "Error while unbinding from the directory" );
  return( 1 );
}
...

See Also

ldap_unbind_s(), ldap_unbind_ext()

ldap_unbind_s()

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

Syntax

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

Parameters

ldap_unbind_s() Function Parameter

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

Returns

One of the following values:

• LDAP_SUCCESS if successful.
• LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request.
• LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.
• LDAP_NO_MEMORY if memory cannot be allocated.

Description

The ldap_unbind_s() function unbinds from the directory, terminates the current association, and frees the resources contained in the LDAP structure. The three unbind functions ( ldap_unbind(), ldap_unbind_s(), and ldap_unbind_ext()) all work synchronously in the sense that they send an unbind request to the server, close all open connections associated with the LDAP session handle, and dispose of all resources associated with the session handle before returning.

Note: There is no server response to an LDAP unbind operation. All three of the unbind functions return LDAP_SUCCESS (or another LDAP error code if the request cannot be sent to the LDAP server). After a call to one of the unbind functions, the session handle ld is invalid and it is illegal to make any further calls using it.

Example

The following example closes the current connection with the LDAP server.

#include <ldap.h>
...
LDAP *ld;
...
/* After completing your LDAP operations with the server, close the
connection. */
if ( ldap_unbind_s( ld ) != LDAP_SUCCESS ) {
  ldap_perror( ld, "Error while unbinding from the directory" );
  return( 1 );
}
...

See Also

ldap_unbind(), ldap_unbind_ext()

ldap_unbind_ext()

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

Syntax

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

Parameters

ldap_unbind_ext() Function Parameters

Parameter	Description
ld	Pointer to an LDAP structure containing information about the connection to the LDAP server.
serverctrls	List of LDAP server controls.
clientctrls	List of client controls.

Returns

One of the following values:

• LDAP_SUCCESS if successful.
• LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request.
• LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.
• LDAP_NO_MEMORY if memory cannot be allocated.
• LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function.

Description

The ldap_unbind_ext() function unbinds from the directory, terminates the current association, and frees the resources contained in the LDAP structure. The three unbind functions (ldap_unbind(), ldap_unbind_s(), and ldap_unbind_ext()) all work synchronously in the sense that they send an unbind request to the server, close all open connections associated with the LDAP session handle, and dispose of all resources associated with the session handle before returning.

See also ldap_unbind(), ldap_unbind_s()

ldap_url_parse()

The ldap_url_parse() function parses an LDAP URL into its components.

Syntax

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

Parameters

ldap_url_parse() Function Parameters

Parameter	Description
url	The URL that you want to check.
ludpp	Pointer to a structure containing the components of the URL.

Returns

One of the following values:

• LDAP_SUCCESS if successful.
• LDAP_URL_ERR_NOTLDAP if the URL does not begin with the ldap:// or ldaps:// prefix.
• LDAP_URL_ERR_NODN if the URL missing trailing slash after host or port.
• LDAP_URL_ERR_BADSCOPE if the scope within the URL is invalid.
• LDAP_URL_ERR_MEM if not enough free memory is available for this operation.
• LDAP_URL_ERR_PARAM if an invalid argument was passed to the function.

Example

The following example parses an LDAP URL and prints out each component of it.

#include <stdio.h>
#include <ldap.h>
...
char *my_url = "ldap://ldap.example.com:1389/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 missing trailing slash after host or port\n" );
      break;
    case LDAP_URL_ERR_BADSCOPE:
      printf( "URL contains an invalid scope\n" );
      break;
    case LDAP_URL_ERR_MEM:
      printf( "Not enough memory\n" );
      break;
    default:
      printf( "Unknown error\n" );
  }
  return( 1 );
}
printf( "Components of the URL:\n" );
printf( "Host name: %s\n", ludpp->lud_host );
printf( "Port number: %d\n", ludpp->lud_port );
if ( ludpp->lud_dn != NULL ) {
  printf( "Base entry: %s\n", ludpp->lud_dn );
} else {
  printf( "Base entry: Root DN\n" );
}
if ( ludpp->lud_attrs != NULL ) {
  printf( "Attributes returned: \n" );
  for ( i=0; ludpp->lud_attrs[i] != NULL; i++ ) {
    printf( "\t%s\n", ludpp->lud_attrs[i] );
}
} else {
        printf( "No attributes returned.\n" );
}
printf( "Scope of the search: " );
switch( ludpp->lud_scope ) {
  case LDAP_SCOPE_BASE:
    printf( "base\n" );
    break;
  case LDAP_SCOPE_ONELEVEL:
    printf( "one\n" );
    break;
  case LDAP_SCOPE_SUBTREE:
    printf( "sub\n" );
    break;
  default:
    printf( "Unknown scope\n" );
}
printf( "Filter: %s\n", ludpp->lud_filter );
...

See Also

ldap_free_urldesc()

ldap_url_parse_no_defaults()

The ldap_url_parse_no_defaults() function parses an LDAP URL into its components.

Syntax

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

Parameters

ldap_url_parse_no_defaults() Function Parameters

Parameter	Description
url	The URL that you want to check.
ludpp	Pointer to a structure containing the components of the URL.
dn_required	Specifies if a DN must be present in the URL. Set to 0, the DN is not required. Set to 1, the function will return an error LDAP_URL_ERR_NODN if no DN is present.

Returns

One of the following values:

• LDAP_SUCCESS if successful.
• LDAP_URL_ERR_NODN if a required DN is not present.
• LDAP_URL_ERR_NOTLDAP if the URL does not begin with the ldap:// or ldaps:// prefix.
• LDAP_URL_ERR_NODN if the URL missing trailing slash after host or port.
• LDAP_URL_ERR_BADSCOPE if the scope within the URL is invalid.
• LDAP_URL_ERR_MEM if not enough free memory is available for this operation.
• LDAP_URL_ERR_PARAM if an invalid argument was passed to the function.

Description

The ldap_url_parse_no_defaults() function does not set any default value in the fields that would be absent from the URL (for example, the port number).

ldap_url_search()

The ldap_url_search() function searches the directory asynchronously for matching entries, based on the contents of the URL.

Syntax

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

Parameters

ldap_url_search() Function Parameters

Parameter	Description
ld	Pointer to an LDAP structure containing information about the connection to the LDAP server.
url	LDAP URL specifying a search of the directory.
attrsonly	Specifies whether or not attribute values are returned along with the attribute types. This parameter can have the following values: 0 specifies that both attribute types and attribute values are returned. 1 specifies that only attribute types are returned.

Returns

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

Description

ldap_url_search() searches the directory for matching entries, based on the contents of the URL. ldap_url_search() is an asynchronous function; it does not directly return results. If you want the results to be returned directly by the function, call the synchronous function ldap_url_search_s().

Example

The following example returns the message ID.

#include "examples.h"

static void do_other_work();
unsigned long global_counter = 0;

int
main( int argc, char **argv )
{
  char *my_url = "ldap://ldap.example.com/dc=example,dc=com?
                  cn,mail,telephoneNumber?sub?(sn=Jensen)";
  LDAP *ld;
  LDAPMessage *result, *e;
  BerElement *ber;
  char *a, *dn;
  char **vals;
  int i, rc, finished, msgid;
  int num_entries = 0;
  struct timeval zerotime;

  zerotime.tv_sec = zerotime.tv_usec = 0L;

/* Get a handle to an LDAP connection. Use prldap_init() for IPv6. */
if ( (ld = ldap_init( MY_HOST, MY_PORT )) == NULL ) {
  perror( "ldap_init" );
  return( 1 );
}
/* authenticate to the directory as nobody */
if ( ldap_simple_bind_s( ld, NULL, NULL ) != LDAP_SUCCESS ) {
  ldap_perror( ld, "ldap_simple_bind_s" );
  return( 1 );
}
/* search for all entries with surname of Jensen */
if (( msgid = ldap_url_search( ld, my_url, 0 )) == -1 ) {
  ldap_perror( ld, "ldap_url_search" );
  return( 1 );
}

/* Loop, polling for results until finished */
finished = 0;
while ( !finished ) {
  /*
  * Poll for results.   We call ldap_result with the "all" parameter
  * set to zero. This causes ldap_result() to return exactly one
  * entry if at least one entry is available. This allows us to
  * display the entries as they are received.
  */
  result = NULL;
  rc = ldap_result( ld, msgid, 0, zerotime, result );
  switch ( rc ) {
  case -1:
    /* some error occurred */
    ldap_perror( ld, "ldap_result" );
    return( 1 );
  case 0:
  /* Timeout was exceeded. No entries are ready for retrieval. */
    if ( result != NULL ) {
      ldap_msgfree( result );
    }
    break;
  default:
  /*
  * Either an entry is ready for retrieval, or all entries have
  * been retrieved.
  */
    if (( e = ldap_first_entry( ld, result )) == NULL ) {
      /* All done */
      finished = 1;
      if ( result != NULL ) {
        ldap_msgfree( result );
      }
      continue;
      }
    /* for each entry print out name + all attrs and values */
    num_entries++;
    if (( dn = ldap_get_dn( ld, e )) != NULL ) {
      printf( "dn: %s\n", dn );
      ldap_memfree( dn );
    }
    for ( a = ldap_first_attribute( ld, e, ber );
     a != NULL; a = ldap_next_attribute( ld, e, ber ) ) {
      if (( vals = ldap_get_values( ld, e, a )) != NULL ) {
        for ( i = 0; vals[ i ] != NULL; i++ ) {
          printf( "%s: %s\n", a, vals[ i ] );
        }
      ldap_value_free( vals );
      }
      ldap_memfree( a );
    }
    if ( ber != NULL ) {
      ldap_ber_free( ber, 0 );
    }
    printf( "\n" );
    ldap_msgfree( result );
  }
  /* Do other work here while you are waiting... */
  do_other_work();
}

/* All done. Print a summary. */
printf( "%d entries retrieved. I counted to %ld "
      "while I was waiting.\n", num_entries,
      global_counter );
ldap_unbind( ld );
return( 0 );
}

/*
 * Perform other work while polling for results. */
static void
do_other_work()
{
    global_counter++;
}

See Also

ldap_url_search_s(), ldap_result(), ldap_result2error()

ldap_url_search_s()

The ldap_url_search_s() function searches the directory synchronously for matching entries, based on the contents of the URL.

Syntax

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

Parameters

ldap_url_search_s() Function Parameters

Parameter	Description
ld	Pointer to an LDAP structure containing information about the connection to the LDAP server.
url	LDAP URL specifying a search of the directory.
attrsonly	Specifies whether or not attribute values are returned along with the attribute types. This parameter can have the following values: 0 specifies that both attribute types and attribute values are returned. 1 specifies that only attribute types are returned.
res	Results of the search (when the call is completed).

Returns

One of the following values:

• LDAP_SUCCESS if successful.
• If unsuccessful, returns the LDAP error code for the operation.

Description

The ldap_url_search_s() function searches the directory for matching entries, based on the contents of the URL. ldap_url_search_s() is a synchronous function, which directly returns the results of the operation. If you want to perform other operations while waiting for the results of this operation, call the asynchronous function ldap_url_search().

Example

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

#include <stdio.h>
#include <ldap.h>
...
LDAP *ld;
LDAPMessage *result;
char *my_url = "ldap://ldap.example.com/dc=example,dc=com?
cn,mail,telephoneNumber?sub?(sn=Jensen)";
...
/* Process the search request in the URL */
if ( ldap_url_search_s( ld, my_url, 0, &result ) != LDAP_SUCCESS ) {
  ldap_perror( ld, "ldap_url_search_s" );
  return( 1 );
}
...

See Also

ldap_search(), ldap_search_st()

ldap_url_search_st()

The ldap_url_search_st() function searches the directory, synchronously within a specified time limit, for matching entries, based on the contents of the URL.

Syntax

#include <ldap.h>
int ldap_url_search_st( LDAP *ld, const char *url, int attrsonly,
  struct timeval *timeout, LDAPMessage **res );

Parameters

ldap_url_search_st() Function Parameters

Parameter	Description
ld	Pointer to an LDAP structure containing information about the connection to the LDAP server.
url	LDAP URL specifying a search of the directory.
attrsonly	Specifies whether or not attribute values are returned along with the attribute types. This parameter can have the following values: 0 specifies that both attribute types and attribute values are returned. 1 specifies that only attribute types are returned.
timeout	Maximum time to wait for the results of the search.
res	Results of the search (when the call is completed).

Returns

One of the following values:

• LDAP_SUCCESS if successful.
• LDAP_PARAM_ERROR if any of the arguments are invalid.
• LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request.
• LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.
• LDAP_NO_MEMORY if memory cannot be allocated.
• LDAP_LOCAL_ERROR if an error occurred when receiving the results from the server.
• LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded results from the server.
• LDAP_FILTER_ERROR if an error occurred when parsing and BER-encoding the search filter specified by the filter argument.
• LDAP_TIMEOUT if the search exceeded the time specified by the timeoutp argument.
• LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function.

Note: Directory Server and other LDAP server products may send result codes in addition to those described. For example, the server may have loaded a plug-in that returns custom result codes. Check your LDAP server documentation for other result codes.

Description

The ldap_url_search_st() function searches the directory for matching entries, based on the contents of the URL. This function works like ldap_url_search_s() and lets you specify a time out period for the search.

See Also

ldap_search(), ldap_search_s()

ldap_utf8characters()

The ldap_utf8characters() function accepts a Unicode string and returns the number of characters.

Syntax

#include <ldap.h>
size_t ldap_utf8characters( const char* );

Parameters

ldap_utf8characters() Function Parameter

Parameter	Description
char	Pointer to a UTF-8 string.

Returns

Returns the number of UTF-8 characters in the 0 terminated array.

ldap_utf8copy()

The ldap_utf8copy() function accepts a Unicode string and copies the characters to a destination.

Syntax

#include <ldap.h>
int ldap_utf8copy( char* dst, const char* src );

Parameters

ldap_utf8copy() Function Parameter

Parameter	Description
dst	Pointer to a destination for the copied characters.
src	Pointer to a UTF-8 string to copy.

Description

ldap_utf8copy() copies a character from src to dst. This function handles any valid UTF-8 character (including \0 and ASCII).

Returns

The number of characters copied.

ldap_utf8getcc()

The ldap_utf8getcc() function gets one UCS-4 character and moves the pointer to the next character.

Syntax

#include <ldap.h>
unsigned long ldap_utf8getcc( const char** src );

Parameters

ldap_utf8getcc() Function Parameter

Parameter	Description
src	Pointer to a UCS-4 character.

ldap_utf8isalnum()

The ldap_utf8isalnum() function determines whether the character is an alphanumeric one.

Syntax

#include <ldap.h>
int ldap_utf8isalnum( char* s );

Parameters

ldap_utf8isalnum() Function Parameter

Parameter	Description
s	Pointer to a UTF-8 character.

ldap_utf8isalpha()

The ldap_utf8isalpha() function determines whether the character is a letter.

Syntax

#include <ldap.h>
int ldap_utf8isalpha( char* s );

Parameters

ldap_utf8isalpha() Function Parameter

Parameter	Description
s	Pointer to a UTF-8 character.

ldap_utf8isdigit()

The ldap_utf8isdigit() function determines whether the character is a number.

Syntax

#include <ldap.h>
int ldap_utf8isdigit( char* s );

Parameters

ldap_utf8isdigit() Function Parameter

Parameter	Description
s	Pointer to a UTF-8 character.

ldap_utf8isspace()

The ldap_utf8isspace() function determines whether the character is a space, tab, newline, return or formfeed.

Syntax

#include <ldap.h>
int ldap_utf8isspace( char* s );

Parameters

ldap_utf8isspace() Function Parameter

Parameter	Description
s	Pointer to a UTF-8 character.

ldap_utf8len()

The ldap_utf8len() function accepts a Unicode string and returns the number of bytes it contains.

Syntax

#include <ldap.h>
int ldap_utf8len( const char* );

Parameters

ldap_utf8len() Function Parameter

Parameter	Description
char	Pointer to a UTF-8 string.

ldap_utf8next()

The ldap_utf8next() function accepts a character and returns a pointer to the character immediately following it.

Syntax

#include <ldap.h>
char* ldap_utf8next( char* );

Parameters

ldap_utf8next() Function Parameter

Parameter	Description
char	Pointer to a UTF-8 character.

ldap_utf8prev()

The ldap_utf8prev() function accepts a character and returns a pointer to the previous character.

Syntax

#include <ldap.h>
char* ldap_utf8prev( char* );

Parameters

ldap_utf8prev() Function Parameter

Parameter	Description
char	Pointer to a UTF-8 character.

ldap_utf8strtok_r()

The ldap_utf8strtok_r() function gets the next token from a string.

Syntax

#include <ldap.h>
char* ldap_utf8strtok_r( char* src, const char* brk, char** next);

Parameters

ldap_utf8strtok_r() Function Parameter

Parameter	Description
src	Pointer to a UTF-8 string from which to extract token.
brk	Points to a NULL terminated set of delimiter characters.
next	Pointer to the next token.

Returns

Returns a pointer to the next token. If there are no remaining tokens, returns a NULL pointer.

ldap_whoami()

The ldap_whoami() function sends an asynchronous Who am I? extended operation request to determine the authorization identity associated with a connection.

Syntax

LDAP_API(int) LDAP_CALL ldap_whoami( LDAP *ld, LDAPControl **serverctrls,
  LDAPControl **clientctrls, int *msgidp );

Parameters

ldap_whoami() Function Parameters

Parameter	Description
ld	Pointer to an LDAP structure containing information about the connection to the LDAP server.
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 the message ID for this asynchronous call, for use with ldap_parse_whoami_result(), or to retrieve the result for use with ldap_parse_whoami().

Returns

One of the following values:

• LDAP_SUCCESS if successful.
• LDAP_PARAM_ERROR if any of the arguments are invalid.
• LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request.
• LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.
• LDAP_NO_MEMORY if memory cannot be allocated.

ldap_whoami_s()

The ldap_whoami_s() function sends a synchronous Who am I? extended operation request to determine the authorization identity associated with a connection.

Syntax

LDAP_API(int) LDAP_CALL ldap_whoami_s( LDAP *ld, LDAPControl **serverctrls,
  LDAPControl **clientctrls, char **authzid );

Parameters

ldap_whoami_s() Function Parameters

Parameter	Description
ld	Pointer to an LDAP structure containing information about the connection to the LDAP server.
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.
authzid	Pointer to the string to hold the authorization identity retrieved from the server.

Returns

One of the following values:

• LDAP_SUCCESS if successful.
• LDAP_PARAM_ERROR if any of the arguments are invalid.
• LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request.
• LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.
• LDAP_NO_MEMORY if memory cannot be allocated.

ldap_vals2html()

The ldap_vals2html() function writes the HTML representation of a set of values.

Syntax

#include <disptmpl.h>
int ldap_vals2html( LDAP *ld, char *buf, char **vals, char *label,
  int labelwidth, unsigned long syntaxid, writeptype writeproc,
  void *writeparm, char *eol, int rdncount, char *urlprefix );

Parameters

ldap_vals2html() Function Parameters

Parameter	Description
ld	The LDAP pointer obtained by a previous call to ldap_open() .
buf
vals	A NULL terminated list of values, usually obtained by a call to ldap_get_values().
label	A string (usually a friendly form of an LDAP attribute name) shown next to the values.
labelwidth	Specifies the label margin (the number of blank spaces displayed to the left of the values). If zero is passed, a default label width is used.
syntaxid	Display template attribute syntax identifier for a list of predefined LDAP_SYN_... values.
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.
urlprefix	Starting text to use when constructing an LDAP URL. The default is the string ldap://

Returns

• LDAP_SUCCESS if successful.
• An LDAP error code on error.

Description

ldap_vals2html() produces HTML output of a single set of LDAP attribute values.

See Also

ldap_vals2text()

ldap_vals2text()

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

Syntax

#include <disptmpl.h>
int ldap_vals2text( LDAP *ld, char *buf, char **vals, char *label,
  int labelwidth, unsigned long syntaxid, writeptype writeproc,
  void *writeparm, char *eol, int rdncount );

Parameters

ldap_vals2text() Function Parameters

Parameter	Description
ld	The LDAP pointer obtained by a previous call to ldap_open() .
buf
vals	A NULL terminated list of values, usually obtained by a call to ldap_get_values().
label	A string (usually a friendly form of an LDAP attribute name) shown next to the values.
labelwidth	Specifies the label margin (the number of blank spaces displayed to the left of the values). If zero is passed, a default label width is used.
syntaxid	Display template attribute syntax identifier for a list of predefined LDAP_SYN_... values.
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.

Returns

• LDAP_SUCCESS if successful.
• An LDAP error code on error.

Description

ldap_vals2text() produces a text representation of a single set of LDAP attribute values.

See Also

ldap_vals2html()

ldap_value_free()

The ldap_value_free() function frees an array of values from memory.

Syntax

#include <ldap.h>
void ldap_value_free( char **values );

Parameters

ldap_value_free() Function Parameter

Parameter	Description
values	Array of values.

Description

Use the ldap_value_free_len() function if the values are berval structures.

Example

See the example under ldap_get_values().

See Also

ldap_get_values(), ldap_value_free_len

ldap_value_free_len()

The ldap_value_free_len() function frees an array of berval structures from memory.

Syntax

#include <ldap.h>
void ldap_value_free_len( struct berval **values );

Parameters

ldap_value_free_len() Function Parameter

Parameter	Description
values	Array of berval structures.

Description

Use the ldap_value_free() function instead of this function if the values are string values.

Example

See the example under ldap_get_values_len().

See Also

ldap_get_values(), ldap_get_values_len

ldap_version()

#include <ldap.h>
int ldap_version( LDAPVersion *ver );

Parameters

ldap_version() Function Parameter

Parameter	Description
ver	LDAPVersion structure returning version information. If you only want the SDK version, you can pass NULL for this parameter.

Returns

The version number of the LDAP C SDK, multiplied by 100. For example, for version 1.0, the function returns 100.

See Also

ldap_get_option()

ldap_x_calloc()

The ldap_x_calloc() function allocates space for an array of elements.

Syntax

#include <ldap-extension.h>
void *ldap_x_calloc( size_t nelem, size_t elsize );

Parameters

ldap_x_calloc() Function Parameters

Parameter	Description
nelem	Number of elements for which memory is to be allocated.
elsize	Size of each element.

Returns

• If successful, returns a pointer to the space.
• If there is no available memory, returns a NULL pointer.

See Also

ldap_x_free(), ldap_x_malloc() , ldap_x_realloc()

ldap_x_free()

The ldap_x_free() function frees allocated memory.

Syntax

#include <ldap-extension.h>
void ldap_x_free( void *ptr );

Parameters

ldap_x_free() Function Parameter

Parameter	Description
ptr	Pointer to the block of memory to be freed.

See Also

ldap_x_calloc(), ldap_x_malloc(), ldap_x_realloc()

ldap_x_hostlist_first()

The ldap_x_hostlist_first() function returns the first host and port defined in a host list file.

Syntax

#include <ldap-extension.h>
int ldap_x_hostlist_first( char *hostlist, int defport, char **hostp,
  int *portp, struct ldap_x_hostlist_status **statusp );

Description

ldap_x_hostlist_first() parses a space-separated host list (useful for implementing an extended I/O CONNECT callback function) and returns the first host and port defined.

Returns

• LDAP_SUCCESS if successful.
• If unsuccessful returns a valid LDAP API error code.

Note: A NULL or zero-length hostlist causes the host 127.0.0.1 to be returned.

See Also

ldap_x_hostlist_status(), LDAP_X_EXTIOF_CONNECT_CALLBACK(),

ldap_x_hostlist_next()

The ldap_x_hostlist_next() function returns the host and port defined in a host list file following the previous host and port returned.

Syntax

#include <ldap-extension.h>
int ldap_x_hostlist_next( char **hostp, int *portp,
  struct ldap_x_hostlist_status **statusp );

Description

This utility parses a space-separated host list (useful for implementing an extended I/O CONNECT callback function) and returns the host and port defined following the previous host and port returned.

Returns

• LDAP_SUCCESS if successful. If no more

hosts are available, LDAP_SUCCESS is returned but hostp is set to NULL.

• If unsuccessful returns a valid LDAP API error code.

Note: A NULL or zero-length hostlist causes the host 127.0.0.1 to be returned.

See Also

ldap_x_hostlist_status(), LDAP_X_EXTIOF_CONNECT_CALLBACK(),

ldap_x_hostlist_status()

See Also

ldap_x_hostlist_first(), ldap_x_hostlist_next(), LDAP_X_EXTIOF_CONNECT_CALLBACK()

ldap_x_hostlist_statusfree()

See Also

ldap_x_hostlist_first(), ldap_x_hostlist_next(), LDAP_X_EXTIOF_CONNECT_CALLBACK()

ldap_x_malloc()

The ldap_x_malloc() function allocates space for an object.

Syntax

#include <ldap-extension.h>
void *ldap_x_malloc( size_t size );

Parameters

ldap_x_malloc() Function Parameter

Parameter	Description
size	Specifies the size for the allocated block of memory.

See Also

ldap_x_free(), ldap_x_calloc() , ldap_x_realloc()

ldap_x_realloc()

The ldap_x_realloc() function changes the size of a block of memory.

Syntax

#include <ldap-extension.h>
void *ldap_x_realloc( void *ptr, size_t size );

Parameters

ldap_x_realloc() Function Parameter

Parameter	Description
ptr	Pointer to a block of memory.
size	Specifies the new size of the block.

See Also

ldap_x_free(), ldap_x_calloc() , ldap_x_malloc()

prldap_get_default_socket_info()

The prldap_get_default_socket_info() function retrieves default socket information.

Syntax

#include <ldappr.h>
int prldap_get_default_socket_info( LDAP *ld, PRLDAPSocketInfo *soip );

Parameters

prldap_get_default_socket_info() Function Parameters

Parameter	Description
fd	The session handle returned from prldap_init().
soip	Pointer to a structure containing socket specific information.

Returns

• LDAP_SUCCESS if successful.
• An LDAP API error code if an error occurs.
• LDAP_PARAM_ERROR is returned if ld is NULL.

See Also

prldap_set_default_socket_info()

prldap_get_session_info()

The prldap_get_session_info() function retrieves application-specific data.

Syntax

#include <ldappr.h>
int prldap_get_session_info( LDAP *ld, void *sessionarg,
  PRLDAPSessionInfo *seip );

Parameters

prldap_get_session_info() Function Parameters

Parameter	Description
ld	The session handle returned from prldap_init(). If NULL, the functions are installed as the default functions for all new LDAP handles.
seip	Pointer to a structure with session information data.

Returns

• LDAP_SUCCESS if successful.
• An LDAP API error code if an error occurs.

Description

The prldap_get_session_option() function retrieves an option for an LDAP session handle or a session argument that is passed to the CONNECT , POLL, NEWHANDLE, or DISPOSEHANDLE extended I/O callbacks.

See Also

prldap_set_session_info()

prldap_get_session_option()

The prldap_get_session_option() function retrieves an option specific to the prldap layer.

Syntax

#include <ldappr.h>
int prldap_get_session_option( LDAP *ld, void *sessionarg,
  int option, ... );

Returns

• LDAP_SUCCESS if successful.
• An LDAP API error code if an error occurs.

Description

The prldap_get_session_option() function retrieves an option for an LDAP session handle or a session argument that is passed to the CONNECT , POLL, NEWHANDLE, or DISPOSEHANDLE extended I/O callbacks.

See Also

prldap_set_session_option()

prldap_get_socket_info()

The prldap_get_socket_info() function retrieves socket-specific information based on parameters passed to the extended I/O callback functions.

Syntax

#include <ldappr.h>
int prldap_get_socket_info( int fd, void *socketarg,
  PRLDAPSocketInfo *soip );

Parameters

prldap_get_socket_info() Function Parameters

Parameter	Description
fd	The session handle returned from prldap_init().
soip	Pointer to a structure containing socket information data.

Returns

• LDAP_SUCCESS if successful.
• An LDAP API error code if an error occurs.

See Also

prldap_set_socket_info()

prldap_init()

The prldap_init() function creates a new session handle with Netscape Portable Runtime (NSPR) I/O, threading, support for IPv6, and DNS functions installed.

Syntax

#include <ldappr.h>
LDAP * prldap_init( const char *defhost, int defport, int shared );

Parameters

prldap_init() Function Parameters

Parameter	Description
defhost	Space-delimited list of one or more host names (or IP address in dotted notation, such as 192.168.0.99) 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.
shared	Pass a non-zero value if you plan to use this LDAP handle for more than one thread.

Returns

• Pointer to LDAP session handle if successful.
• NULL if an error occurs.

Description

To be able to use LDAP over Internet Protocol, version 6, IPv6, this function should be used rather than ldap_init().

See Also

prldap_install_routines()

prldap_install_routines()

The prldap_install_routines() function installs Netscape Portable Runtime (NSPR) I/O, threading, and DNS functions so they can be used by the LDAP session handle.

Syntax

#include <ldappr.h>
int prldap_install_routines( LDAP *ld, int shared );

Parameters

prldap_install_routines() Function Parameters

Parameter	Description
ld	The session handle returned from prldap_init(). If NULL, the functions are installed as the default functions for all new LDAP handles.
shared	Pass a non-zero value if you plan to use this LDAP handle for more than one thread.

Returns

• LDAP_SUCCESS if successful.
• An LDAP API error code if an error occurs.

See Also

prldap_init()

prldap_set_default_socket_info()

The prldap_set_default_socket_info() function sets default socket information.

Syntax

#include <ldappr.h>
int prldap_set_default_socket_info( LDAP *ld, PRLDAPSocketInfo *soip );

Parameters

prldap_set_default_socket_info() Function Parameters

Parameter	Description
fd	The session handle returned from prldap_init().
soip	Pointer to a structure containing socket specific information.

Returns

• LDAP_SUCCESS if successful.
• LDAP_PARAM_ERROR is returned if ld is NULL.
• An LDAP API error code if an error occurs.

See Also

prldap_get_socket_info()

prldap_set_session_info()

The prldap_set_session_info() function sets application-specific data.

Syntax

#include <ldappr.h>
int prldap_set_session_info( LDAP *ld, void *sessionarg,
  PRLDAPSessionInfo *seip );

Parameters

prldap_set_session_info() Function Parameters

Parameter	Description
ld	The session handle returned from prldap_init().
seip	Pointer to a structure containing session information data.

Returns

• LDAP_SUCCESS if successful.
• An LDAP API error code if an error occurs.

Description

The prldap_set_session_info() function sets application-specific data for an LDAP session handle or a session argument that is passed to the CONNECT, POLL, NEWHANDLE, or DISPOSEHANDLE extended I/O callbacks.

See Also

prldap_get_session_info()

prldap_set_session_option()

The prldap_set_session_option() function sets a session option specific to the prldap layer.

Syntax

#include <ldappr.h>
int prldap_set_session_option( LDAP *ld, void *sessionarg,
  int option, ... );

Parameters

prldap_set_session_option() Function Parameters

Parameter	Description
ld	The session handle returned from prldap_init().
option

Returns

• LDAP_SUCCESS if successful.
• An LDAP API error code if an error occurs.

Description

The prldap_set_session_option() function sets an option for an LDAP session handle or a session argument that is passed to the CONNECT , POLL, NEWHANDLE, or DISPOSEHANDLE extended I/O callbacks.

See Also

prldap_get_session_option()

prldap_set_socket_info()

The prldap_set_socket_info() function sets socket information.

Syntax

#include <ldappr.h>
int prldap_set_socket_info( int fd, void *socketarg,
  PRLDAPSocketInfo *soip );

Parameters

prldap_set_socket_info() Function Parameters

Parameter	Description
fd	The session handle returned from prldap_init().
soip	Pointer to a structure containing socket information data.

Returns

• LDAP_SUCCESS if successful.
• An LDAP API error code if an error occurs.

Description

The prldap_set_socket_info() function sets socket-specific information based on parameters passed to the extended I/O callback functions. For more information, see the ldappr.h header file.

See Also

prldap_get_socket_info()