| Sun Java System LDAP SDK for C Programming Guide |
Chapter 17
Function ReferenceThis chapter contains detailed reference material for each public function of the Sun™ Java System Directory Server Resource Kit LDAP SDK for C. Each reference gives a description of the function, and its usage syntax, parameters and return values. In many cases, an example program is also included. The chapter contains the following sections:
Typographic ConventionsThe general purpose of a function is usually given by its name. Table 17-1 lists the naming conventions used when adding suffixes to function names.
Table 17-1 Function Naming Conventions
Suffix
Description
_ext
Identifies extended functions introduced for LDAPv3. These functions are augmented through additional parameters, as compared to the functions they replace. As LDAPv3 has become widely adopted, it is recommended you use extended functions whenever possible in your new applications. See Table 17-19.
_s
Identifies the synchronous form of functions. A synchronous function will not return until it receives a response from the server, thereby blocking the caller. Similar function names without this suffix are asynchronous, allowing the caller to perform other operations while waiting for a result. (The synchronous and asynchronous forms exist only for functions which involve possible delays due to communication with the LDAP server. Functions which do not involve communication do not use this suffix.) For more information on these options, see "Managing Memory" of Chapter 4, "Using the LDAP API."
Function Summary by TaskIn the following sections, the functions of the LDAP SDK for C are grouped into task categories.
Working with Basic Encoding Rules
The functions listed in Table 17-2 may be used to encode and decode with Basic Encoding Rules (BER). They are often used inside of control and extension values.
Managing LDAP Sessions
The functions listed in Table 17-3 manage the different phases of an LDAP session: initialization, configuration, authentication (binding) and termination (unbinding). These phases are described in more detail in Chapter 3, "Writing an LDAP Client."
Table 17-3 Functions to Manage an LDAP Session
Function
Description
Initializes an LDAP session.
Initializes an LDAP session over SSL.
Initializes a thread-safe session over SSL.
Read and writes the current preference settings for a session.
ldap_memcache_init()
ldap_memcache_set()
ldap_memcache_get()
ldap_memcache_update()
ldap_memcache_flush()
ldap_memcache_destroy()Creates a memory cache and uses it for search results from this session. Manages the data in the cache and frees the memory when the cache is no longer needed. The in-memory cache for search results is a Sun Java System extension to the API.
Ends an LDAP session and frees the associated data structures.
Performing LDAP Operations
The functions listed in Table 17-4 perform LDAP operations on a server and retrieve the results. These operations are covered in Chapter 7, "Adding, Modifying and Deleting Entries," Chapter 8, "Comparing Entries," and Chapter 15, "Extended Operations."
Table 17-4 Functions to Perform Operations on LDAP Server
Function
Description
Adds a new entry to the directory.
Modifies an entry in the directory
Deletes an entry from the directory.
Renames or moves one or more entry(ies).
Searches the directory.
Compares a value with the values of an entry’s attribute.
Checks the results of an asynchronous operation.
Cancels an asynchronous operation.
Performs an LDAPv3 extended operation.
Parses the results of an LDAPv3 extended operation.
Frees the memory used by the data structure for the results.
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.
Specifies the function used to get authentication information when following referrals.
Processing Search Results
Search results are given as a chain of LDAPMessage structures which can contain both entry messages and search reference messages. The functions listed in Table 17-5 retrieve the results of a search operation and process the data structures which are returned. These functions are introduced in "Getting Search Results" of Chapter 5, "Searching a LDAP Directory."
Reading the Contents of an Entry
The functions listed in Table 17-6 are used to access the contents of an entry returned as a search result. These functions are described in "Getting Distinguished Names for Each Entry" and "Getting Attribute Names from an Entry" of Chapter 5, "Searching a LDAP Directory."
Sorting Search Results
With the functions listed in Table 17-7, your LDAP client can sort the data structures returned as search results. These functions are demonstrated in "Sorting Entries by an Attribute" and "Sorting the Values of an Attribute" in Chapter 5, "Searching a LDAP Directory."
Table 17-7 Client-side Sorting Functions
Function
Description
Sorts search results by DN or by a single attribute.
Sorts search results by by multiple attributes
Sorts search results using key(s).
Sorts the values of an attribute.
A case-insensitive comparison function that you can pass to ldap_sort_values().
Sun Java System Directory Server and others also provide server-side sorting through LDAPv3 controls. The controls mechanism is described in Chapter 13, "Working with LDAP Controls," including the following server-side sorting functions which are shown in "Using the Server-Side Sorting Control".
Working with Search Filters
The functions listed in Table 17-9 retrieve and build filters using a filter configuration file. Use this mechanism to create complex filters to pass to the search functions. Filters and filter configuration files are described in Chapter 6, "Using Filter Configuration Files."
Using LDAPv3 Controls
Sun Java System Directory Server and others also provide additional functionality throught LDAPv3 controls. The functions listed in Table 17-10 configure LDAPv3 control structures which ask the server to perform advanced operations. This mechanism is described in Chapter 13, "Working with LDAP Controls."
Table 17-10 Functions to Manage LDAPv3 Controls
Function
Description
ldap_create_persistentsearch_control()
ldap_get_entry_controls()
ldap_parse_entrychange_control()Track changes to an entry or a set of entries by setting the persistent search control and analyzing the entry change control sent by the server.
ldap_create_sort_keylist()
ldap_free_sort_keylist()
ldap_create_sort_control()
ldap_parse_sort_control()Define and send criteria for server-side sorting of search results and check the server’s response
ldap_create_virtuallist_control()
ldap_parse_virtuallist_control()Use in conjuction with server- side sorting to limit and handle the number of results returned to the client.
Define a proxy authorization control to perform an operation under a different bind DN
Parse an LDAP response from the server to extract the result and the response to the control.
Using Sun Java System Extensions
The functions listed in Table 17-11 are utility functions for parsing space-separated host lists. This is useful for implementing an extended I/O CONNECT callback function.
Table 17-11 Sun Java System Extensions
Function
Description
ldap_x_hostlist_first()
ldap_x_hostlist_next()
ldap_x_hostlist_status()Utility functions for parsing space-separated host lists.
Working with LDAP URLs
The functions listed in Table 17-12 interpret LDAP URLs (universal resource locators of the form ldap://...). For additional information, see Chapter 9, "Working with LDAP URLs."
Working with UTF-8 Encoding
The functions listed in Table 17-13 work with strings and characters that use UTF-8 encoding.
Table 17-13 Functions to Handle UTF-8 Encoding
Function
Description
Function to determine bytel length.
Function to get next character.
Function to get previous character.
Function to copy a character to a destination.
Function to return the number of characters.
Function moves the pointer to the next character following a UCS-4 character.
Function moves the pointer to the next character following a UCS-4 character.
ldap_utf8isalnum()
ldap_utf8isalpha()
ldap_utf8isdigit()
ldap_utf8len()
ldap_utf8isspace()Functions to determine characteristics of the character.
Handling Errors
The functions listed in Table 17-14 handle errors returned by the functions. Chapter 18, "Result Codes" lists all of the error and status codes used in the LDAP SDK for C. You can also find details about possible errors in the reference section for each function.
Managing Memory
The functions listed in Table 17-15 free memory allocated by the LDAP SDK for C functions. See Table 4-1 in the "Managing Memory" section of Chapter 4, "Using the LDAP API" for a list of all functions which allocate memory that needs to be freed.
Table 17-15 Functions to Free Memory
Function
Description
Free the memory allocated for a berval structure.
Free the memory of a BerElement structure.
Free the memory of an LDAPControl structure.
Free an array of LDAPControl structures.
Free the memory of a FriendlyMap structure
Free an array of LDAPsortkey structures
Free the memory of an LDAPURLDesc structure
Free the memory of an LDAPFiltDesc structure.
General function for freeing memory of any other data structure
Free an array of LDAPMod structure.
Free the memory of an LDAPMessage structure.
Free the memory allocated for the string values of an attribute.
Free the memory allocated for the binary values of an attribute (an array of berval structures)
You may also manage memory directly with the functions in Table 17-16.
Table 17-16 Functions to Directly Manage Memory
Function
Description
Allocates memory.
Allocates memory for an array of elements.
Changes the size of a memory block.
Frees a block of memory.
Working with Netscape Portable Runtime
The functions listed in Table 17-17 tie libldap into Netscape Portable Runtime (NSPR).
Deprecated and Outdated Functions
The functions listed in first column of Table 17-18 should no longer be used; they have been superceded by the newer functions listed in the second column of Table 17-18. Deprecated functions are those being dropped from the standard or from the Sun Java System extensions to the LDAP SDK for C. Outdated functions are those which are not officially deprecated but which have newer, extended functions for performing the same operation.
Table 17-18 Deprecated Functions and Their Replacement
Deprecated Function
Replacement
Replaced by ber_free().
Replaced by ldap_simple_bind() and ldap_simple_bind_s(), respectively.
Replaced by ldap_create_filter().
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.
Replaced by Description.
Rarely used, no replacement.
Replaced by ldap_modrdn2(), itself outdated by ldap_rename().
Replaced by ldap_modrdn2_s(), itself outdated by ldap_rename_s().
Replaced by ldap_init() and one of the bind functions.
Replaced by ldap_parse_result().
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.
Replaced by ldap_get_option().
Outdated Standard Functions and Equivalents
Many LDAPv2 functions are outdated now that LDAPv3 has been widely adopted. Table 17-19 lists both the outdated function and its new equivalent. Although LDAPv2 functions remain in the standard specification, you should use the LDAPv3 functions in any new client applications. Again, for maintenance reaons, the outdated functions have often been reimplemented to simply call the newer function.
Table 17-19 Outdated LDAPv2 Functions and New Equivalent
LDAPv2 Functions
LDAPv3 Equivalent
ldap_search_ext()
ldap_search_ext_s()
ldap_search_ext_s() - use timeout argumentldap_unbind_ext() replaces both forms which are identical besides the suffix.
Functions Alphabetically
ber_alloc()The ber_alloc() function is used to allocate a new Basic Encoding Rules (BER) BerElement structure.
Syntax
#include <lber.h>
BerElement* ber_alloc( void );Parameters
This function has no parameters.
Returns
- 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_alloc_t()The ber_alloc_t() function constructs and returns a BerElement structure.
Syntax
#include <lber.h>
BerElement* ber_alloc_t( int options );Parameters
This function has the parameter listed in Table 17-20.
Table 17-20 ber_alloc_t() Function Parameter
Parameter
Description
options
Contains bitwise OR of options to be used when generating the encoding of the BerElement. One option is defined and must always be supplied:
#define LBER_USE_DER 0x01
When this option is present, lengths will always be encoded in the minimum number of octets. This option does not cause values of sets and sequences to be rearranged in tag and byte order, so these functions are not suitable for generating DER output as defined in X.509 and X.680.
Returns
- 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_bvecfree()The ber_bvecfree() function frees an array of berval structures.
Syntax
#include <lber.h>
void ber_bvecfree( struct berval **bv );Parameters
This function has the parameter listed in Table 17-21.
Table 17-21 ber_bvecfree() Function Parameter
Parameter
Description
bv
Pointer to the array that you want to free from memory.
Description
Each berval in the array is freed using ber_bvfree(), and then the array itself is freed.
See Also
ber_bvdup()The ber_bvdup() function returns a copy of a berval structure.
Syntax
#include <lber.h>
berval* ber_bvdup( const struct berval *bv );Parameters
This function has the parameter listed in Table 17-22.
Table 17-22 ber_bvdup() Function Parameter
Parameter
Description
bv
Pointer to the berval structure to be duplicated.
Returns
- 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
This function has the parameter listed in Table 17-23.
Table 17-23 ber_bvfree() Function Parameter
Parameter
Description
bv
Pointer to the berval structure that you want to free from memory.
Description
The ber_bvfree() function frees a berval structure from memory. Call this function to free a berval passed back from the ldap_extended_operation_s(), ldap_parse_extended_result(), ldap_sasl_bind_s(), or ldap_parse_sasl_bind_result() functions.
See Also
ldap_extended_operation_s(), ldap_parse_extended_result(), ldap_sasl_bind_s(), ldap_parse_sasl_bind_result()
ber_dup()The ber_dup() function returns a copy of a BerElement structure.
Syntax
#include <lber.h>
BerElement* ber_dup( BerElement *ber );Parameters
This function has the parameters listed in Table 17-24.
Table 17-24 ber_dup() Function Parameter
Parameter
Description
ber
Pointer to the BerElement to be duplicated.
Returns
- 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
This function has the parameters listed in Table 17-25.
Table 17-25 ber_first_element() Function Parameters
Parameter
Description
ber
Pointer to a BerElement.
len
Pointer to the address of the unsigned long which returns the length of the first element.
last
Address of the pointer to return the address of the last byte of the element.
Returns
NULL pointer is returned on error.
Description
The ber_first_element() function is used to return the tag and length of the first element in a set or sequence. It also returns a magic cookie parameter that should be passed to subsequent calls to ber_next_element().
See Also
ber_flatten()The ber_flatten() function allocates a berval structure whose contents are taken from a source BerElement structure.
Syntax
#include <lber.h>
int ber_flatten( BerElement *ber, struct berval **bvPtr );Parameters
This function has the parameters listed in Table 17-26.
Table 17-26 ber_flatten() Function Parameters
Parameter
Description
ber
Pointer to the source BerElement.
bvPtr
Pointer to the newly allocated berval structure which must be freed using ber_bvfree().
Returns
Returns 0 on success and -1 on error.
Description
This function is usually used when encoding LDAPv3 controls or extended operations values.
See Also
ber_free()The ber_free() function frees a BerElement structure previously allocated with ber_alloc(), ber_alloc_t(), ber_init(), or the ldap_first_attribute() and ldap_next_attribute() search functions.
Syntax
#include <ldap.h>
void ber_free( BerElement *ber, int freebuf );Parameters
This function has the parameters listed in Table 17-27.
Table 17-27 ber_free() Function Parameters
Parameter
Description
ber
Pointer to the BerElement structure that you want to free.
freebuf
Specifies whether or not to free the buffer in the BerElement structure.
Description
This function frees a BerElement structure, which is used to keep track of the current attribute. When you are done working with the attributes, you should free this structure from memory, if it still exists.
Note
To retrieve attributes from a search result entry, you need to call either the ldap_first_attribute() or ldap_next_attribute() function. When freeing structures allocated by these functions, you should specify 0 for the freebuf argument. Otherwise, it should always be set to 1.
Example
Code Example 17-1 frees the BerElement structure allocated by the ldap_first_attribute() function.
See Also
ber_alloc(), ber_alloc_t(), ber_init(), ldap_first_attribute(), ldap_next_attribute()
ber_get_boolean()The ber_get_boolean() function is used to read a boolean value.
Syntax
#include <lber.h>
unsigned long ber_get_boolean( BerElement *ber,
int *boolval );Parameters
This function has the parameters listed in Table 17-28.
Table 17-28 ber_get_boolean() Function Parameters
Parameter
Description
ber
Pointer to the BerElement structure that contains the boolean.
boolval
Specifies the boolean to read.
Returns
The value is returned on success and LBER_ERROR (-1) on failure.
ber_get_int()The ber_get_int() function tries to interpret the next element as an integer, returning the result in num.
Syntax
#include <lber.h>
unsigned long ber_get_int( BerElement *ber, int *num );Parameters
This function has the parameters listed in Table 17-29.
Table 17-29 ber_get_int() Function Parameters
Parameter
Description
ber
Pointer to the BerElement structure that contains the boolean.
num
Pointer to the result.
Returns
The tag of whatever it finds is returned on success and LBER_ERROR (-1) on failure.
ber_get_next()The ber_get_next() function reads the next BER element.
Syntax
#include <lber.h>
unsigned long ber_get_next( Sockbuf *sb, unsigned long *len,
BerElement *ber );Parameters
This function has the parameters listed in Table 17-27.
Table 17-30 ber_get_next() Function Parameters
Parameter
Description
sb
Descriptor (socket or file descriptor) from which to read.
len
The length of the entire element.
ber
Pointer to the BerElement structure.
Description
ber_get_next() strips off and returns the leading tag, strips off and returns the length of the entire element, and sets up a pointer to ber for subsequent calls to decode the element.
ber_get_next_buffer()The ber_get_next_buffer() function reads the next BER element from a byte buffer.
Note
This is an older function included in the SDK for backward-compatibility. If you are writing a new LDAP client, use ber_get_next_buffer_ext() instead.
ber_get_next_buffer_ext()The ber_get_next_buffer_ext() function reads the next BER element from a byte buffer.
Note
ber_get_next_buffer_ext() is a new version of the ber_get_next_buffer() function. If you are writing a new LDAP client, use ber_get_next_buffer_ext().
Syntax
#include <lber.h>
unsigned long ber_get_next_buffer_ext( void *buffer,
size_t buffer_size, unsigned long *len, BerElement *ber,
unsigned long *Bytes_Scanned, Sockbuf *sb );Parameters
This function has the parameters listed in Table 17-31.
Table 17-31 ber_get_next_buffer_ext() Function Parameters
Parameter
Description
buffer
Pointer to the buffer.
buffer_size
The size of the buffer.
len
The length of the entire element.
ber
Pointer to a BerElement.
Bytes_Scanned
Returns the number of bytes actually searched through.
sb
Descriptor (socket or file descriptor) from which to read.
ber_get_null()The ber_get_null() function is used to read a NULL element.
Syntax
#include <lber.h>
unsigned long ber_get_null( BerElement *ber );Parameters
This function has the parameter listed in Table 17-32.
Table 17-32 ber_get_null() Function Parameter
Parameter
Description
ber
Pointer to a BerElement.
Returns
Returns the tag of the element it skips over.
ber_get_option()The ber_get_option() function is used to retrieve information about the API and about the specific implementation being used.
Syntax
#include <lber.h>
int ber_get_option( BerElement *ber, int option, void *value );
ber_get_stringa()The ber_get_stringa() function is used to allocate memory space into which an octet string is read.
Syntax
#include <lber.h>
unsigned long ber_get_stringa( BerElement *ber, char **buf );
ber_get_stringal()The ber_get_stringal() function is used to allocate memory space into which an octet string and its length are read.
Syntax
#include <lber.h>
unsigned long ber_get_stringal( BerElement *ber, struct berval **bv );Description
It takes a berval structure, and returns the result in this parameter.
ber_get_stringb()The ber_get_stringb() function is used to read an octet string into a preallocated buffer.
Syntax
#include <lber.h>
unsigned long ber_get_stringb( BerElement *ber, char *buf,
unsigned long *len );Description
The len parameter should be initialized to the size of the buffer, and will contain the length of the octet string read upon return. The buffer should be big enough to take the octet string value plus a terminating NULL byte.
ber_init()The ber_init() function constructs a new BerElement.
Syntax
#include <lber.h>
BerElement * ber_init( const struct berval *bv );Parameters
This function has the parameter listed in Table 17-32.
Table 17-33 ber_init() Function Parameter
Parameter
Description
bv
Pointer to a berval.
Returns
- 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
This function has the parameters listed in Table 17-34.
Table 17-34 ber_next_element() Function Parameters
Parameter
Description
ber
Pointer to a BerElement.
len
Pointer to the address of the unsigned long which returns the length of the next element.
last
Address of the pointer to return the address of the last byte of the element.
Returns
NULL pointer is returned on error.
Description
The ber_next_element() function is used to return the tag and length of the first element in a set or sequence.
See Also
ber_peek_tag()The ber_peek_tag() function returns the tag of the next element to be parsed in the supplied BerElement structure.
Syntax
#include <lber.h>
unsigned long ber_peek_tag( BerElement *ber, unsigned long *len );Parameters
This function has the parameters listed in Table 17-35.
Table 17-35 ber_peek_tag() Function Parameters
Parameter
Description
ber
Pointer to a BerElement.
len
Pointer to the address of the unsigned long which returns the length of the next element.
Returns
Returns the tag of the next element to be read in the BerElement structure. LBER_DEFAULT is returned if there is no further data to be read.
ber_printf()The ber_printf() function encodes a BER element.
Syntax
#include <lber.h>
ber_printf( BerElement *ber, const char *fmt, ... );Parameters
This function has the parameters listed in Table 17-36.
Table 17-36 ber_printf() Function Parameters
Parameter
Description
ber
Pointer to a BerElement returned by ber_alloc() or ber_alloc_t().
fmt
Defines the encoding format string. The format string can contain the following characters:
- -b Boolean. An integer parameter should be supplied. A boolean element is output.
- -i Integer. An integer parameter should be supplied. An integer element is output.
- -B Bitstring. A char * pointer to the start of the bitstring is supplied, followed by the number of bits in the bitstring. A bitstring element is output.
- -n Null. No parameter is required. A NULL element is output.
- -o Octet string. A char * is supplied, followed by the length of the string pointed to. An octet string element is output.
- -s Octet string. A NULL-terminated string is supplied. An octet string element is output, not including the trailing NULL octet.
- -t Tag. An int specifying the tag to give the next element is provided. This works across calls.
- -v Several octet strings. A NULL-terminated array of char *'s is supplied. Note that a construct like '{v}' is required to get an actual sequence of octet strings.
- -{ Begin sequence. No parameter is required.
- -} End sequence. No parameter is required.
- -[ Begin set. No parameter is required.
- -] End set. No parameter is required.
...
Values to be encoded.
Description
State information is kept with the ber parameter so multiple calls can be made to ber_printf() to append things to the end of the BerElement. ber_printf() interprets and formats its arguments according to the format string fmt. Each character in fmt refers to an argument to ber_printf().
Returns
-1 if there is an error during encoding.
ber_put_bitstring()The ber_put_bitstring() function writes a bitstring value to the given BerElement.
Syntax
#include <lber.h>
int ber_put_bitstring( BerElement *ber, char *str,
unsigned long bitlen, unsigned long tag );Description
The ber_put_bitstring() function writes bitlen bits starting at str as a bitstring value to the given BerElement.
ber_put_boolean()The ber_put_boolean() function writes a boolean value to a BerElement.
Syntax
#include <lber.h>
int ber_put_boolean( BerElement *ber, int boolval, unsigned long tag );Description
The boolean value is given by boolval to the BerElement.
ber_put_enum()The ber_put_enum() function writes an enumerated value to a BerElement.
Syntax
#include <lber.h>
int ber_put_enum( BerElement *ber, long num, unsigned long tag );
ber_put_int()The ber_put_int() function writes an integer to a BerElement.
Syntax
#include <lber.h>
int ber_put_int( BerElement *ber, long num, unsigned long tag );
ber_put_null()The ber_put_null() function writes a writes a NULL element to a BerElement.
Syntax
#include <lber.h>
int ber_put_null( BerElement *ber, unsigned long tag );
ber_put_ostring()The ber_put_ostring() function writes bytes to a BerElement as an octet string.
Syntax
#include <lber.h>
int ber_put_ostring( BerElement *ber, char *str,
unsigned long len, unsigned long tag );
ber_put_seq()The ber_put_seq() function puts a sequence to a BerElement.
Syntax
#include <lber.h>
int ber_put_seq( BerElement *ber );Parameters
This function has the parameter listed in Table 17-37.
Table 17-37 ber_put_seq() Function Parameter
Parameter
Description
ber
Pointer to a BerElement.
Description
The ber_start_seq() function is used to start a sequence in the BerElement. The end of the sequence is marked by the nearest matching call to ber_put_seq().
ber_put_set()The ber_put_set() function puts a set to a BerElement.
Syntax
#include <lber.h>
int ber_put_set( BerElement *ber );Parameters
This function has the parameter listed in Table 17-38.
Table 17-38 ber_put_set() Function Parameter
Parameter
Description
ber
Pointer to a BerElement.
Description
The ber_start_set() function is used to start a set in the BerElement. The end of the set is marked by the nearest matching call to ber_put_set().
ber_put_string()The ber_put_string() function writes a NULL-terminated string (minus the terminating 0) to a BerElement as an octet string.
Syntax
#include <lber.h>
int ber_put_string( BerElement *ber, char *str, unsigned long tag );
ber_read()Syntax
#include <lber.h>
long ber_read( BerElement *ber, char *buf, unsigned long len );
ber_reset()Syntax
#include <lber.h>
void ber_reset( BerElement *ber, int was_writing );
ber_scanf()The ber_scanf() function decodes a BerElement.
Syntax
#include <lber.h>
unsigned long ber_scanf( BerElement *ber, const char *fmt, ... );Parameters
This function has the parameters listed in Table 17-39.
Table 17-39 ber_scanf() Function Parameters
Parameter
Description
ber
Pointer to a BerElement as returned by ber_get_next().
fmt
Defines the encoding format string. The format string can contain the following characters:
- -a Octet string. A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, NULL-terminated, and returned in the parameter.
- -s Octet string. A char * buffer should be supplied, followed by a pointer to an integer initialized to the size of the buffer. Upon return, the NULL-terminated octet string is put into the buffer, and the integer is set to the actual size of the octet string.
- -O Octet string. A struct ber_val ** should be supplied, which upon return points to a memory allocated struct berval containing the octet string and its length. Call ber_bvfree() to free allocated memory.
- -b Boolean. A pointer to an integer should be supplied.
- -i Integer. A pointer to an integer should be supplied.
- -B Bitstring. A char ** should be supplied which will point to the memory allocated bits, followed by an unsigned long *, which will point to the length (in bits) of the bitstring returned.
- -n Null. No parameter is required. The element is simply skipped if it is recognized.
- -v Sequence of octet strings. A char *** should be supplied, which upon return points to a memory allocated NULL-terminated array of char *'s containing the octet strings. NULL is returned if the sequence is empty.
- -V Sequence of octet strings with lengths. A struct berval *** should be supplied, which upon return points to a memory allocated, NULL-terminated array of struct berval *'s containing the octet strings and their lengths. NULL is returned if the sequence is empty. ber_bvecfree() can be called to free the allocated memory.
- -x Skip element. The next element is skipped.
- -{ Begin sequence. No parameter is required. The initial sequence tag and length are skipped.
- -} End sequence. No parameter is required and no action is taken.
- -[ Begin set. No parameter is required. The initial set tag and length are skipped.
- -] End set. No parameter is required and no action is taken.
...
Values to be encoded.
Description
ber_scanf() reads from ber, interprets the bytes according to the format string fmt, and stores the results in its additional arguments. The format string contains conversion specifications which are used to direct the interpretation of the BER element.
See Also
ber_set_option()Syntax
#include <lber.h>
int ber_set_option( BerElement *ber, int option, void *value );
ber_set_string_translators()Syntax
#include <lber.h>
unsigned long ber_skip_tag( BerElement *ber, unsigned long *len );
ber_skip_tag()The ber_skip_tag() function advances the pointer to a BerElement past the first tag and length to the next tag.
Syntax
#include <lber.h>
unsigned long ber_skip_tag( BerElement *ber, unsigned long *len );Parameters
This function has the parameters listed in Table 17-40.
Table 17-40 ber_skip_tag() Function Parameters
Parameter
Description
ber
Pointer to a BerElement.
len
Pointer to the length of the value to be skipped.
Description
ber_skip_tag() should only be used with constructed types and situations when a BER encoding is used as the value of an octet string.
See Also
ber_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_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_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_svecfree()Syntax
#include <lber.h>
void ber_svecfree( char **vals );
ber_write()Syntax
#include <lber.h>
long ber_write( BerElement *ber, char *buf,
unsigned long len, int nosos );
ldap_abandon()The ldap_abandon() function cancels an asynchronous LDAP operation that is in progress.
Note
This is an older function included in the SDK for backward-compatibility. If you are writing a new LDAP client, use ldap_abandon_ext() instead.
Syntax
#include <ldap.h>
int ldap_abandon( LDAP *ld, int msgid );Parameters
This function has the parameters listed in Table 17-41.
Table 17-41 ldap_abandon() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
msgid
Message ID of an LDAP operation.
Returns
One of the following values:
- 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
Code Example 17-2 cancels an ldap_url_search() operation, abandoning the results of the operation.
Code Example 17-2 Cancelling an ldap_url_search() Operation
LDAP *ld;
char *url = "ldap://ldap.itd.umich.edu/c=US?o,description? one?o=umich";
int msgid;
...
/* Initiate a search operation */
msgid = ldap_url_search( ld, url, 0 );
...
/* Abandon the search operation */
if ( ldap_abandon( ld, msgid ) != LDAP_SUCCESS ) {
ldap_perror( ld, "ldap_abandon" );
return( 1 );
}
...
See Also
ldap_abandon_ext()The ldap_abandon_ext() function cancels an asynchronous LDAP operation that is in progress.
Note
ldap_abandon_ext() is a new version of the ldap_abandon() function. If you are writing a new LDAP client, use ldap_abandon_ext().
Syntax
#include <ldap.h>
int ldap_abandon_ext( LDAP *ld, int msgid,
LDAPControl **serverctrls, LDAPControl **clientctrls );Parameters
This function has the parameters listed in Table 17-42.
Table 17-42 ldap_abandon_ext() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
msgid
Message ID of an LDAP operation to identify the operation to be cancelled. When you call an asynchronous function (such as ldap_search_ext()), the msgidp argument returns a pointer to a message ID that uniquely identifies the operation. Thus, when you call ldap_abandon_ext(), your LDAP client is able to send a request specifying the message ID of the operation to be cancelled.
serverctrls
Pointer to an array of LDAPControl structures representing LDAP server controls that apply to this operation. If you do not want to pass any server controls, specify NULL for this argument.
clientctrls
Pointer to an array of LDAPControl structures representing LDAP client controls that apply to this operation. If you do not want to pass any client controls, specify NULL for this argument.
Returns
One of the following values:
- 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.
For more information, see "To Cancel an Operation in Progress" of Chapter 4, "Using the LDAP API."
Example
Code Example 17-3 cancels an ldap_url_search() operation, abandoning the results of the operation.
Code Example 17-3 ldap_abandon_ext() Code Example
LDAP *ld;
char *url = "ldap://ldap.itd.umich.edu/c=US?o,description?one?o=umich";
int msgid;
LDAPControl **srvrctrls, **clntctrls;
...
/* Initiate a search operation */
msgid = ldap_url_search( ld, url, 0 );
...
/* Abandon the search operation */
if ( ldap_abandon_ext( ld, msgid, srvrctrls, clntctrls )
!= LDAP_SUCCESS ) {
ldap_perror( ld, "ldap_abandon" );
return( 1 );
}
...
See Also
ldap_add_ext(), ldap_compare_ext(), ldap_delete_ext(), ldap_extended_operation(), ldap_modify_ext(), ldap_rename(), ldap_sasl_bind(), ldap_search_ext(), ldap_simple_bind(), ldap_url_search()
ldap_add()The ldap_add() function adds a new entry to the directory asynchronously.
Note
This is an older function that is included in the SDK for backward-compatibility. If you are writing a new LDAP client, use ldap_add_ext() instead.
Syntax
#include <ldap.h>
int ldap_add( LDAP *ld, const char *dn, LDAPMod **attrs );Parameters
This function has the parameters listed in Table 17-43.
Table 17-43 ldap_add() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
dn
DN of the entry to add. With the exception of the leftmost component, all components of the DN (for example, o=organization or c=country) must already exist.
attrs
Pointer to a NULL-terminated array of pointers to LDAPMod structures representing the attributes of the new entry.
Returns
The message ID of the ldap_add() operation.
Note
To check the result of this operation, call ldap_result() and ldap_result2error(). See ldap_add_ext_s() for a list of possible result codes for the LDAP add operation.
Description
Please use the newer version of this function, ldap_add_ext().
Example
Code Example 17-4 adds a new entry to the directory.
Code Example 17-4 ldap_add() Code Example
#include <ldap.h>
...
LDAP *ld;
LDAPMod *list_of_attrs[4];
LDAPMod attribute1, attribute2, attribute3;
LDAPMessage *result;
int msgid, rc;
struct timeval tv;
/* Distinguished name of the new entry. Note that "dc=example,dc=com" and "ou=People,dc=example,dc=com" must already exist in the directory. */
char *dn = "uid=bjensen,ou=People,dc=example,dc=com";
/* To add a "person" entry, you must specify values for the sn, cn, and objectClass attributes. (These are required attributes.) */
char *sn_values[] = { "Jensen", NULL };
/* To specify multiple values for an attribute, add the different values to the array. */
char *cn_values[] = { "Barbara Jensen", "Babs Jensen", NULL };
/* The object class for a "person" entry is "inetOrgPerson", which is a subclass of "top", "person", and "organizationalPerson". You should add all of these classes as values of the objectClass attribute. */
char *objectClass_values[] = { "top", "person", "organizationalPerson", "inetOrgPerson", NULL };
...
/* Specify the value and type of each attribute in separate LDAPMod structures */
attribute1.mod_type = "sn";
attribute1.mod_values = sn_values;
attribute2.mod_type = "cn";
attribute2.mod_values = cn_values;
attribute3.mod_type = "objectClass";
attribute3.mod_values = objectClass_values;
/* Add the pointers to these LDAPMod structures to an array */
list_of_attrs[0] = &attribute1;
list_of_attrs[1] = &attribute2;
list_of_attrs[2] = &attribute3;
list_of_attrs[3] = NULL;
...
/* Set up the timeout period for adding the new entry */
tv.tv_sec = tv.tv_usec = 0;
/* Add the user "Barbara Jensen" */
if ( ( msgid = ldap_add( ld, dn, list_of_attrs ) ) == -1 ) {
ldap_perror( ld, "ldap_add" );
return( 1 );
}
/* Check to see if the operation has completed */
while ( ( rc = ldap_result( ld, msgid, 0, &tv, &result ) ) == 0 ) {
...
/* do other work while waiting for the operation to complete */
...
}
/* Check the result to see if any errors occurred */
if (( rc = ldap_result2error( ld, result, 1 )) != LDAP_SUCCESS ) {
printf( "Error while adding entry: %s\n", ldap_err2string( rc ));
}
...
See Also
ldap_add_ext()The ldap_add_ext() function adds a new entry to the directory asynchronously.
Note
ldap_add_ext() is a new version of the ldap_add() function. If you are writing a new LDAP client, use ldap_add_ext().
Syntax
#include <ldap.h>
int ldap_add_ext( LDAP *ld, const char *dn, LDAPMod **attrs,
LDAPControl **serverctrls, LDAPControl **clientctrls,
int *msgidp );Parameters
This function has the parameters listed in Table 17-44.
Table 17-44 ldap_add_ext() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
dn
DN of the entry to add. With the exception of the leftmost component, all components of the DN (for example, o=organization or c=country) must already exist.
attrs
Pointer to a NULL-terminated array of pointers to LDAPMod structures representing the attributes of the new entry.
serverctrls
Pointer to an array of LDAPControl structures representing LDAP server controls that apply to this operation. If you do not want to pass any server controls, specify NULL for this argument.
clientctrls
Pointer to an array of LDAPControl structures representing LDAP client controls that apply to this operation. If you do not want to pass any client controls, specify NULL for this argument.
msgidp
Pointer to an integer that will be set to the message ID of the LDAP operation.
Returns
One of the following values:
- LDAP_SUCCESS if successful.
- LDAP_PARAM_ERROR if any of the arguments are invalid.
- LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request.
- LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.
- LDAP_NO_MEMORY if memory cannot be allocated.
- LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAPv3. Make sure that you set the version of your LDAP client to version 3 before calling this function. For details, see "Specifying the LDAP Version of Your Client" of Chapter 3, "Writing an LDAP Client."
Description
The ldap_add_ext() adds a new entry to the directory. To add a new entry to the directory, you need to specify:
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.
For additional information on adding new entries to the directory, see "Adding an Entry" of Chapter 7, "Adding, Modifying and Deleting Entries."
Example
See Code Example 4-7 of Chapter 4, "Using the LDAP API."
See Also
ldap_add_ext_s(), ldap_result(), ldap_parse_result(), LDAPMod
ldap_add_ext_s()The ldap_add_ext_s() function adds a new entry to the directory synchronously.
Note
ldap_add_ext_s() is a new version of the ldap_add_s() function. If you are writing a new LDAP client, use ldap_add_ext_s().
Syntax
#include <ldap.h>
int ldap_add_ext_s( LDAP *ld, const char *dn, LDAPMod **attrs,
LDAPControl **serverctrls, LDAPControl **clientctrls );Parameters
This function has the parameters listed in Table 17-45.
Table 17-45 ldap_add_ext_s() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
dn
DN of the entry to add. With the exception of the leftmost component, all components of the DN (for example, o=organization or c=country) must already exist.
attrs
Pointer to a NULL-terminated array of pointers to LDAPMod structures representing the attributes of the new entry.
serverctrls
Pointer to an array of LDAPControl structures representing LDAP server controls that apply to this operation. If you do not want to pass any server controls, specify NULL for this argument.
clientctrls
Pointer to an array of LDAPControl structures representing LDAP client controls that apply to this operation. If you do not want to pass any client controls, specify NULL for this argument.
Returns
One of the following values:
- LDAP_SUCCESS if successful.
- LDAP_PARAM_ERROR if any of the arguments are invalid.
- LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request.
- LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.
- LDAP_NO_MEMORY if memory cannot be allocated.
- LDAP_LOCAL_ERROR if an error occurred when receiving the results from the server.
- LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded results from the server.
- LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAPv3. Make sure that you set the version of your LDAP client to version 3 before calling this function. For details, see "Specifying the LDAP Version of Your Client" of Chapter 3, "Writing an LDAP Client."
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().
For additional information on adding new entries to the directory, see "Adding an Entry" of Chapter 7, "Adding, Modifying and Deleting Entries."
Example
See Code Example 7-8 of Chapter 7, "Adding, Modifying and Deleting Entries."
See Also
ldap_add_s()The ldap_add_s() function adds a new entry to the directory synchronously.
Note
This is an older function that is included in the SDK for backward-compatibility. If you are writing a new LDAP client, use ldap_add_ext_s() instead.
Syntax
#include <ldap.h>
int ldap_add_s( LDAP *ld, const char *dn, LDAPMod **attrs );Parameters
This function has the parameters listed in Table 17-46.
Table 17-46 ldap_add_s() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
dn
DN of the entry to add. With the exception of the leftmost component, all components of the DN (for example, o=organization or c=country) must already exist.
attrs
Pointer to a NULL-terminated array of pointers to LDAPMod structures representing the attributes of the new entry.
Returns
See ldap_add_ext_s() for a list of possible return codes.
Description
Please use the newer version of this function, ldap_add_ext_s().
Example
Code Example 17-5 adds a new entry to the directory.
Code Example 17-5 ldap_add_s Code Example
#include <ldap.h>
...
LDAP *ld;
LDAPMod *list_of_attrs[4];
LDAPMod attribute1, attribute2, attribute3;
/* Distinguished name of the new entry. Note that "dc=example,dc=com" and "ou=People,dc=example,dc=com" must already exist in the directory. */
char *dn = "uid=bjensen,ou=People,dc=example, dc=com";
/* To add a "person" entry, you must specify values for the sn, cn, and objectClass attributes. (These are required attributes.) */
char *sn_values[] = { "Jensen", NULL };
/* To specify multiple values for an attribute, add the different values to the array. */
char *cn_values[] = { "Barbara Jensen", "Babs Jensen", NULL };
/* The object class for a "person" entry is "inetOrgPerson", which is a subclass of "top", "person", and "organizationalPerson". You should add all of these classes as values of the objectClass attribute. */
char *objectClass_values[] = { "top", "person", "organizationalPerson", "inetOrgPerson", NULL };
...
/* Specify the value and type of each attribute in separate LDAPMod structures */
attribute1.mod_type = "sn";
attribute1.mod_values = sn_values;
attribute2.mod_type = "cn";
attribute2.mod_values = cn_values;
attribute3.mod_type = "objectClass";
attribute3.mod_values = objectClass_values;
/* Add the pointers to these LDAPMod structures to an array */
list_of_attrs[0] = &attribute1;
list_of_attrs[1] = &attribute2;
list_of_attrs[2] = &attribute3;
list_of_attrs[3] = NULL;
...
/* Add the user "Barbara Jensen" */
if ( ldap_add_s( ld, dn, list_of_attrs ) != LDAP_SUCCESS ) {
ldap_perror( ld, "ldap_add_s" );
return( 1 );
}
...
See Also
ldap_ber_free()The ldap_ber_free() function frees a BerElement structure from memory.
Note
This is an older function that is included in the SDK for backward-compatibility. If you are writing a new LDAP client, use ber_free() instead. Except in name, the two functions are identical.
Syntax
#include <ldap.h>
void ldap_ber_free( BerElement *ber, int freebuf );Parameters
This function has the parameters listed in Table 17-47.
Table 17-47 ldap_ber_free() Function Parameters
Parameter
Description
ber
Pointer to the BerElement structure that you want to free.
freebuf
Specifies whether or not to free the buffer in the BerElement structure.
Description
Please use the newer version of this function, ber_free().
See Also
ldap_bind()
Caution
This function is deprecated and should not be used. It is included in ldap-deprecated.h for backward-compatibility. Please use ldap_simple_bind().
ldap_bind() can be used when the authentication method being used needs to be selected at runtime.
Syntax
#include <ldap-deprecated.h>
ldap_bind( LDAP *ld, const char *who, const char *passwd, int method );Parameters
This function has the parameters listed in Table 17-48.
Table 17-48 ldap_bind() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
who
DN of the user who wants to authenticate. For anonymous authentication, set this or the passwd argument to NULL.
passwd
Password of the user who wants to authenticate. For anonymous authentication, set this or the who argument to NULL.
method
Defines the authentication method to be used. It should be set to LDAP_AUTH_SIMPLE to select simple authentication.
Returns
ldap_bind() returns the message ID of the request it initiates.
Description
This is an asynchronous function that authenticates a specified entry to the directory. After a connection is made to an LDAP server using ldap_open(), a bind operation must be performed before other operations can be attempted over the conection.
See Also
ldap_open(), ldap_init(), ldap_bind_s()
ldap_bind_s()
Caution
This function is deprecated and should not be used. It is included in ldap-deprecated.h for backward-compatibility. Please use ldap_simple_bind_s().
ldap_bind_s() can be used when the authentication method needs to be selected at runtime.
Syntax
#include <ldap-deprecated.h>
ldap_bind_s( LDAP *ld, const char *who, const char *cred, int method );Parameters
This function has the parameters listed in Table 17-49.
Table 17-49 ldap_bind_s() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
who
DN of the user who wants to authenticate. For anonymous authentication, set this or the passwd argument to NULL.
cred
Password of the user who wants to authenticate. For anonymous authentication, set this or the who argument to NULL.
method
Defines the authentication method to be used. It should be set to LDAP_AUTH_SIMPLE to select simple authentication.
Returns
ldap_bind_s() returns an LDAP error indication.
Description
This is a synchronous function that authenticates a specified entry to the directory. After a connection is made to an LDAP server using ldap_open(), a bind operation must be performed before other operations can be attempted over the conection
See Also
ldap_open(), ldap_init() , ldap_bind()
ldap_build_filter()
Caution
This function is deprecated and should not be used. It is included in ldap-deprecated.h for backward-compatibility. Please use ldap_create_filter().
See Also
ldap_cache_flush()
Caution
This function is deprecated and should not be used. It is included in ldap-deprecated.h for backward-compatibility. Please use the ldap_memcache_* functions.
For more specific information, see the header file ldap-deprecated.h.
See Also
ldap_memcache_init(), ldap_memcache_set(), ldap_memcache_get(), ldap_memcache_update(), ldap_memcache_flush(), ldap_memcache_destroy()
ldap_charray_add()
Caution
This function is deprecated and should not be used. It is included in ldap-to-be-deprecated.h for backward-compatibility.
For more specific information, see the header file ldap-to-be-deprecated.h.
ldap_charray_dup()
Caution
This function is deprecated and should not be used. It is included in ldap-to-be-deprecated.h for backward-compatibility.
For more specific information, see the header file ldap-to-be-deprecated.h.
ldap_charray_free()
Caution
This function is deprecated and should not be used. It is included in ldap-to-be-deprecated.h for backward-compatibility.
For more specific information, see the header file ldap-to-be-deprecated.h.
ldap_charray_inlist()
Caution
This function is deprecated and should not be used. It is included in ldap-to-be-deprecated.h for backward-compatibility.
For more specific information, see the header file ldap-to-be-deprecated.h.
ldap_charray_merge()
Caution
This function is deprecated and should not be used. It is included in ldap-to-be-deprecated.h for backward-compatibility.
For more specific information, see the header file ldap-to-be-deprecated.h.
ldap_charray_position()
Caution
This function is deprecated and should not be used. It is included in ldap-to-be-deprecated.h for backward-compatibility.
For more specific information, see the header file ldap-to-be-deprecated.h.
ldap_compare()The ldap_compare() function asynchronously determines if an attribute of an entry contains a specified value.
Note
This is an older function that is included in the SDK for backward-compatibility. If you are writing a new LDAP client, use ldap_compare_ext() instead.
Syntax
#include <ldap.h>
int ldap_compare( LDAP *ld, const char *dn, const char *attr,
const char *value );Parameters
This function has the parameters listed in Table 17-50.
Table 17-50 ldap_compare() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
dn
DN of the entry used in the comparison.
attr
Attribute type that you want to check the value against.
value
Value that you want to compare against the attribute values.
Returns
Returns the message ID of the ldap_compare() operation.
Note
To check the result of this operation, call ldap_result() and ldap_result2error(). See ldap_compare_ext_s() function for a list of possible result codes for the LDAP compare operation.
Description
Please use the newer version of this function, ldap_compare_ext().
Example
Code Example 17-6 checks to see if Barbara Jensen has the e-mail address bjensen@example.com.
Code Example 17-6 ldap_compare() Code Sample
#include <stdio.h>
#include <ldap.h>
...
LDAP *ld;
char *dn = "uid=bjensen,ou=People,dc=example, dc=com";
int msgid;
...
msg_id = ldap_compare( ld, dn, "mail", "bjensen@example.com" );
...
See Also
ldap_compare_ext()The ldap_compare_ext() function asynchronously determines if an attribute of an entry contains a specified value.
Note
ldap_compare_ext() is a new version of the ldap_compare() function. If you are writing a new LDAP client, use ldap_compare_ext().
Syntax
#include <ldap.h>
int ldap_compare_ext( LDAP *ld, const char *dn, const char *attr,
struct berval *bvalue, LDAPControl **serverctrls,
LDAPControl **clientctrls, int *msgidp );Parameters
This function has the parameters listed in Table 17-51.
Table 17-51 ldap_compare_ext() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
dn
DN of the entry used in the comparison.
attr
Attribute type that you want to check the value against.
value
Value that you want to compare against the attribute values.
serverctrls
Pointer to an array of LDAPControl structures representing LDAP server controls that apply to this operation. If you do not want to pass any server controls, specify NULL for this argument.
clientctrls
Pointer to an array of LDAPControl structures representing LDAP client controls that apply to this operation. If you do not want to pass any client controls, specify NULL for this argument.
msgidp
Pointer to an integer that will be set to the message ID of the LDAP operation.
Returns
One of the following values:
- LDAP_SUCCESS if successful.
- LDAP_PARAM_ERROR if any of the arguments are invalid.
- LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request.
- LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.
- LDAP_NO_MEMORY if memory cannot be allocated.
- LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAPv3. Make sure that you set the version of your LDAP client to version 3 before calling this function. For details, see "Specifying the LDAP Version of Your Client" of Chapter 3, "Writing an LDAP Client."
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().
For additional information on comparing attribute values in an entry, see Chapter 8, "Comparing Entries."
Example
See Code Example 8-4 of Chapter 8, "Comparing Entries."
See Also
ldap_compare_ext_s(), ldap_result(), ldap_parse_result()
ldap_compare_ext_s()The ldap_compare_ext_s() function synchronously determines if an attribute of an entry contains a specified value.
Syntax
#include <ldap.h>
int ldap_compare_ext_s( LDAP *ld, const char *dn,
const char *attr, struct berval *bvalue,
LDAPControl **serverctrls, LDAPControl **clientctrls );Parameters
This function has the parameters listed in Table 17-52.
Table 17-52 ldap_compare_ext_s() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
dn
DN of the entry used in the comparison.
attr
Attribute type that you want to check the value against.
value
Value that you want to compare against the attribute values.
serverctrls
Pointer to an array of LDAPControl structures representing LDAP server controls that apply to this operation. If you do not want to pass any server controls, specify NULL for this argument.
clientctrls
Pointer to an array of LDAPControl structures representing LDAP client controls that apply to this operation. If you do not want to pass any client controls, specify NULL for this argument.
Returns
One of the following values:
- LDAP_COMPARE_TRUE if the entry contains the attribute value.
- LDAP_COMPARE_FALSE if the entry does not contain the attribute value.
- LDAP_PARAM_ERROR if any of the arguments are invalid.
- LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request.
- LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.
- LDAP_NO_MEMORY if memory cannot be allocated.
- LDAP_LOCAL_ERROR if an error occurred when receiving the results from the server.
- LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded results from the server.
- LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAPv3. Make sure that you set the version of your LDAP client to version 3 before calling this function. For details, see "Specifying the LDAP Version of Your Client" of Chapter 3, "Writing an LDAP Client."
Description
The ldap_compare_ext_s() function compares the value of an attribute in an entry against a specified value. ldap_compare_ext_s() is a synchronous function, which directly returns the results of the operation. If you want to perform other operations while waiting for the results of this operation, call the asynchronous function ldap_compare_ext().
For additional information on comparing attribute values in an entry, see Chapter 8, "Comparing Entries."
Example
See Code Example 8-2 of Chapter 8, "Comparing Entries."
See Also
ldap_compare_s()The ldap_compare_s() function synchronously determines if an attribute of an entry contains a specified value.
Note
This is an older function that is included in the SDK for backward-compatibility. If you are writing a new LDAP client, use ldap_compare_ext_s() instead.
Syntax
#include <ldap.h>
int ldap_compare_s( LDAP *ld, const char *dn,
const char *attr, const char *value );Parameters
This function has the parameters listed in Table 17-53.
Table 17-53 ldap_compare_s() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
dn
DN of the entry used in the comparison.
attr
Attribute type that you want to check the value against.
value
Value that you want to compare against the attribute values.
Returns
For a list of the possible result codes for an LDAP compare operation, see ldap_compare_ext_s().
Description
Please use the newer version of this function, ldap_compare_ext_s().
Example
Code Example 17-7 checks to see if Barbara Jensen has the e-mail address bjensen@example.com.
Code Example 17-7 ldap_compare_s() Code Sample
#include <stdio.h>
#include <ldap.h>
LDAP *ld;
char *dn = "uid=bjensen,ou=People,dc=example, dc=com";
int has_value;
...
has_value = ldap_compare_s( ld, dn, "mail", "bjensen@example.com" );
switch ( has_value ) {
case LDAP_COMPARE_TRUE:
printf( "The mail attribute contains bjensen@example.com.\n");
break;
case LDAP_COMPARE_FALSE:
printf( "The mail attribute does not contain bjensen@example.com.\n");
break;
default:
ldap_perror( ld, "ldap_compare_s" );
return( 1 );
}
...
See Also
ldap_control_free()The ldap_control_free() function frees an LDAPControl structure from memory.
Syntax
#include <ldap.h>
void ldap_control_free( LDAPControl *ctrl );Parameters
This function has the parameter listed in Table 17-54.
Table 17-54 ldap_control_free() Function Parameter
Parameter
Description
ctrl
Pointer to an LDAPControl structure that you want to free from memory.
Description
The ldap_control_free() function frees an LDAPControl structure from memory. You should call this function to free controls that you create; for example, if you call the ldap_create_sort_control() function.
See Also
ldap_controls_free()The ldap_controls_free() function frees an array of LDAPControl structures from memory.
Syntax
#include <ldap.h>
void ldap_controls_free( LDAPControl **ctrls );Parameters
This function has the parameter listed in Table 17-55.
Table 17-55 ldap_controls_free() Function Parameter
Parameter
Description
ctrls
Pointer to an array of LDAPControl structures that you want to free from memory.
Description
The ldap_controls_free() function frees an array of LDAPControl structures from memory. You should call this function to free arrays of controls that you create or any arrays returned by ldap_parse_result().
See Also
ldap_control_free(), ldap_parse_result()
ldap_count_entries()The ldap_count_entries() function returns the number of LDAPMessage structures representing directory entries in a chain of search results.
Syntax
#include <ldap.h>
int ldap_count_entries( LDAP *ld, LDAPMessage *result );Parameters
This function has the parameters listed in Table 17-56.
Table 17-56 ldap_count_entries() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
result
Chain of search results, represented by pointer to an LDAPMessage structure.
Returns
One of the following values:
- 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.
Note
If you pass in a pointer to an LDAPMessage structure in the middle of the chain of results, the function counts only the entries between that structure and the last structure in the chain. In this type of situation, the function does not return the count of all entries in the chain.
For more information on using this function, see "Getting Search Results" of Chapter 5, "Searching a LDAP Directory."
Example
See the examples under ldap_search_ext() and ldap_search_ext_s().
See Also
ldap_result(), ldap_search_ext(), ldap_search_ext_s(), ldap_first_entry(), ldap_next_entry(), ldap_first_entry(), ldap_next_message()
ldap_count_messages()The ldap_count_messages() function returns the number of LDAPMessage structures in a chain of search results.
Syntax
#include <ldap.h>
int ldap_count_messages( LDAP *ld, LDAPMessage *res );Parameters
This function has the parameters listed in Table 17-57.
Table 17-57 ldap_count_messages() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
result
Chain of search results, represented by pointer to an LDAPMessage structure.
Returns
One of the following values:
- 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.
For more information on using this function, see "Getting Search Results" of Chapter 5, "Searching a LDAP Directory."
Example
See the examples under ldap_search_ext() and ldap_search_ext_s().
See Also
ldap_result(), ldap_search_ext(), ldap_search_ext_s(), ldap_first_message(), ldap_next_message(), ldap_first_entry(), ldap_next_entry(), ldap_first_reference(), ldap_next_reference()
ldap_count_references()The ldap_count_references() function returns the number of LDAPMessage structures representing search references in a chain of search results.
Syntax
#include <ldap.h>
int ldap_count_references( LDAP *ld, LDAPMessage *res );Parameters
This function has the parameters listed in Table 17-58.
Table 17-58 ldap_count_references() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
result
Chain of search results, represented by pointer to an LDAPMessage structure.
Returns
One of the following values:
- The number of LDAPMessage structures of the type LDAP_RES_SEARCH_REFERENCE in a chain of search results, if successful. (If there are no structures of this type, returns 0.)
- -1 if ld is not a valid connection handle.
Description
The ldap_count_references() function returns the number of LDAPMessage structures representing search references in a chain of search results. These messages have the type LDAP_RES_SEARCH_REFERENCE.
Note
If you pass in a pointer to an LDAPMessage structure in the middle of the chain of results, the function counts only the references between that structure and the last structure in the chain. In this type of situation, the function does not return the count of all references in the chain.
For more information on using this function, see "Getting Search Results" of Chapter 5, "Searching a LDAP Directory."
Example
See the examples under ldap_search_ext() and ldap_search_ext_s().
See Also
ldap_result(), ldap_search_ext(), ldap_search_ext_s(), ldap_first_reference(), ldap_next_reference()
ldap_count_values()The ldap_count_values() function returns the number of values in an array of strings.
Note
Use the ldap_count_values_len() function if the array contains berval structures.
Syntax
#include <ldap.h>
int ldap_count_values( char **values );Parameters
This function has the parameter listed in Table 17-59.
Returns
One of the following values:
See Chapter 18, "Result Codes" for a complete listing.
Description
For additional information, see "Getting the Values of an Attribute" of Chapter 5, "Searching a LDAP Directory."
Example
Code Example 17-8 counts the number of values assigned to an attribute.
Code Example 17-8 ldap_count_values() Code Example
#include <ldap.h>
...
LDAP *ld;
LDAPMessage *e;
char *a="cn";
char **vals;
int count;
...
/* Get the values of the cn attribute */
vals = ldap_get_values( ld, e, a );
/* Count the values of the attribute */
count = ldap_count_values( vals );
...
See Also
ldap_count_values_len(), ldap_get_values()
ldap_count_values_len()The ldap_count_values_len() function returns the number of values in an array of berval structures.
Note
Use the ldap_count_values() function if the array contains strings.
Syntax
#include <ldap.h>
int ldap_count_values_len( struct berval **vals );Parameters
This function has the parameter listed in Table 17-60.
Table 17-60 ldap_count_values_len() Function Parameter
Parameter
Description
values
Array of berval structures.
Returns
One of the following values:
See Chapter 18, "Result Codes" for a complete listing.
Description
For additional information, see "Getting the Values of an Attribute" of Chapter 5, "Searching a LDAP Directory."
Example
Code Example 17-9 counts the number of values assigned to an attribute.
Code Example 17-9 ldap_count_values_len() Code Example
#include <ldap.h>
LDAP *ld;
LDAPMessage *e;
char *a="jpegPhoto";
struct berval **bvals;
int count;
...
/* Get the values of the jpegPhoto attribute */
bvals = ldap_get_values_len( ld, e, a );
/* Count the values of the attribute */
count = ldap_count_values_len( vals );
...
See Also
ldap_count_values(), ldap_get_values_len()
ldap_create_filter()The ldap_create_filter() routine constructs an LDAP search filter.
Syntax
#include <ldap.h>
int ldap_create_filter( char *buf, unsigned long buflen,
char *pattern, char *prefix, char *suffix, char *attr,
char *value, char **valwords );Parameters
This function has the parameters listed in Table 17-61.
Table 17-61 ldap_create_filter() Function Parameters
Parameter
Description
buf
Buffer to contain the constructed filter.
buflen
Size of the buffer.
pattern
Pattern for the filter.
prefix
Prefix to prepend to the filter. (NULL if not used.)
suffix
Suffix to append to the filter. (NULL if not used.)
attr
Replaces %a in the pattern.
value
Replaces %v in the pattern.
valwords
Replaces %vM through %vN in the pattern.
Returns
One of the following values:
- 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.
Description
For more information about filters, see "Creating Filters Programmatically" of Chapter 6, "Using Filter Configuration Files."
Example
Code Example 17-10 builds the filter (mail=bjensen@example.com).
Code Example 17-10 Creating a Filter with ldap_create_filter()
char buf[LDAP_FILT_MAXSIZ];
char *pattern = "(%a=%v)";
char *attr = "mail";
char *value = "bjensen@example.com";
...
ldap_create_filter( buf, LDAP_FILT_MAXSIZ, pattern, NULL,
NULL, attr, value, NULL );
...
See Also
ldap_init_getfilter(), ldap_init_getfilter_buf(), ldap_getfirstfilter(), ldap_getnextfilter(), ldap_set_filter_additions()
ldap_create_persistentsearch_control()The ldap_create_persistentsearch_control() function creates a control that allows your client to perform a search of an LDAP v3 server that continues without termination until your client abandons it.
Note
Persistent search is an optional feature; it may not be supported on all LDAP servers. In order for the control to work, the server that you are connecting to must support the server control for persistent searches (OID 2.16.840.1.113730.3.4.3, or LDAP_CONTROL_PERSISTENTSEARCH, as defined in the ldap.h header file). See "Determining Supported Controls" of Chapter 13, "Working with LDAP Controls"for information on determining the controls supported by a server.
Syntax
#include <ldap.h>
int ldap_create_persistentsearch_control( LDAP *ld,
int changetypes, int changesonly, int return_echg_ctls,
char ctl_iscritical, LDAPControl **ctrlp );Parameters
This function has the parameters listed in Table 17-62.
Table 17-62 ldap_create_persistentsearch_control() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
changetypes
Specifies the types of changes that you want to keep track of. This field can have one or more of the following values:
- LDAP_CHANGETYPE_ADD specifies that you want to keep track of entries added to the directory.
- LDAP_CHANGETYPE_DELETE specifies that you want to keep track of entries deleted from the directory.
- LDAP_CHANGETYPE_MODIFY specifies that you want to keep track of entries that are modified.
- LDAP_CHANGETYPE_MODDN specifies that you want to keep track of entries that are renamed.
- LDAP_CHANGETYPE_ANY specifies that you want to keep track of all of the above changes to the directory.
You can OR the values together to specify multiple types.
changesonly
Specifies whether or not you want skip the initial search and only get the latest changes as they occur:
return_echg_ctls
Specifies whether or not entry controls are included with each entry returned to your client:
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_geteffectiveRights_control()The ldap_create_geteffectiveRights_control() function allows a user (with correct privileges) to query about the access rights another identity has on one or more entries in the directory.
Syntax
#include <ldap-extension.h>
int ldap_create_geteffectiveRights_control( LDAP *ld, char *authzid,
char *attrlist, char ctl_iscritical, LDAPControl **ctrlp);Parameters
This function has the parameters listed in Table 17-63.
Table 17-63 ldap_create_geteffectiveRights_control() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
authzid
The DN of the identity for which you are checking access rights.
attrlist
A comma-separated list of access rights to determine.
ctl_iscritical
Specifies whether the control is critical to the operation.
- If non-zero, the control is critical to the operation. If the server does not support it, the server will return an LDAP_UNAVAILABLE_CRITICAL_EXTENSION error.
- If 0, the control is not critical to the operation. Even if the server does not support the control, the operation is still attempted and the control is ignored.
ctrlp
Pointer to an LDAPControl structure created by this function. When you are done using this control, you should free it by calling ldap_control_free().
Description
Typically, this control is used in an LDAP search request where the base, the scope, the filter and the attributes will determine the entries to return the access rights.
ldap_create_proxiedauth_control()The ldap_create_proxiedauth_control() function creates an LDAPv3 control that allows a bound entity to assume the identity of another directory entry.
Note
ldap_create_proxiedauth_control() is a new version of the ldap_create_proxyauth_control() function. If you are writing a new LDAP client, use ldap_create_proxiedauth_control().
Syntax
#include <ldap.h>
int ldap_create_proxiedauth_control( LDAP *ld, char *authzid,
LDAPControl **ctrlp);Parameters
This function has the parameters listed in Table 17-64.
Table 17-64 ldap_create_proxiedauth_control() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
authzid
The string representing the identity to assume for the access rights, defined in the format specified by the following Augmented Backus-Naur Form (ABNF) (copied from RFC 2829):
; Specific predefined authorization (authz) id schemes are
; defined below -- new schemes may be defined in the future.authzId = dnAuthzId / uAuthzId
; distinguished-name-based authz id.
dnAuthzId = "dn:" dn
dn = utf8string ; with syntax defined in RFC 2253; unspecified userid, UTF-8 encoded.
uAuthzId = "u:" userid
userid = utf8string ; syntax unspecifiedctrlp
Pointer to an LDAPControl structure created by this function. When you are done using this control, you should free it by calling ldap_control_free().
Description
More information on proxy authorization can be found in the LDAP Proxied Authorization Control Internet Draft (http://ietfreport.isoc.org/ids/draft-weltman-ldapv3-proxy-12.txt).
Note
Proxy authorization is an optional feature; it may not be supported on all LDAP servers. In order for the control to work, the server that you are connecting to must support the server control for proxy authorization (OID 2.16.840.1.113730.3.4.18, or LDAP_CONTROL_PROXIEDAUTH, as defined in the ldap-extension.h header file). See "Determining Supported Controls" of Chapter 13, "Working with LDAP Controls"for information on determining the controls supported by a server.
ldap_create_proxyauth_control()The ldap_create_proxyauth_control() function creates an LDAPv3 control that allows a bound entity to assume the identity of another directory entry.
Note
This is an older function that is included in the SDK for backward-compatibility. If you are writing a new LDAP client, use ldap_create_proxiedauth_control().
Syntax
#include <ldap.h>
int ldap_create_proxyauth_control( LDAP *ld, char *DN,
char ctl_iscritical, LDAPControl **ctrlp);Parameters
This function has the parameters listed in Table 17-65.
Table 17-65 ldap_create_proxyauth_control() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
DN
String representing the DN of the entry who's identity the client will be assuming.
ctl_iscritical
Specifies whether the control is critical to the operation.
- If non-zero, the control is critical to the operation. If the server does not support it, the server will return an LDAP_UNAVAILABLE_CRITICAL_EXTENSION error.
- If 0, the control is not critical to the operation. Even if the server does not support the control, the operation is still attempted and the control is ignored.
ctrlp
Pointer to an LDAPControl structure created by this function. When you are done using this control, you should free it by calling ldap_control_free().
Returns
One of the following values:
- LDAP_SUCCESS if successful.
- LDAP_PARAM_ERROR if an invalid parameter was passed to the function.
- LDAP_NO_MEMORY if memory cannot be allocated.
- LDAP_ENCODING_ERROR if an error occurred when BER-encoding the control.
- LDAP_UNAVAILABLE_CRITICAL_EXTENSION if the server does not support proxied authorization and ctl_iscritical is set to a non-zero value.
See Also
ldap_create_sort_control()The ldap_create_sort_control() function creates a control that specifies the order in which you want search results returned.
Note
This function implements an extension to the LDAPv3. Server-side sorting is an optional feature; it may not be supported on all LDAP servers. Call this function when interacting with LDAP servers that support this LDAPv3 extension. See "Determining Supported Extended Operations" of Chapter 15, "Extended Operations" to determine if the server supports extended operations.
Syntax
#include <ldap.h>
int ldap_create_sort_control( LDAP *ld,
LDAPsortkey **sortKeyList, const char ctl_iscritical,
LDAPControl **ctrlp );Parameters
This function has the parameters listed in Table 17-66.
Table 17-66 ldap_create_sort_control() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
sortKeyList
Pointer to an array of LDAPsortkey structures that specify the attribute types or matching rules used for sorting and the order (ascending or descending) in which to sort the results.
ctl_iscritical
Specifies whether the control is critical to the operation.
- If non-zero, the control is critical to the operation. If the server does not support it, the server will return an LDAP_UNAVAILABLE_CRITICAL_EXTENSION error.
- If 0, the control is not critical to the operation. Even if the server does not support the control, the operation is still attempted and the control is ignored.
ctrlp
Pointer to an LDAPControl structure created by this function. When you are done using this control, you should free it by calling ldap_control_free().
Returns
One of the following values:
- 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.
Note
In order for the control to work, the LDAP server that you are connecting to must support the server control for sorting search results (OID 1.2.840.113556.1.4.473, or LDAP_CONTROL_SORTREQUEST, as defined in the ldap.h header file). See "Determining Supported Controls" of Chapter 13, "Working with LDAP Controls"for information on determining the controls supported by a server.
To specify the attributes to use for sorting the results, you can call ldap_create_sort_keylist() to create an array of LDAPsortkey structures and pass the array as the sortKeyList argument. When you are done with the search, you should free the control and the array of LDAPsortkey structures by calling the ldap_control_free() and ldap_free_sort_keylist() functions.
For more information, see "Creating the Control" of Chapter 13, "Working with LDAP Controls."
See Also
ldap_create_sort_keylist(), ldap_search_ext(), ldap_search_ext_s(), ldap_control_free()
ldap_create_sort_keylist()The ldap_create_sort_keylist() function creates an array of LDAPsortkey structures from a string representation of a set of sort keys.
Syntax
#include <ldap.h>
int ldap_create_sort_keylist(LDAPsortkey ***sortKeyList,
const char *string_rep);Parameters
This function has the parameters listed in Table 17-67.
Table 17-67 ldap_create_sort_keylist() Function Parameters
Parameter
Description
sortKeyList
Pointer to an array of LDAPsortkey structures that specify the attribute types or matching rules used for sorting and the order (ascending or descending) in which to sort the results.
string_rep
String representation of a set of sort keys. The value should specify the name of the attribute that you want to sort by. To sort in reverse order, precede the attribute name with a hyphen ("-"). To use a matching rule for sorting, append a colon to the attribute name and specify the object identifier (OID) of a matching rule after the colon. For example:
1. cn (sorts by the cn attribute)
2. -cn (sorts by the cn attribute in reverse order)
3. -cn:1.2.3.4 (sorts by the cn attribute in reverse order using the matching rule identified by the OID 1.2.3.4)
Returns
One of the following values:
- 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.
For more information, see "Specifying the Sort Order" of Chapter 13, "Working with LDAP Controls."
See Also
ldap_create_sort_control(), ldap_free_sort_keylist()
ldap_create_virtuallist_control()The ldap_create_virtuallist_control() function creates a control that requests a subset of search results for use in a virtual list box.
Note
ldap_create_virtuallist_control() implements an extension to the LDAPv3 supported by Sun Java System Directory Server. For information on determining if another server supports this control, see "Determining Supported Controls" of Chapter 13, "Working with LDAP Controls."
Syntax
#include <ldap.h>
int ldap_create_virtuallist_control( LDAP *ld,
LDAPVirtualList *ldvlistp, LDAPControl **ctrlp );Parameters
This function has the parameters listed in Table 17-68.
Table 17-68 ldap_create_virtuallist_control() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
ldvlistp
Pointer to an LDAPVirtualList structure that specifies the subset of entries that you want retrieved from the server and the selected entry.
ctrlp
Pointer to an LDAPControl structure created by this function. When you are done using this control, you should free it by calling ldap_control_free().
Returns
One of the following values:
- 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). See "Determining Supported Controls" of Chapter 13, "Working with LDAP Controls" for information on determining the controls supported by a server.
Calling ldap_create_virtuallist_control() creates an LDAP control that you can pass to the ldap_search_ext() and ldap_search_ext_s() functions. You also need to pass a server-side sorting control to the search functions. You can call ldap_create_sort_keylist() and ldap_create_sort_control() to create a server-side sorting control. When you are done with the search, you should free the control by calling the ldap_control_free() function.
For more information about this control, see "Using the Virtual List View Control" of Chapter 13, "Working with LDAP Controls."
See Also
LDAPVirtualList, ldap_parse_virtuallist_control(), ldap_search_ext(), ldap_search_ext_s(), ldap_control_free()
ldap_delete()The ldap_delete() function removes an entry from the directory asynchronously.
Note
This is an older function that is included in the SDK for backward-compatibility. If you are writing a new LDAP client, use ldap_delete_ext() instead.
Syntax
#include <ldap.h>
int ldap_delete( LDAP *ld, const char *dn );Parameters
This function has the parameters listed in Table 17-69.
Table 17-69 ldap_delete() FunctionParameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
dn
DN of the entry to remove.
Returns
Returns the message ID of the ldap_delete() operation.
Note
To check the result of this operation, call ldap_result() and ldap_result2error(). See ldap_delete_ext_s() for a list of possible result codes for the LDAP delete operation.
Description
Please use the newer version of this function, ldap_delete_ext().
Example
Code Example 17-11 uses the asynchronous ldap_delete() function to remove the entry for Barbara Jensen from the directory.
Code Example 17-11 ldap_delete() Code Example
#include <ldap.h>
...
LDAP *ld;
LDAPMessage *result;
int msgid, rc;
struct timeval tv;
/* Distinguished name of the entry that you want to delete. */
char *dn = "uid=bjensen,ou=People,dc=example, dc=com";
...
/* Set up the timeout period to wait for the "modify" operation */
tv.tv_sec = tv.tv_usec = 0;
/* Delete the entry */
if ( ( msgid = ldap_delete( ld, dn ) ) == -1 ) {
ldap_perror( ld, "ldap_delete" );
return( 1 );
}
/* Check to see if the operation has completed */
while ( ( rc = ldap_result( ld, msgid, 0, &tv, &result ) ) == 0 ) {
...
/* do other work while waiting for the operation to complete */
...
}
/* Check the result to see if any errors occurred */
ldap_result2error( ld, result, 1 );
ldap_perror( ld, "ldap_delete" );
...
See Also
ldap_delete_ext()The ldap_delete_ext() function deletes an entry from the directory asynchronously.
Note
ldap_delete_ext() is a new version of the ldap_delete() function. If you are writing a new LDAP client, you should call ldap_delete_ext().
Syntax
#include <ldap.h>
int ldap_delete_ext( LDAP *ld, const char *dn,
LDAPControl **serverctrls, LDAPControl **clientctrls, int *msgidp );Parameters
This function has the parameters listed in Table 17-70.
Table 17-70 ldap_delete_ext() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
dn
DN of the entry to remove.
serverctrls
Pointer to an array of LDAPControl structures representing LDAP server controls that apply to this operation. If you do not want to pass any server controls, specify NULL for this argument.
clientctrls
Pointer to an array of LDAPControl structures representing LDAP client controls that apply to this operation. If you do not want to pass any client controls, specify NULL for this argument.
msgidp
Pointer to an integer that will be set to the message ID of the LDAP operation.
Returns
One of the following values:
- 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 LDAPv3. Make sure that you set the version of your LDAP client to version 3 before calling this function. For details, see "Specifying the LDAP Version of Your Client" of Chapter 3, "Writing an LDAP Client."
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().
For additional information on deleting entries from the directory, see Chapter 7, "Adding, Modifying and Deleting Entries."
Example
See Code Example 4-2 of Chapter 4, "Using the LDAP API" and Code Example 7-21 of Chapter 7, "Adding, Modifying and Deleting Entries."
See Also
ldap_delete_ext_s(), ldap_result(), ldap_parse_result()
ldap_delete_ext_s()The ldap_delete_ext_s() function deletes an entry from the directory synchronously.
Note
ldap_delete_ext_s() is a new version of the ldap_delete_s() function. If you are writing a new LDAP client, you should call ldap_delete_ext_s().
Syntax
#include <ldap.h>
int ldap_delete_ext_s( LDAP *ld, const char *dn,
LDAPControl **serverctrls, LDAPControl **clientctrls );Parameters
This function has the parameters listed in Table 17-71.
Table 17-71 ldap_delete_ext_s() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
dn
DN of the entry to remove.
serverctrls
Pointer to an array of LDAPControl structures representing LDAP server controls that apply to this operation. If you do not want to pass any server controls, specify NULL for this argument.
clientctrls
Pointer to an array of LDAPControl structures representing LDAP client controls that apply to this operation. If you do not want to pass any client controls, specify NULL for this argument.
Returns
One of the following values:
Returns
One of the following values:
- 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 LDAPv3. Make sure that you set the version of your LDAP client to version 3 before calling this function. For details, see "Specifying the LDAP Version of Your Client" of Chapter 3, "Writing an LDAP Client."
- 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.
Description
The ldap_delete_ext_s() function deletes an entry from the directory, using the dn argument to specify the entry that you want to delete. ldap_delete_ext_s() is a synchronous function, which directly returns the results of the operation. If you want to perform other operations while waiting for the results of this operation, call the asynchronous function ldap_delete_ext() instead.
For additional information on deleting entries from the directory, see Chapter 7, "Adding, Modifying and Deleting Entries."
Example
See Code Example 4-1 of Chapter 4, "Using the LDAP API" and Code Example 7-19 in Chapter 7, "Adding, Modifying and Deleting Entries."
See Also
ldap_delete_s()The ldap_delete_s() deletes an entry from the directory synchronously.
Note
This is an older function that is included in the SDK for backward-compatibility. If you are writing a new LDAP client, use ldap_delete_ext_s() instead.
Syntax
#include <ldap.h>
int ldap_delete_s(LDAP *ld, const char *dn);Parameters
This function has the parameters listed in Table 17-72.
Table 17-72 ldap_delete_s() Function Parameters
Parameters
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
dn
DN of the entry to remove.
Returns
For a list of possible result codes for an LDAP delete operation, see the ldap_delete_ext_s() function.
Description
Please use the newer version of this function, ldap_delete_ext_s().
Example
Code Example 17-12 uses the synchronous ldap_delete_s() function to delete the entry for Barbara Jensen from the directory.
Code Example 17-12 ldap_delete_s() Code Example
#include <ldap.h>
LDAP *ld;
/* Distinguished name of the entry that you want to delete. */
char *dn = "uid=bjensen,ou=People,dc=example, dc=com";
...
/* Delete the entry */
if ( ldap_delete_s( ld, dn ) != LDAP_SUCCESS ) {
ldap_perror( ld, "ldap_delete_s" );
return( 1 );
}
...
See Also
ldap_dn2ufn()The ldap_dn2ufn() function converts a DN into a more user-friendly form by stripping off the cryptic type names.
Syntax
#include <ldap.h>
char * ldap_dn2ufn( const char *dn );Parameters
This function has the parameter listed in Table 17-73.
Table 17-73 ldap_dn2ufn() Function Parameter
Parameter
Description
dn
The DN that you want converted.
Returns
One of the following values:
Description
For more information on ldap_dn2ufn(), see the man page. For more information on user friendly naming (UFN), see RFC 1781, Using the OSI Directory to Achieve User Friendly Naming (http://www.faqs.org/rfcs/rfc1781.html).
ldap_entry2html()The ldap_entry2html() function writes the HTML representation of an LDAP entry.
Syntax
#include <disptmpl.h>
int ldap_entry2html( LDAP *ld, char *buf, LDAPMessage *entry,
struct ldap_disptmpl *tmpl, char **defattrs, char ***defvals,
writeptype writeproc, void *writeparm, char *eol, int rdncount,
unsigned long opts, char *urlprefix, char *base );Parameters
This function has the parameters listed in Table 17-74.
Table 17-74 ldap_entry2html() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
buf
A pointer to a buffer of size LDAP_DTMPL_BUFSIZ or larger. If NULL, a buffer is allocated and freed internally.
entry
Specifies the attribute values to be represented.
tmpl
Pointer to the display template to be used, usually obtained by calling ldap_oc2template().
defattrs
A NULL-terminated array of LDAP attribute names for which you wish to provide default values. It is only used if the entry contains no values for the attribute.
defvals
An array of NULL-terminated arrays of default values corresponding to the attributes.
writeproc
writeproc function should be declared as:
int writeproc( writeparm, p, len )
void *writeparm;
char *p;
int len;
where p is a pointer to text to be written and len is the length of the text. p is guaranteed to be zero-terminated.
writeparm
A pointer to a structure that will be passed as the first parameter of the writeproc procedure. Typically, this is used to pass the file descriptor of the file to write to.
eol
Lines of text are terminated with this string.
rdncount
Limits the number of components that are displayed for DN attributes.
opts
Specifies output options. The allowed values are:
- zero (default output)
- LDAP_DISP_OPT_AUTOLABELWIDTH which causes the width for labels to be determined based on the longest label in tmpl.
- LDAP_DISP_OPT_HTMLBODYONLY which instructs the library not to include <HTML>, <HEAD>, <TITLE>, and <BODY> tags. In other words, an HTML fragment is generated, and the caller is responsible for prepending and appending the appropriate HTML tags to construct a correct HTML document.
urlprefix
Starting text to use when constructing an LDAP URL. The default is the string ldap://.
base
The base with which to begin when executing search actions. If NULL, search action template items are ignored.
Returns
- 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
This function has the parameters listed in Table 17-75.
Table 17-75 ldap_entry2html_search() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
dn
DN of the entry to write as HTML.
base
The base with which to begin when executing search actions. If NULL, search action template items are ignored.
entry
Specifies the attribute values to be represented.
tmpllist
Pointer to the entire list of templates available (usually obtained by calling ldap_init_templates() or ldap_init_templates_buf()). If NULL, will attempt to read a load templates from the default template configuration file.
defattrs
A NULL-terminated array of LDAP attribute names for which you wish to provide default values. It is only used if the entry contains no values for the attribute.
defvals
An array of NULL-terminated arrays of default values corresponding to the attributes.
writeproc
writeproc function should be declared as:
int writeproc( writeparm, p, len )
void *writeparm;
char *p;
int len;
where p is a pointer to text to be written and len is the length of the text. p is guaranteed to be zero-terminated.
writeparm
A pointer to a structure that will be passed as the first parameter of the writeproc procedure. Typically, this is used to pass the file descriptor of the file to write to.
eol
Lines of text are terminated with this string.
rdncount
Limits the number of components that are displayed for DN attributes.
opts
Specifies output options. The allowed values are:
- zero (default output)
- LDAP_DISP_OPT_AUTOLABELWIDTH which causes the width for labels to be determined based on the longest label in tmpl.
- LDAP_DISP_OPT_HTMLBODYONLY which instructs the library not to include <HTML>, <HEAD>, <TITLE>, and <BODY> tags. In other words, an HTML fragment is generated, and the caller is responsible for prepending and appending the appropriate HTML tags to construct a correct HTML document.
urlprefix
Starting text to use when constructing an LDAP URL. The default is the string ldap://
Returns
- 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
This function has the parameters listed in Table 17-76.
Table 17-76 ldap_entry2text() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
buf
A pointer to a buffer of size LDAP_DTMPL_BUFSIZ or larger. If NULL, a buffer is allocated and freed internally.
entry
Specifies the attribute values to be represented.
tmpl
Pointer to the display template to be used, usually obtained by calling ldap_oc2template().
defattrs
A NULL-terminated array of LDAP attribute names for which you wish to provide default values. It is only used if the entry contains no values for the attribute.
defvals
An array of NULL-terminated arrays of default values corresponding to the attributes.
writeproc
writeproc function should be declared as:
int writeproc( writeparm, p, len )
void *writeparm;
char *p;
int len;
where p is a pointer to text to be written and len is the length of the text. p is guaranteed to be zero-terminated.
writeparm
A pointer to a structure that will be passed as the first parameter of the writeproc procedure. Typically, this is used to pass the file descriptor of the file to write to.
eol
Lines of text are terminated with this string.
rdncount
Limits the number of components that are displayed for DN attributes.
opts
Specifies output options. The allowed values are:
- zero (default output)
- LDAP_DISP_OPT_AUTOLABELWIDTH which causes the width for labels to be determined based on the longest label in tmpl.
- LDAP_DISP_OPT_HTMLBODYONLY which instructs the library not to include <HTML>, <HEAD>, <TITLE>, and <BODY> tags. In other words, an HTML fragment is generated, and the caller is responsible for prepending and appending the appropriate HTML tags to construct a correct HTML document.
Returns
- 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
This function has the parameters listed in Table 17-77.
Table 17-77 ldap_entry2text_search() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
dn
DN of the entry to write.
base
If NULL, the search action template items are ignored. If not NULL, it is the search base to use when executing search actions.
entry
If entry is not NULL, it should contain the objectClass attribute values for the entry to be displayed. If NULL, dn can not be NULL, and ldap_entry2text_search() will retrieve the objectClass values itself by calling ldap_search_s().
tmpllist
Pointer to the entire list of templates available (usually obtained by calling ldap_init_templates() or ldap_init_templates_buf()). If NULL, will attempt to read a load templates from the default template configuration file.
defattrs
A NULL-terminated array of LDAP attribute names for which you wish to provide default values. It is only used if the entry contains no values for the attribute.
defvals
An array of NULL-terminated arrays of default values corresponding to the attributes.
writeproc
writeproc function should be declared as:
int writeproc( writeparm, p, len )
void *writeparm;
char *p;
int len;
where p is a pointer to text to be written and len is the length of the text. p is guaranteed to be zero-terminated.
writeparm
A pointer to a structure that will be passed as the first parameter of the writeproc procedure. Typically, this is used to pass the file descriptor of the file to write to.
eol
Lines of text are terminated with this string.
rdncount
Limits the number of components that are displayed for DN attributes.
opts
Specifies output options. The allowed values are:
- zero (default output)
- LDAP_DISP_OPT_AUTOLABELWIDTH which causes the width for labels to be determined based on the longest label in tmpl.
- LDAP_DISP_OPT_HTMLBODYONLY which instructs the library not to include <HTML>, <HEAD>, <TITLE>, and <BODY> tags. In other words, an HTML fragment is generated, and the caller is responsible for prepending and appending the appropriate HTML tags to construct a correct HTML document.
Returns
- 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
This function has the parameter listed in Table 17-78.
Table 17-78 ldap_err2string() Function Parameter
Parameter
Description
err
Error code that you want interpreted into an error message.
Returns
One of the following values:
Description
For more information, see "Getting the Error Message from an Error Code" of Chapter 4, "Using the LDAP API."
Example
Code Example 17-13 sets the variable err_msg to the error message corresponding to the error code returned by the ldap_simple_bind_s() function.
Code Example 17-13 ldap_err2string() Code Example
#include <ldap.h>
...
LDAP *ld;
char *dn = "uid=bjensen,ou=People,dc=example, dc=com";
char *pw = "hifalutin";
char *err_msg;
...
err_msg = ldap_err2string( ldap_simple_bind_s( ld, dn, pw ) );
...
See Also
ldap_get_lderrno(), ldap_perror(), ldap_result2error(), ldap_set_lderrno(), ldapssl_err2string()
ldap_explode_dn()The ldap_explode_dn() function converts a DN into its component parts.
Syntax
#include <ldap.h>
char ** ldap_explode_dn( const char *dn, int notypes );Parameters
This function has the parameters listed in Table 17-79.
Table 17-79 ldap_explode_dn() Function Parameters
Parameter
Description
dn
DN that you want separated into components.
notypes
Specifies whether or not type names in the DN are returned. This parameter can have the following possible values:
Returns
One of the following values:
Description
For more information, see "Getting the Components of a Distinguished Name" of Chapter 5, "Searching a LDAP Directory."
Example
The following function call:
ldap_explode_dn( "uid=bjensen,ou=People,dc=example,dc=com", 0 )
returns this array:
{ "uid=bjensen", "ou=People", "dc=example,dc=com", NULL }
If you change the notypes parameter from 0 to 1:
ldap_explode_dn( "uid=bjensen,ou=People,dc=example,dc=com", 1 )
The component names are not returned in the array:
{ "bjensen", "People", "example.com", NULL }
See Also
ldap_explode_rdn(), ldap_get_dn()
ldap_explode_dns()
Caution
This function is to be deprecated and should not be used. It is included in ldap-to-be-deprecated.h for backward-compatibility.
The ldap_explode_dns() function takes a DNS-style DN, breaks it up into its component parts, and returns a NULL-terminated array. For example, the DN cal.sun.com will return { "cal", "sun", "com", NULL }. The result can be freed by calling ldap_value_free().
Syntax
#include <ldap-to-be-deprecated.h>
char ** ldap_explode_dns( const char *dn );Parameters
This function has the parameter listed in Table 17-80.
Table 17-80 ldap_explode_dns() Function Parameter
Parameter
Description
dn
DN that you want separated into components.
Returns
One of the following values:
Description
For more information, see "Getting the Components of a Distinguished Name" of Chapter 5, "Searching a LDAP Directory."
ldap_explode_rdn()The ldap_explode_rdn() function converts a relative distinguished name (RDN) into its component parts.
Syntax
#include <ldap.h>
char ** ldap_explode_rdn( const char *dn, int notypes );Parameters
This function has the parameters listed in Table 17-81.
Table 17-81 ldap_explode_rdn() Function Parameters
Parameter
Description
dn
RDN that you want separated into components.
notypes
Specifies whether or not type names in the RDN are returned. This parameter can have the following possible values:
Returns
One of the following values:
Description
For more information, see "Getting the Components of a Distinguished Name" of Chapter 5, "Searching a LDAP Directory."
Example
The following function call:
ldap_explode_rdn( "ou=Sales + cn=Barbara Jensen", 0 );
returns this array:
{ "ou=Sales", "cn=Barbara Jensen", NULL }
See Also
ldap_explode_dn(), ldap_get_dn()
ldap_extended_operation()The ldap_extended_operation() function sends a request to the server to perform an extended operation asynchronously.
Syntax
#include <ldap.h>
int ldap_extended_operation( LDAP *ld, const char *requestoid,
struct berval *requestdata, LDAPControl **serverctrls,
LDAPControl **clientctrls, int *msgidp );Parameters
This function has the parameters listed in Table 17-82.
Table 17-82 ldap_extended_operation() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
requestoid
Object identifier (OID) of the extended operation that you want the server to perform. (After processing an LDAPv3 extended operation, an LDAP server can return an OID and data in the result. To parse the OID and data from the result, call the ldap_parse_extended_result() function.)
requestdata
Pointer to a berval structure containing the data that you want passed to the server to perform the extended operation. The data in the berval is a buffer of the BER encoded datatype, usually optained using the ber_flatten() function.
serverctrls
Pointer to an array of LDAPControl structures representing LDAP server controls that apply to this operation. If you do not want to pass any server controls, specify NULL for this argument.
clientctrls
Pointer to an array of LDAPControl structures representing LDAP client controls that apply to this operation. If you do not want to pass any client controls, specify NULL for this argument.
msgidp
Pointer to an integer that will be set to the message ID of the LDAP operation.
Returns
One of the following values:
- 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 LDAPv3. Make sure that you set the version of your LDAP client to version 3 before calling this function. For details, see "Specifying the LDAP Version of Your Client" of Chapter 3, "Writing an LDAP Client."
Note
To check the result of this operation, call ldap_result(), ldap_parse_extended_result(), and ldap_get_lderrno().
Description
The ldap_extended_operation() function sends a request to the server to perform an LDAPv3 extended operation. ldap_extended_operation() is an asynchronous function; it does not directly return results. If you want the results to be returned directly by the function, call the synchronous function ldap_extended_operation_s().
For additional information on asynchronous extended operations, see "Asynchronous Extended Operation" of Chapter 15, "Extended Operations." For a list of possible result codes for an LDAP extended operation, see ldap_extended_operation_s().
See Also
ldap_extended_operation_s(), ldap_result(), ldap_parse_extended_result(), ldap_get_lderrno(), ber_flatten()
ldap_extended_operation_s()The ldap_extended_operation_s() function sends a request to the server to perform an extended operation synchronously.
Syntax
#include <ldap.h>
int ldap_extended_operation_s( LDAP *ld, const char *requestoid,
struct berval *requestdata, LDAPControl **serverctrls,
LDAPControl **clientctrls, char **retoidp, struct berval **retdatap );Parameters
This function has the parameters listed in Table 17-83.
Table 17-83 ldap_extended_operation_s() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
requestoid
Object identifier (OID) of the extended operation that you want the server to perform.
requestdata
Pointer to a berval structure containing the data that you want passed to the server to perform the extended operation. The data in the berval is a buffer of the BER encoded datatype, usually optained using the ber_flatten() function.
serverctrls
Pointer to an array of LDAPControl structures representing LDAP server controls that apply to this operation. If you do not want to pass any server controls, specify NULL for this argument.
clientctrls
Pointer to an array of LDAPControl structures representing LDAP client controls that apply to this operation. If you do not want to pass any client controls, specify NULL for this argument.
retoidp
Pointer to the OID returned by the server after performing the extended operation. When done, you can free this by calling the ldap_memfree() function.
retdatap
Pointer to the pointer for a berval structure containing the data returned by the server after performing the extended operation. When done, you can free this by calling the ber_bvfree() function.
Returns
One of the following values:
- 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 LDAPv3. Make sure that you set the version of your LDAP client to version 3 before calling this function. For details, see "Specifying the LDAP Version of Your Client" of Chapter 3, "Writing an LDAP Client."
Description
The ldap_extended_operation_s() function sends a request to the server to perform an LDAPv3 extended operation.
Note
The LDAP server must support the extended operation. Sun Java System Directory Server supports a server plug-in interface that you can use to add support for extended operations. For details, see the Sun ONE Directory Server Plug-In Programming Guide.
ldap_extended_operation_s() is a synchronous function, which directly returns the results of the operation. If you want to perform other operations while waiting for the results of this operation, call the asynchronous function ldap_extended_operation(). After processing an LDAPv3 extended operation, an LDAP server can return an object identifier and data in the results. The retoidp and retdatap arguments point to these values.
For information on determining the extended operations supported by a server, see "Determining Supported Extended Operations" of Chapter 15, "Extended Operations."
See Also
ldap_extended_operation(), ber_flatten()
ldap_first_attribute()The ldap_first_attribute() function returns the name of the first attribute in an entry returned by the ldap_first_entry(), the ldap_next_entry(), or the ldap_result() functions.
Syntax
#include <ldap.h>
char * ldap_first_attribute( LDAP *ld, LDAPMessage *entry,
BerElement **ber );Parameters
This function has the parameters listed in Table 17-84.
Table 17-84 ldap_first_attribute() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
entry
Pointer to the LDAPMessage structure representing the entry returned by the ldap_first_entry() or ldap_next_entry() function.
ber
Pointer to a BerElement allocated to keep track of its current position. Pass this pointer to subsequent calls to ldap_next_attribute() to step through the entry's attributes.
Returns
One of the following values:
- If successful, returns the pointer to the name of the first attribute in an entry. When you are done using this data, you should free the memory by calling the ldap_memfree() function.
- If unsuccessful, returns a NULL and sets the appropriate error code in the LDAP structure. To get the error code, call the ldap_get_lderrno() function.
See Chapter 18, "Result Codes" for a complete listing of error codes.
Description
For more information, see "Getting Attribute Names from an Entry" of Chapter 5, "Searching a LDAP Directory."
Example
Code Example 17-14 retrieves each attribute for an entry.
Code Example 17-14 ldap_first_attribute() Code Example
#include <stdio.h>
#include <ldap.h>
...
LDAP *ld;
LDAPMessage *result, *e;
BerElement *ber;
char *a;
char *my_searchbase = "dc=example,dc=com";
char *my_filter = "(sn=Jensen)"
...
/* Search the directory */
if ( ldap_search_s( ld, my_searchbase, LDAP_SCOPE_SUBTREE, \
my_filter, NULL, 0, &result ) != LDAP_SUCCESS ) {
ldap_perror( ld, "ldap_search_s" );
return( 1 );
}
/* Get the first matching entry.*/
e = ldap_first_entry( ld, result );
/* Retrieve the attributes the entry */
for ( a = ldap_first_attribute( ld, e, &ber ); a != NULL;
a = ldap_next_attribute( ld, e, ber ) ) {
...
/* Code to get and manipulate attribute values */
...
}
ldap_memfree( a );
}
/* Free the BerElement from memory when done */
if ( ber != NULL ) {
ldap_ber_free( ber, 0 );
}
...
See Also
ldap_first_entry(), ldap_next_entry(), ldap_next_attribute(), BerElement
ldap_first_disptmpl()The ldap_first_disptmpl() function returns the first template in a list.
Syntax
#include <disptmpl.h>
ldap_first_disptmpl( struct ldap_disptmpl *tmpllist );Parameters
This function has the parameter listed in Table 17-85.
Table 17-85 ldap_first_disptmpl() Function Parameter
Parameter
Description
tmpllistp
Pointer to a list of template data structures.
Description
ldap_first_disptmpl() returns the first template in the list of templates pointed to by the parameter tmpllistp. tmpllistp is typically obtained by calling ldap_init_templates().
See Also
ldap_next_disptmpl(), ldap_init_templates(), ldap_init_templates_buf()
ldap_first_entry()The ldap_first_entry() function returns a pointer to the LDAPMessage structure representing the first directory entry in a chain of search results.
Syntax
#include <ldap.h>
LDAPMessage * ldap_first_entry( LDAP *ld, LDAPMessage *result );Parameters
This function has the parameters listed in Table 17-86.
Table 17-86 ldap_first_entry() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
result
Chain of search results, which are represented by a pointer to the LDAPMessage structure.
Returns
One of the following values:
- If successful, returns the pointer to the first LDAPMessage structure of the type LDAP_RES_SEARCH_ENTRY in the chain of search results.
- If no LDAPMessage structures of the type LDAP_RES_SEARCH_ENTRY are in the chain of the search results or if the function is unsuccessful, returns a NULLMSG.
Description
The ldap_first_entry() function returns a pointer to the LDAPMessage structure representing the first directory entry in a chain of search results. Search result entries are in messages of the type LDAP_RES_SEARCH_ENTRY. You can use this function in conjunction with the ldap_next_entry() function to iterate through the directory entries in a chain of search results. These functions skip over any messages in the chain that do not have the type LDAP_RES_SEARCH_ENTRY.
Caution
Do not free the LDAPMessage structure returned by this function. Because this is a structure within a chain of search results, freeing this structure will free part of the chain of search results. When you are done working with the search results, you can free the chain itself, rather than individual structures within the chain.
For more information, see Chapter 5, "Searching a LDAP Directory."
See Also
ldap_result(), ldap_search_ext(), ldap_search_ext_s(), ldap_next_entry()
ldap_first_message()The ldap_first_message() function returns a pointer to the first LDAPMessage structure in a chain of search results.
Syntax
#include <ldap.h>
LDAPMessage * ldap_first_message( LDAP *ld, LDAPMessage *res );Parameters
This function has the parameters listed in Table 17-87.
Table 17-87 ldap_first_message() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
res
Chain of search results, represented by a pointer to the LDAPMessage structure.
Returns
One of the following values:
- 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).
Caution
Do not free the LDAPMessage structure returned by this function. Because this is a structure within a chain of search results, freeing this structure will free part of the chain of search results. When you are done working with the search results, you can free the chain itself, rather than individual structures within the chain.
For more information, see Chapter 5, "Searching a LDAP Directory."
Example
See Code Example 5-4 and Code Example 5-7 in Chapter 5, "Searching a LDAP Directory."
See Also
ldap_result(), ldap_search_ext(), ldap_search_ext_s(), ldap_next_message(), ldap_first_entry(), ldap_first_reference()
ldap_first_reference()The ldap_first_reference() function returns a pointer to the LDAPMessage structure representing the first search reference in a chain of search results.
Syntax
#include <ldap.h>
LDAPMessage * ldap_first_reference(LDAP *ld, LDAPMessage *res );Parameters
This function has the parameters listed in Table 17-88.
Table 17-88 ldap_first_reference() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
res
Chain of search results, which are represented by a pointer to the LDAPMessage structure.
Returns
One of the following values:
- If successful, returns the pointer to the first LDAPMessage structure of the type LDAP_RES_SEARCH_REFERENCE in the chain of search results.
- If no LDAPMessage structures of the type LDAP_RES_SEARCH_REFERENCE are in the chain of the search results or if the function is unsuccessful, returns a NULLMSG.
Description
The ldap_first_reference() function returns a pointer to the LDAPMessage structure representing the first search reference in a chain of search results. Search references are in messages of the type LDAP_RES_SEARCH_REFERENCE. You can use this function in conjunction with the ldap_next_reference() function to iterate through the search references in a chain of search results. These functions skip over any messages in the chain that do not have the type LDAP_RES_SEARCH_REFERENCE.
Caution
Do not free the LDAPMessage structure returned by this function. Because this is a structure within a chain of search results, freeing this structure will free part of the chain of search results. When you are done working with the search results, you can free the chain itself, rather than individual structures within the chain.
For more information, see Chapter 5, "Searching a LDAP Directory."
See Also
ldap_result(), ldap_search_ext(), ldap_search_ext_s(), ldap_next_reference(), ldap_first_message()
ldap_first_searchobj()The ldap_first_searchobj() function returns the first search preference configuration from a data structure defined in the list solist.
Syntax
#include <ldap.h>
ldap_searchobj * ldap_first_searchobj( struct ldap_searchobj *solist );Parameters
This function has the parameter listed in Table 17-89.
Table 17-89 ldap_first_searchobj() Function Parameter
Parameter
Description
solist
Pointer to the search preference data structures, typically obtained by calling ldap_init_searchprefs().
Description
ldap_first_searchobj provides access to LDAP search preference configuration data. LDAP search preference configurations are typically used by LDAP client programs to specify which attributes a user may search by, the labels for the attributes, and the LDAP filters and scopes associated with those searches.
See Also
ldap_init_searchprefs(), ldap_init_searchprefs_buf()
ldap_first_tmplcol()The ldap_first_tmplcol() function returns a pointer to the first item within a template.
Syntax
#include <disptmpl.h>
struct ldap_tmplitem * ldap_first_tmplcol( struct ldap_disptmpl *tmpl,
struct ldap_tmplitem *row );Parameters
This function has the parameters listed in Table 17-90.
Table 17-90 ldap_first_tmplcol() Function Parameters
Parameter
Description
tmpl
The name of the template to be retrieved.
row
The row in which the item is to be retrieved from.
Returns
Description
ldap_first_tmplcol() returns a pointer to the first item (in the first column) of the row, defined by row, within the template defined by tmpl.
See Also
ldap_first_tmplrow(), ldap_next_tmplcol()
ldap_first_tmplrow()The ldap_first_tmplrow() function returns a pointer to the first row of items in a template.
Syntax
#include <disptmpl.h>
struct ldap_tmplitem * ldap_first_tmplrow( struct ldap_disptmpl *tmpl );Parameters
This function has the parameter listed in Table 17-91.
Table 17-91 ldap_first_tmplrow() Function Parameter
Parameter
Description
tmpl
The name of the template to be retrieved.
Returns
See Also
ldap_next_tmplrow(), ldap_first_tmplcol()
ldap_free_friendlymap()The ldap_free_friendlymap() function frees the FriendlyMap structures allocated by the ldap_friendly_name() function when no more calls to it are to be made.
Syntax
#include <ldap.h>
void ldap_free_friendlymap( FriendlyMap *map );Parameters
This function has the parameter listed in Table 17-92.
Table 17-92 ldap_free_friendlymap() Function Parameter
Parameter
Description
map
Pointer to the FriendlyMap mapping structure in memory.
Example
Code Example 17-15 frees memory allocated by the ldap_friendly_name() function.
Code Example 17-15 ldap_free_friendlymap() Code Example
#include <ldap.h>
#include <stdio.h>
...
FriendlyMap map = NULL;
char *map_file = "/u/mozilla/ldapsdk/examples/ldapfriendly";
char *unfriendly_name = "IS";
char *friendly_name;
...
/* Read the ldapfriendly file into the map in memory */
friendly_name = ldap_friendly_name( map_file, unfriendly_name, &map );
printf( "Friendly Name for %s: %s\n", unfriendly_name, friendly_name );
/* Since file is in memory, no need to reference it in subsequent calls */
friendly_name = ldap_friendly_name( NULL, "VI", &map );
printf( "Friendly Name for VI: %s\n", friendly_name );
...
ldap_free_friendlymap( map );
...
See Also
ldap_friendly_name(), FriendlyMap
ldap_free_searchprefs()The ldap_free_searchprefs() function disposes of the data structures allocated by ldap_init_searchprefs().
Syntax
#include <ldap.h>
void ldap_free_searchprefs( struct ldap_searchobj *solist );Parameters
This function has the parameter listed in Table 17-93.
Table 17-93 ldap_free_searchprefs() Function Parameter
Parameter
Description
solist
Pointer to the data structures, typically obtained by calling ldap_init_searchprefs().
See Also
ldap_init_searchprefs(), ldap_init_searchprefs_buf()
ldap_free_sort_keylist()The ldap_free_sort_keylist() function frees the structures allocated by the ldap_create_sort_keylist() function.
Syntax
#include <ldap.h>
void ldap_free_sort_keylist (LDAPsortkey **sortKeyList);Parameters
This function has the parameter listed in Table 17-94.
Table 17-94 ldap_free_sort_keylist() Function Parameter
Parameter
Description
sortKeyList
Array of LDAPsortkey structures that you want to free from memory.
Description
The ldap_free_sort_keylist() function frees the array of LDAPsortkey structures allocated by the ldap_create_sort_keylist() function. When done sorting results, call this function to free the memory that you have allocated. This function must be called after the ldap_create_sort_control() function has completed.
See Also
ldap_create_sort_keylist(), ldap_create_sort_control()
ldap_free_templates()The ldap_free_templates() function disposes of the templates allocated by ldap_init_templates().
Syntax
#include <disptmpl.h>
void ldap_free_templates( struct ldap_disptmpl *tmpllist );Parameters
This function has the parameter listed in Table 17-95.
Table 17-95 ldap_free_templates() Function Parameter
Parameter
Description
tmpllistp
Pointer to a list of template data structures.
Description
ldap_free_templates() releases the templates allocated by ldap_init_templates(). Each template defined in the file is an ldap_disptmpl structure.
ldap_free_urldesc()The ldap_free_urldesc() function frees memory allocated by the ldap_url_parse() function.
Syntax
#include <ldap.h>
void ldap_free_urldesc( LDAPURLDesc *ludp );Parameters
This function has the parameter listed in Table 17-96.
Table 17-96 ldap_free_urldesc() Function Parameter
Parameter
Description
ludp
Pointer to a LDAPURLDesc structure.
Description
For more information, see "Freeing the Components of an LDAP URL" of Chapter 9, "Working with LDAP URLs."
Example
Code Example 17-16 parses an LDAP URL and then frees the LDAPURLDesc structure from memory after verifying that the LDAP URL is valid.
Code Example 17-16 ldap_free_urldesc() Code Example
#include <stdio.h>
#include <ldap.h>
...
char *my_url = "ldap://ldap.example.com:5000/dc=example,dc=com?cn,mail,telephoneNumber?sub ? \
(sn=Jensen)";
LDAPURLDesc *ludpp;
int res, i;
...
if ( ( res = ldap_url_parse( my_url, &ludpp ) ) != 0 ) {
switch( res ){
case LDAP_URL_ERR_NOTLDAP:
printf( "URL does not begin with \"ldap://\"\n" );
break;
case LDAP_URL_ERR_NODN:
printf( "URL does not contain a distinguished name\n" );
break;
case LDAP_URL_ERR_BADSCOPE:
printf( "URL contains an invalid scope\n" );
break;
case LDAP_URL_ERR_MEM:
printf( "Not enough memory\n" );
break;
default:
printf( "Unknown error\n" );
}
return( 1 );
}
printf( "URL is a valid LDAP URL\n" );
ldap_free_urldesc( ludpp );
...
See Also
ldap_friendly_name()The ldap_friendly_name() function maps a set of standard identifiers to their user-friendly counterparts. For example, you can represent the list of two-letter state codes (CA, IA) with their corresponding state names (California, Iowa), or map country ISO codes to the full country names.
Note
ldapfriendly, located in DSRK_base/lib/ldapcsdk/etc, is a sample file that maps two letter country codes to their full names. It can be used in context with ldap_friendly_name().
Syntax
#include <ldap.h>
char * ldap_friendly_name( char *filename, char *uname,
FriendlyMap *map );Parameters
This function has the parameters listed in Table 17-97.
Table 17-97 ldap_friendly_name() function parameters
Parameter
Description
filename
Name of the file mapping the standard identifiers to the user-friendly names.
uname
Standard identifier name for which you want to find the user-friendly name.
map
Pointer to the FriendlyMap mapping in memory. Initialize this pointer to NULL on the first call, then use it during subsequent calls so that the mapping file does not need to be read again.
Returns
One of the following values:
Description
This function relies on the existence of a text file mapping standard identifiers to user-friendly names. The names in the file are tab-delimited, as shown in Code Example 17-17.
Code Example 17-17 Unfriendly to Friendly Name Mapping File
<unfriendly_name> <friendly_name>
AD Andorra
AE United Arab Emirates
AF Afghanistan
AG Antigua and Barbuda
AI Anguilla
Example
Code Example 17-18 reads in a map of user-friendly names and prints the name corresponding to the standard identifier IS.
Code Example 17-18 ldap_friendly_name() Code Example
#include <ldap.h>
#include <stdio.h>
...
FriendlyMap map = NULL;
char *map_file = "/u/mozilla/ldapsdk/examples/ldapfriendly";
char *unfriendly_name = "IS";
char *friendly_name;
...
/* Read the ldapfriendly file into the map in memory */
friendly_name = ldap_friendly_name( map_file, unfriendly_name, &map );
printf( "Friendly Name for %s: %s\n", unfriendly_name, friendly_name );
/* Since file is in memory, no need to reference it in subsequent calls */
friendly_name = ldap_friendly_name( NULL, "VI", &map );
printf( "Friendly Name for VI: %s\n", friendly_name );
...
See Also
ldap_free_friendlymap(), FriendlyMap
ldap_get_dn()The ldap_get_dn() routine returns the DN for an entry in a chain of search results.
Syntax
#include <ldap.h>
char * ldap_get_dn( LDAP *ld, LDAPMessage *entry );Parameters
This function has the parameters listed in Table 17-98.
Table 17-98 ldap_get_dn() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
entry
Pointer to an entry in a chain of search results, as returned by the ldap_first_entry() and ldap_next_entry() functions.
Returns
One of the following values:
- 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.
See Chapter 18, "Result Codes" for a complete listing of error codes.
Description
You can get an entry from a chain of search results by calling the ldap_first_entry() and ldap_next_entry() functions.
For more information, see "Getting the Distinguished Name of an Entry" of Chapter 5, "Searching a LDAP Directory."
Example
Code Example 17-19 prints the DN for each entry found in a search.
Code Example 17-19 ldap_get_dn() Code Example
#include <stdio.h>
#include <ldap.h>
...
LDAP *ld;
LDAPMessage *result, *e;
char *dn;
char *my_searchbase = "dc=example,dc=com";
char *my_filter = "(sn=Jensen)";
...
/* Search the directory */
if ( ldap_search_s( ld, my_searchbase, LDAP_SCOPE_SUBTREE, my_filter,
NULL, 0, &result ) != LDAP_SUCCESS ) {
ldap_perror( ld, "ldap_search_s" );
return( 1 );
}
/* For each matching entry found, print out the name of the entry.*/
for ( e = ldap_first_entry( ld, result ); e != NULL;
e = ldap_next_entry( ld, e ) ) {
if ( ( dn = ldap_get_dn( ld, e ) ) != NULL ) {
printf( "dn: %s\n", dn );
/* Free the memory used for the DN when done */
ldap_memfree( dn );
}
}
/* Free the result from memory when done. */
ldap_msgfree( result );
...
See Also
ldap_first_entry(), ldap_next_entry(), ldap_get_lderrno()
ldap_get_entry_controls()The ldap_get_entry_controls() function gets the LDAP controls included with a directory entry in a set of search results.
Syntax
#include <ldap.h>
int ldap_get_entry_controls( LDAP *ld, LDAPMessage *entry,
LDAPControl ***serverctrlsp );Parameters
This function has the parameters listed in Table 17-99.
Table 17-99 ldap_get_entry_controls() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
entry
Pointer to an LDAPMessage structure representing an entry in a chain of search results.
serverctrlsp
Pointer to an array of LDAPControl structures, which represent the LDAPv3 server controls returned by the server.
Returns
One of the following values:
- 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 LDAPv3 controls included in a directory entry in a chain of search results. The LDAP controls are specified in an array of LDAPControl structures with each structure representing one LDAP control. Other controls are returned with results sent from the server. You can call ldap_parse_result() to retrieve those controls.
ldap_getfilter_free()The ldap_getfilter_free() function frees the memory used by a filter set.
Syntax
#include <ldap.h>
void ldap_getfilter_free( LDAPFiltDesc *lfdp );Parameters
This function has the parameter listed in Table 17-100.
Table 17-100 ldap_getfilter_free() Function Parameter
Parameter
Description
lfdp
Pointer to a LDAPFiltDesc structure.
Description
Once you call ldap_getfilter_free(), the LDAPFiltDesc structure is no longer valid and cannot be used again.
For more information, see "Freeing Filters from Memory" of Chapter 17, "Function Reference."
Example
Code Example 17-20 frees the LDAPFiltDesc structure from memory after all searches are completed.
Code Example 17-20 ldap_getfilter_free Code Example
#include <ldap.h>
...
LDAPFiltDesc *lfdp;
char *filter_file = "myfilters.conf";
...
/* Read the filter configuration file into an LDAPFiltDesc structure */
lfdp = ldap_init_getfilter( filter_file );
...
/* Retrieve filters and perform searches */
...
/* Free the configuration file (the LDAPFiltDesc structure) */
ldap_getfilter_free( lfdp );
...
See Also
ldap_init_getfilter(), ldap_init_getfilter_buf()
ldap_getfirstfilter()The ldap_getfirstfilter() function retrieves the first filter that is appropriate for a given value.
Syntax
#include <ldap.h>
LDAPFiltInfo * ldap_getfirstfilter( LDAPFiltDesc *lfdp,
char *tagpat, char *value );Parameters
This function has the parameters listed in Table 17-101.
Table 17-101 ldap_getfirstfilter() Function Parameters
Parameter
Description
lfdp
Pointer to an LDAPFiltDesc structure.
tagpat
Regular expression for a tag in the filter configuration.
value
Value for which to find the first appropriate filter.
Returns
One of the following values:
- 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
For more information, see "Retrieving Filters" of Chapter 6, "Using Filter Configuration Files."
Example
Code Example 17-21 is based on the getfilt command-line program example provided with the LDAP SDK for C. The program prompts the user to enter search criteria and, based on the criteria entered, it retrieves filters that match the criteria. Code Example 17-21 uses the filter configuration file shown in "The Filter Configuration File Syntax" of Chapter 6, "Using Filter Configuration Files."
Code Example 17-21 ldap_getfirstfilter() Code Example
#include <stdio.h>
#include <ldap.h>
...
LDAP *ld;
LDAPMessage *result, *e;
BerElement *ber;
char *a, *dn;
char **vals;
int i;
LDAPFiltDesc *ldfp;
LDAPFiltInfo *ldfi;
char buf[ 80 ]; /* Contains the search criteria */
int found;
...
/* Load the filter configuration file into an LDAPFiltDesc structure */
if ( ( ldfp = ldap_init_getfilter( "myfilters.conf" ) ) == NULL ) {
perror( "Cannot open filter configuration file" );
return( 1 );
}
/* Read a string to search for */
printf( "Enter a string to search for: " );
gets( buf );
if ( strlen( buf ) == 0 ) {
fprintf( stderr, "usage: %s search-string\n", argv[ 0 ]);
return( 1 );
}
/* Select a filter to use when searching for the value in buf */
found = 0;
for ( ldfi = ldap_getfirstfilter( ldfp, "people", buf ); ldfi != NULL; ldfi = ldap_getnextfilter( ldfp ) ) {
/* Use the selected filter to search the directory */
if ( ldap_search_s( ld, "dc=example,dc=com, ldfi->lfi_scope,
ldfi->lfi_filter, NULL, 0, &result ) != LDAP_SUCCESS ) {
ldap_perror( ld, "ldap_search_s" );
return( 1 );
} else {
/* Once a filter gets results back, stop iterating through the different filters */
if ( ( found = ldap_count_entries( ld, result ) > 0 ) ) {
break;
} else {
ldap_msgfree( result );
}
}
}
if ( found == 0 ) {
printf( "No matching entries found.\n" );
} else {
printf( "Found %d %s match%s for \"%s\"\n\n", found,
ldfi->lfi_desc, found == 1 ? "" : "es", buf );
}
ldap_msgfree( result );
ldap_getfilter_free( ldfp );
...
See Also
ldap_init_getfilter(), ldap_init_getfilter_buf(), ldap_getnextfilter()
ldap_get_lang_values()
Caution
This function is deprecated and should not be used. It is included in ldap-deprecated.h for backward-compatibility. Please use ldap_get_values().
The ldap_get_lang_values() function returns a NULL-terminated array of an attribute’s string values that match a specified language subtype.
Syntax
#include <ldap.h>
char ** ldap_get_lang_values( LDAP *ld, LDAPMessage *entry,
const char *target, char **type );Parameters
This function has the parameters listed in Table 17-102.
Table 17-102 ldap_get_lang_values() Function Parameters
Parameters
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
entry
Entry retrieved from the directory.
target
Attribute type (including an optional language subtype) that you want to retrieve the values of.
type
Pointer to a buffer that returns the attribute type retrieved by this function.
Returns
One of the following values:
- If successful, returns a NULL-terminated array of the attribute’s values.
- If unsuccessful or if no such attribute exists in the entry, returns a NULL and sets the appropriate error code in the LDAP structure. To get the error code, call the ldap_get_lderrno() function.
See Chapter 18, "Result Codes" for a complete listing of error codes.
Description
Unlike the ldap_get_values() function, if a language subtype is specified, this function first attempts to find and return values that match that subtype (for example, cn;lang-en). If you want to retrieve binary data from an attribute, call the ldap_get_lang_values_len() function.
See Also
ldap_first_entry(), ldap_first_attribute(), ldap_get_lang_values_len(), ldap_get_values(), ldap_next_entry(), ldap_next_attribute()
ldap_get_lang_values_len()
Caution
This function is deprecated and should not be used. It is included in ldap-deprecated.h for backward-compatibility. Please use ldap_get_values_len().
The ldap_get_lang_values_len() function returns a NULL-terminated array of pointers to berval structures, each containing the length and pointer to a binary value of an attribute for a given entry.
Syntax
#include <ldap-deprecated.h>
struct berval ** ldap_get_lang_values_len( LDAP *ld,
LDAPMessage *entry, const char *target, char **type );Parameters
This function has the parameters listed in Table 17-103.
Table 17-103 ldap_get_lang_values_len() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
entry
Result returned by the ldap_result() or ldap_search_s() function.
target
Attribute returned by ldap_first_attribute() or ldap_next_attribute(), or the attribute as a literal string, such as "jpegPhoto" or “audio”.
type
Pointer to a buffer that returns the attribute type retrieved by this function.
Returns
One of the following values:
- If successful, returns a NULL-terminated array of pointers to berval structures, which, in turn, contain pointers to the attribute’s binary values.
- If unsuccessful or if no such attribute exists in the entry, returns a NULL and sets the appropriate error code in the LDAP structure. To get the error code, call the ldap_get_lderrno() function.
See Chapter 18, "Result Codes" for a complete listing of error codes.
Description
Use the ldap_get_lang_values() routine if the attribute values are string values.
For more information, see "Getting the Values of an Attribute" of Chapter 5, "Searching a LDAP Directory."
See Also
ldap_first_attribute(), ldap_first_entry(), ldap_get_lang_values(), ldap_next_entry(), ldap_next_attribute()
ldap_get_lderrno()The ldap_get_lderrno() function gets information about the last error that occurred for an LDAP operation.
Syntax
#include <ldap.h>
int ldap_get_lderrno( LDAP *ld, char **m, char **s );Parameters
This function has the parameters listed in Table 17-104.
Table 17-104 ldap_get_lderrno() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
m
In the event of an LDAP_NO_SUCH_OBJECT error return, this parameter contains the portion of the DN that identifies an existing entry. (See "Receiving the Matching Portion of a DN" of Chapter 4, "Using the LDAP API.")
s
The text of the error message.
Returns
The LDAP error code for the last operation. See Chapter 18, "Result Codes" for a complete listing of error codes.
Description
ldap_get_lderrno() gets information about the last error that occurred for an LDAP operation. You can also call this function to get error codes for functions that do not return errors (such as ldap_next_attribute()).
For more information, see "Getting Information About an Error" of Chapter 4, "Using the LDAP API."
Example
Code Example 17-22 attempts to add a new user to the directory. If the entry identified by a DN does not exist, the server returns the portion of the DN that matches an existing entry; this is the variable matched. (See "Receiving the Matching Portion of a DN" of Chapter 4, "Using the LDAP API" for details.)
Code Example 17-22 ldap_get_lderrno() Code Example
#include <ldap.h>
LDAP *ld;
char *dn = "uid=bjensen,ou=People,dc=example,dc=com";
LDAPMod **list_of_attrs;
char *matched;
int rc;
...
if ( ldap_add_s( ld, dn, list_of_attrs ) != LDAP_SUCCESS ) {
rc = ldap_get_lderrno( ld, &matched, NULL );
return( rc );
}
...
In Code Example 17-22, if no organizational unit named People exists, the matched variable is set to dc=example,dc=com.
See Also
ldap_err2string(), ldap_perror(), ldap_result2error(), ldap_set_lderrno()
ldap_getnextfilter()The ldap_getnextfilter() function retrieves the next filter that is appropriate for a given value.
Syntax
#include <ldap.h>
LDAPFiltInfo * ldap_getnextfilter( LDAPFiltDesc *lfdp );Parameters
This function has the parameter listed in Table 17-105.
Table 17-105 ldap_getnextfilter() Function Parameter
Parameter
Description
lfdp
Pointer to an LDAPFiltDesc structure.
Returns
One of the following values:
- 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().
For more information, see "Retrieving Filters" of Chapter 6, "Using Filter Configuration Files."
Example
See Code Example 17-21 under ldap_getfirstfilter().
See Also
ldap_get_option()The function ldap_get_option() retrieves session preferences from an LDAP structure.
Syntax
#include <ldap.h>
int ldap_get_option( LDAP *ld, int option, void *optdata );Parameters
This function has the parameters listed in Table 17-106.
Table 17-106 ldap_get_option() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
option
Option that you want to retrieve. This parameter must be set to one of the option values, as detailed in Table 17-107.
optdata
Pointer to the buffer in which the value of the option will be put.
Table 17-107 describes the options that you can retrieve with ldap_get_option().
Table 17-107 Options for the ldap_get_options() Function
Option
Description
LDAP_OPT_API_FEATURE_INFO
Retrieves information about the revision of a supported LDAP feature. This option is READ-ONLY and cannot be set.
The data type for the optdata parameter is (LDAPAPIFeatureInfo *).
LDAP_OPT_API_INFO
Retrieves information about the API implementation at execution time (API version, protocol version, the names of supported API extensions with their vendor name version, etc.). For details on the structure returned, refer to the ldap.h header file. This option is READ-ONLY and cannot be set.
The data type for the optdata parameter is (LDAPAPIInfo *).
LDAP_OPT_CLIENT_CONTROLS
Pointer to an array of LDAPControl structures representing the LDAPv3 client controls you want sent with every request by default.
The data type for the optdata parameter is (LDAPControl ***).
LDAP_OPT_DESC
Socket descriptor underlying the main LDAP connection. The LBER_SOCKET data type depends on the platform that you are using:
The data type for the optdata parameter is (LBER_SOCKET *).
LDAP_OPT_DEREF
Determines how aliases work during a search. optdata can be one of the following values:
- LDAP_DEREF_NEVER specifies that aliases are never dereferenced.
- LDAP_DEREF_SEARCHING specifies that aliases are dereferenced when searching under the base object (but not when finding the base object).
- LDAP_DEREF_FINDING specifies that aliases are dereferenced when finding the base object (but not when searching under the base object).
- LDAP_DEREF_ALWAYS specifies that aliases are always dereferenced when finding and searching under the base object.
The data type for the optdata parameter is (int *).
LDAP_OPT_DNS_FN_PTRS
DEPRECATED OPTION: Lets you use alternate DNS functions for getting the host entry of the LDAP server.
The data type for the optdata parameter is (struct ldap_dns_fns *).
LDAP_OPT_ERROR_NUMBER
Retrieves the result code for the most recent LDAP error that occurred in this session.
The data type for the optdata parameter is (int *).
LDAP_OPT_ERROR_STRING
Retrieves the error message returned with the result code for the most recent LDAP error that occurred in this session.
The data type for the optdata parameter is (char **).
LDAP_OPT_EXTRA_THREAD_FN_PTRS
Lets you specify the locking and semaphore functions that you want called when getting results from the server. (See Chapter 14, "Writing Multithreaded Clients" for details.)
The data type for the optdata parameter is (struct ldap_extra_thread_fns *).
LDAP_OPT_HOST_NAME
Sets the host name (or list of hosts) for the primary LDAP server.
The data type for the optdata parameter is (char **).
LDAP_OPT_IO_FN_PTRS
DEPRECATED OPTION: Lets you use alternate communication stacks.
The data type for the optdata parameter is (struct ldap_io_fns *).
LDAP_OPT_MATCHED_DN
Gets the matched DN value returned with the most recent LDAP error that occurred for this session.
The data type for the optdata parameter is (char **)
LDAP_OPT_MEMALLOC_FN_PTRS
Gets a pointer to the callback structure which you previously set.
The data type for the optdata parameter is (struct ldap_memalloc_fnsldap_io_fns *).
LDAP_OPT_PROTOCOL_VERSION
Version of the protocol supported by your client. You can specify either LDAP_VERSION2 or LDAP_VERSION3. If no version is set, the default is LDAP_VERSION2. In order to use LDAPv3 features, you need to set the protocol version to LDAP_VERSION3.
The data type for the optdata parameter is (int *).
LDAP_OPT_REBIND_ARG
Lets you set the last argument passed to the routine specified by LDAP_OPT_REBIND_FN. You can also set this option by calling the ldap_set_rebind_proc() function.
The data type for the optdata parameter is (void *).
LDAP_OPT_REBIND_FN
Lets you set the routine to be called when you need to authenticate a connection with another LDAP server (for example, during the course of following a referral). You can also set this option by calling the ldap_set_rebind_proc() function.
The data type for the optdata parameter is (LDAP_REBINDPROC_CALLBACK *).
LDAP_OPT_RECONNECT
If the connection to the server is lost, determines whether or not the same connection handle should be used to reconnect to the server. By default, this option is off. For details, see "Handling Failover" of Chapter 4, "Using the LDAP API." optdata can be one of the following values:
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:
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:
The data type for the optdata parameter is (int *).
LDAP_OPT_SERVER_CONTROLS
Pointer to an array of LDAPControl structures representing the LDAPv3 server controls you want sent with every request by default. Typically, since controls are specific to the type of request, you may want to pass the controls using operation-specific functions (such as ldap_add_ext()) instead.
The data type for the optdata parameter is (LDAPControl ***).
LDAP_OPT_SIZELIMIT
Maximum number of entries that should be returned by the server in search results. The LDAP server may impose a smaller size limit than the limit you specify as the server administrator also has the ability to set this limit.
The data type for the optdata parameter is (int *).
LDAP_OPT_SSL
Determines whether or not SSL is enabled. optdata can be one of the following values:
The data type for the optdata parameter is (int *).
LDAP_OPT_THREAD_FN_PTRS
Lets you specify the thread function pointers. (See Chapter 14, "Writing Multithreaded Clients" for details.)
The data type for the optdata parameter is (struct ldap_thread_fns *).
LDAP_OPT_TIMELIMIT
Maximum number of seconds that should be spent by the server when answering a search request. The LDAP server may impose a shorter time limit than the limit you specify as the server administrator also has the ability to set this limit.
The data type for the optdata parameter is (int *).
LDAP_X_OPT_EXTIO_FN_PTRS
Extended I/O function callback option.
LDAP_X_OPT_CONNECT_TIMEOUT
Value of a timeout (expressed in milliseconds) for nonblocking connect call.
The data type for the optdata parameter is (int *).
LDAP_X_OPT_SOCKBUF
Socket buffer structure associated to the LDAP connection.
Returns
One of the following values:
- LDAP_SUCCESS if successful.
- -1 if unsuccessful.
Description
For more information, see "Retrieving SDK Information" of Chapter 4, "Using the LDAP API."
Examples
Code Example 17-23 gets the session preference for the maximum number of entries to be returned from search operations.
Code Example 17-23 ldap_get_option() Code Example
#include <ldap.h>
...
LDAP *ld;
int max_ret;
...
/* Get the maximum number of entries returned */
if (ldap_get_option, LDAP_OPT_SIZELIMIT, &max_ret) != LDAP_SUCCESS) {
ldap_perror( ld, "ldap_get_option" );
return( 1 );
}
Code Example 17-24 contains two small sections of code that show how to use the LDAP_OPT_API_FEATURE_INFO and the LDAP_OPT_API_INFO options, respectively.
Code Example 17-24 LDAP_OPT_API_FEATURE_INFO and LDAP_OPT_API_INFO Usage
LDAPIIFeatureInfo ldfi;
ldfi.ldapaif_info_version = LDAP_FEATURE_INFO_VERSION;
ldfi.ldapaif_name = "VIRTUAL_LIST_VIEW";
if (ldap_get_option(NULL, LDAP_OPT_API_FEATURE_INFO, &ldfi)==0) {
/* use the info here */ }
LDAPIInfo ldai;
ldai.ldapiai_info_version = LDAP_API_INFO_VERSION;
if (ldap_get_option( NULL, LDAP_OPT_API_INFO, &ldia ) == 0) {
/* use the ldai info here */
}
See Also
ldap_init(), ldap_set_option()
ldap_get_values()The ldap_get_values() function returns a NULL-terminated array of an attribute’s string values for a given entry.
Syntax
#include <ldap.h>
char ** ldap_get_values( LDAP *ld, LDAPMessage *entry,
const char *target );Parameters
This function has the parameters listed in Table 17-108.
Table 17-108 ldap_get_values() Function Parameters
Parameters
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
entry
Result returned by the ldap_result() or ldap_search_s() function.
target
Attribute returned by ldap_first_attribute() or ldap_next_attribute(), or the attribute as a literal string, such as jpegPhoto or audio.
Returns
One of the following values:
- If successful, returns a NULL-terminated array of the attribute’s values.
- If unsuccessful or if no such attribute exists in the entry, returns a NULL and sets the appropriate error code in the LDAP structure. To get the error code, call the ldap_get_lderrno() function.
See Chapter 18, "Result Codes" for a complete listing of error codes.
Description
Use the ldap_get_values_len() function if the attribute values are binary.
For more information, see "Getting the Values of an Attribute" of Chapter 5, "Searching a LDAP Directory."
Example
Code Example 17-25 gets and prints the values of an attribute in an entry. This example assumes that all attributes have string values.
Code Example 17-25 ldap_get_values() Code Example
#include <stdio.h>
#include <ldap.h>
...
LDAP *ld;
LDAPMessage *result, *e;
BerElement *ber;
char *a;
char **vals;
char *my_searchbase = "dc=example,dc=com";
char *my_filter = "(sn=Jensen)";
int i;
...
/* Search the directory */
if ( ldap_search_s( ld, my_searchbase, LDAP_SCOPE_SUBTREE, my_filter,
NULL, 0, &result ) != LDAP_SUCCESS ) {
ldap_perror( ld, "ldap_search_s" );
return( 1 );
}
/* Get the first matching entry.*/
e = ldap_first_entry( ld, result );
/* Get the first matching attribute */
a = ldap_first_attribute( ld, e, &ber );
/* Get the values of the attribute */
if ( ( vals = ldap_get_values( ld, e, a ) ) != NULL ) {
for ( i = 0; vals[i] != NULL; i++ ) {
/* Print the name of the attribute and each value */
printf( "%s: %s\n", a, vals[i] );
}
/* Free the attribute values from memory when done. */
ldap_value_free( vals );
}
...
See Also
ldap_first_entry(), ldap_first_attribute(), ldap_get_values_len(), ldap_next_entry(), ldap_next_attribute()
ldap_get_values_len()The ldap_get_values_len() function returns a NULL-terminated array of pointers to berval structures, each containing the length and pointer to a binary value of an attribute for a given entry.
Syntax
#include <ldap.h>
struct berval ** ldap_get_values_len( LDAP *ld,
LDAPMessage *entry, const char *target );Parameters
This function has the parameters listed in Table 17-109.
Table 17-109 ldap_get_values_len() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
entry
Result returned by the ldap_result() or ldap_search_s() function.
target
Attribute returned by ldap_first_attribute() or ldap_next_attribute(), or the attribute as a literal string, such as jpegPhoto or audio.
Returns
One of the following values:
- 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.
See Chapter 18, "Result Codes" for a complete listing of error codes.
Description
Use the ldap_get_values() routine if the attribute values are string values.
For more information, see "Getting the Values of an Attribute" of Chapter 5, "Searching a LDAP Directory."
Example
Code Example 17-26 gets the first value of the jpegPhoto attribute and saves the JPEG data to a file.
Code Example 17-26 ldap_get_values_len() Code Example
#include <stdio.h>
#include <ldap.h>
...
LDAP *ld;
LDAPMessage *result, *e;
BerElement *ber;
struct berval photo_data;
struct berval **list_of_photos;
FILE *out;
char *my_searchbase = "dc=example,dc=com";
char *my_filter = "(sn=Jensen)";
...
/* Search the directory */
if ( ldap_search_s( ld, my_searchbase, LDAP_SCOPE_SUBTREE, my_filter, NULL,
0, &result ) != LDAP_SUCCESS ) {
ldap_perror( ld, "ldap_search_s" );
return( 1 );
}
/* Get the first matching entry.*/
e = ldap_first_entry( ld, result );
/* Get the value of the jpegPhoto attribute */
if ( ( list_of_photos = ldap_get_values_len( ld, e, "jpegPhoto" ) ) != NULL ) {
/* Prepare to write the JPEG data to a file */
if ( ( out = fopen( "photo.jpg", "wb" ) ) == NULL ) {
perror( "fopen" );
return( 1 );
}
/* Get the first JPEG */
photo_data = *list_of_photos[0];
/* Write the JPEG data to a file */
fwrite( photo_data.bv_val, photo_data.bv_len, 1, out );
fclose( out );
/* Free the attribute values from memory when done. */
ldap_value_free_len( list_of_photos );
}
...
See Also
ldap_first_entry(), ldap_first_attribute(), ldap_get_values(), ldap_next_entry(), ldap_next_attribute()
ldap_init()The ldap_init() function initializes a session with an LDAP server and returns an LDAP structure that represents the context of the connection to that server.
Syntax
#include <ldap.h>
LDAP * ldap_init( const char *defhost, int defport );Parameters
This function has the parameters listed in Table 17-110.
Table 17-110 ldap_init() Function Parameters
Parameter
Description
defhost
Space-delimited list of one or more host names (or IP address in dotted notation, such as "141.211.83.36") of the LDAP servers that you want the LDAP client to connect to. The names can be in hostname:portnumber format (in which case, portnumber overrides the port number specified by the defport argument.
defport
Default port number of the LDAP server. To specify the standard LDAP port (port 389), use LDAP_PORT as the value for this parameter.
Returns
One of the following values:
- 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 LDAPv2. It is highly recommended to set it to LDAPv3 using the ldap_set_option().)
Caution
ldap_init() does not open a connection to the LDAP server. The actual connection opening will occur when the first operation is attempted. Certain fields in the LDAP structure can be set using ldap_set_option().
You can specify a list of LDAP servers to which you want to attempt to connect by passing a space-delimited list of the host names as the defhost argument. Your client will attempt to connect to the first LDAP server in the list. If the attempt fails, your client will attempt to connect to the next LDAP server in the list. In Code Example 17-27, the LDAP client will attempt to connect to the LDAP server on ld1.example.com, port 389. If that server does not respond, the client will attempt to connect to the LDAP server on ld2.example.com, port 389. If that server does not respond, the client will use the server on ld3.example.com, port 389.
Code Example 17-27 Space-Delimited List for ldap_init()
...
LDAP *ld
...
ld = ldap_init( "ld1.example.com ld2.example.com \
ld3.example.com", LDAP_PORT );
If any of the servers do not use the default port specified by the defport argument, use the hostname:portnumber format to specify the server name. In Code Example 17-28, the LDAP client will attempt to connect to the LDAP server on ld1.example.com, port 389. If that server does not respond, the client will attempt to connect to the LDAP server on ld2.example.com, port 38900.
Code Example 17-28 ldap_init() Example Using Variable Argument
...
LDAP *ld
...
ld = ldap_init( "ld1.example.com ld2.example.com:38900", \ LDAP_PORT );
For more information, see "Initializing an LDAP Session" of Chapter 3, "Writing an LDAP Client."
Note
If you are connecting to a secure LDAP server over SSL, you should be calling the ldapssl_init() function. For details, see Chapter 11, "Connecting Over SSL."
Example
Code Example 17-29 initializes a session with the LDAP server at ldap.example.com:389, and sets a session preference that identifies the client as an LDAPv3 client.
Code Example 17-29 ldap_init() Code Example
#include <ldap.h>
...
LDAP *ld;
/* Specify the host name of the LDAP server. */
char *ldap_host = "ldap.example.com";
/* Because the LDAP server is running on the standard LDAP port (port 389), you can use LDAP_PORT to identify the port number. */
int ldap_port = LDAP_PORT;
...
/* Initialize the session with ldap.example.com:389 */
if ( ( ld = ldap_init( ldap_host, ldap_port ) ) == NULL ) {
perror( "ldap_init" );
return( 1 );
}
/* Specify the LDAP version supported by the client. */
version = LDAP_VERSION3;
ldap_set_option( ld, LDAP_OPT_PROTOCOL_VERSION, &version );
...
/* Subsequent calls that authenticate to the LDAP server. */
...
See Also
ldap_unbind(), ldap_unbind_s(), ldap_simple_bind(), ldap_simple_bind_s()
ldap_init_getfilter()The ldap_init_getfilter() function reads a valid LDAP filter configuration file (such as ldapfilter.conf) and returns a pointer to an LDAPFiltDesc structure.
Note
ldapfilter.conf, the sample LDAP filter configuration file located in the DSRK_base/lib/ldapcsdk/etc directory, can be used in context with ldap_init_getfilter().
Syntax
#include <ldap.h>
LDAPFiltDesc * ldap_init_getfilter( char *fname );Parameters
This function has the parameters listed in Table 17-111.
Table 17-111 ldap_init_getfilter() Function Parameter
Parameter
Description
fname
Name of the LDAP filter configuration file to use.
Returns
One of the following values:
- If successful, returns a pointer to an LDAPFiltDesc structure.
- If unsuccessful (for example, if there is an error reading the file), returns a NULL.
Description
For more information, see "Loading a Filter Configuration File" of Chapter 6, "Using Filter Configuration Files."
Example
Code Example 17-30 loads a filter configuration file named myfilters.conf into memory.
Code Example 17-30 Loading a Filter Configuration File
#include <ldap.h>
...
LDAPFiltDesc *lfdp;
char *filter_file = "myfilters.conf";
...
lfdp = ldap_init_getfilter( filter_file );
...
See Also
ldap_init_getfilter_buf(), ldap_getfilter_free()
ldap_init_getfilter_buf()The ldap_init_getfilter_buf() function reads LDAP filter configuration information from a buffer and returns a pointer to an LDAPFiltDesc structure.
Syntax
#include <ldap.h>
LDAPFiltDesc * ldap_init_getfilter_buf(char *buf, long buflen );Parameters
This function has the parameters listed in Table 17-112.
Table 17-112 ldap_init_getfilter_buf() Function Parameters
Parameter
Description
buf
Buffer containing LDAP filter configuration information.
buflen
Size of the buffer
Returns
One of the following values:
- If successful, returns a pointer to an LDAPFiltDesc structure.
- If unsuccessful (for example, if there is an error reading the file), returns a NULL.
Description
The configuration information in the buffer must use the correct syntax, as specified in "The Filter Configuration File Syntax" of Chapter 6, "Using Filter Configuration Files."
Example
Code Example 17-31 copies the following filter configuration to a buffer in memory and uses this buffer to fill an LDAPFiltDesc structure.
"ldap-example"
"@" " " "(mail=%v)" "email address"
"(mail=%v*)" "start of email address"
Code Example 17-31 ldap_init_getfilter() Code Example
#include <string.h>
#include <ldap.h>
...
LDAPFiltDesc *lfdp;
char filtbuf[ 1024 ];
...
/* Create the filter config buffer */
strcpy( filtbuf, "\"ldap-example\"\n" );
strcat( filtbuf, " \"@\"\t\" \"\t\"(mail=%v)\"\t\"email address\"\n" );
strcat( filtbuf, " \t\t\"(mail=%v*)\"\t\"start of email address\"\n" );
lfdp = ldap_init_getfilter( filtbuf, strlen( filtbuf ) );
...
See Also
ldap_init_getfilter(), ldap_getfilter_free()
ldap_init_searchprefs()The ldap_init_searchprefs() function reads a sequence of search preference configurations from a valid LDAP searchpref configuration file.
Syntax
#include <ldap.h>
int ldap_init_searchprefs( char *file, struct ldap_searchobj **solistp );Parameters
This function has the parameters listed in Table 17-113.
Table 17-113 ldap_init_searchprefs() Function Parameters
Parameter
Description
file
Pointer to a valid LDAP searchpref configuration file.
solistp
Pointer to a list of search preference data structures.
Returns
One of the following values:
Description
ldap_init_searchprefs() provides a standard way to access LDAP search preference configuration data.
Note
LDAP search preference configurations are typically used by LDAP client programs to specify which attributes a user may search by, labels for the attributes, and LDAP filters and scopes associated with those searches. Client software presents these choices to a user, who can then specify the type of search to be performed. See the man page for ldapsearchprefs.conf for more information.
See Also
ldap_free_searchprefs(), ldap_init_searchprefs_buf()
ldap_init_searchprefs_buf()The ldap_init_searchprefs_buf() function reads a sequence of search preference configurations from the parameter, buf.
Syntax
#include <ldap.h>
int ldap_init_searchprefs_buf( char *buf, long buflen,
struct ldap_searchobj **solistp );Parameters
This function has the parameters listed in Table 17-114.
Table 17-114 ldap_init_searchprefs_buf() Function Parameters
Parameter
Description
buf
Pointer to data in the format defined for an LDAP search preference configuration file.
buflen
The size of buf.
solistp
Pointer to a list of search preference data structures.
Returns
One of the following values:
Description
ldap_init_searchprefs_buf() reads a sequence of search preference configurations from buf.
Note
LDAP search preference configurations are typically used by LDAP client programs to specify which attributes a user may search by, labels for the attributes, and LDAP filters and scopes associated with those searches. Client software presents these choices to a user, who can then specify the type of search to be performed. See the man page for ldapsearchprefs.conf for more information.
See Also
ldap_init_searchprefs(), ldap_free_searchprefs()
ldap_init_templates()The ldap_init_templates() function reads a sequence of templates from a valid LDAP template configuration file.
Syntax
#include <disptmpl.h>
int ldap_init_templates( char *file, struct ldap_disptmpl **tmpllistp );Parameters
This function has the parameters listed in Table 17-115.
Table 17-115 ldap_init_templates() Function Parameters
Parameter
Description
file
Pointer to a valid LDAP template configuration file.
tmpllistp
Pointer to a list of template data structures.
Returns
Description
ldap_init_templates() reads a sequence of templates from a valid LDAP template configuration file. Each template defined in the file is an ldap_disptmpl structure.
See Also
ldap_init_templates_buf(), ldap_free_templates()
ldap_init_templates_buf()The ldap_init_templates_buf() function reads a sequence of templates from a buffer.
Syntax
#include <disptmpl.h>
int ldap_init_templates_buf( char *buf, long buflen,
struct ldap_disptmpl **tmpllistp );Parameters
This function has the parameters listed in Table 17-116.
Table 17-116 ldap_init_templates_buf() Function Parameters
Parameter
Description
buf
Pointer to data in the format defined for a valid LDAP template configuration file.
buflen
The size of buf.
tmpllistp
Pointer to a list of template data structures.
Returns
Description
The ldap_init_templates_buf() function reads a sequence of templates from a buffer.
See Also
ldap_init_templates(), ldap_free_templates()
ldap_is_dns_dn()
Caution
This function is deprecated and should not be used. It is included in ldap-to-be-deprecated.h for backward-compatibility.
The ldap_is_dns_dn() function determines whether a DN string is of the experimental DNS-style DN (generally in the form of an RFC 822 e-mail address) or the RFC 1779 formatted DN.
Description
This function is specific to LDAPv2 and should not be used when dealing with LDAPv3 servers or data.
Note
More information can be found in RFC 1779 - A String Representation of Distinguished Names (http://www.faqs.org/rfcs/rfc1779.html) and RFC 822 - Standard for the Format of ARPA Internet Text Messages (http://www.faqs.org/rfcs/rfc822.html).
ldap_is_ldap_url()The ldap_is_ldap_url() function determines whether or not a URL is an LDAP URL.
Syntax
#include <ldap.h>
int ldap_is_ldap_url( const char *url );Parameters
This function has the parameter listed in Table 17-117.
Table 17-117 ldap_is_ldap_url() Function Parameter
Parameter
Description
url
The URL that you want to check.
Returns
One of the following values:
Description
The ldap_is_ldap_url() function determines whether or not a URL is an LDAP URL. An LDAP URL is a URL with the protocol set to ldap:// (or ldaps://, if the server is communicating over a SSL connection).
For more information, see "Determining an LDAP URL" of Chapter 9, "Working with LDAP URLs."
Example
Code Example 17-32 determines if a URL is a LDAP URL.
Code Example 17-32 ldap_is_ldap_url() Code Example
#include <stdio.h>
#include <ldap.h>
...
char *my_url = "ldap://ldap.sun.com/dc=example,dc=com";
...
if ( ldap_is_ldap_url( my_url ) != 0 ) {
printf( "%s is an LDAP URL.\n", my_url );
} else {
printf( "%s is not an LDAP URL.\n", my_url );
}
...
See Also
ldap_keysort_entries()The ldap_keysort_entries() function is used for sorting entries.
Syntax
#include <ldap-extension.h>
int ldap_keysort_entries( LDAP *ld, LDAPMessage **chain,
void *arg, LDAP_KEYGEN_CALLBACK *gen, LDAP_KEYCMP_CALLBACK *cmp,
LDAP_KEYFREE_CALLBACK *fre );Parameters
This function has the parameters listed in Table 17-118.
Table 17-118 ldap_keysort_entries() Function Parameter
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
chain
Chain of entries returned by the ldap_result() or ldap_search_s() function.
arg
Pointer to an additional argument that you want to pass.
gen
Callback used to generate the key(s) for sorting once the compare function has been applied.
cmp
Comparison function used when sorting the values. For details, see "Sorting Entries by an Attribute" of Chapter 5, "Searching a LDAP Directory."
fre
Callback used to free the key once the compare function has been applied.
See Also
LDAP_KEYGEN_CALLBACK, LDAP_KEYCMP_CALLBACK, LDAP_KEYFREE_CALLBACK
ldap_memcache_destroy()The ldap_memcache_destroy() function frees an LDAPMemCache structure from memory.
Syntax
#include <ldap.h>
void ldap_memcache_destroy( LDAPMemCache *cache );Parameters
This function has the parameter listed in Table 17-119.
Table 17-119 ldap_memcache_destroy() Function Parameter
Parameter
Description
cache
Pointer to the LDAPMemCache structure that you want freed from memory.
Description
The ldap_memcache_destroy() function frees the specified LDAPMemCache structure from memory. Call this function after you are done working with a cache.
See Also
ldap_memcache_flush()The ldap_memcache_flush() function flushes items from the specified cache.
Syntax
#include <ldap.h>
void ldap_memcache_flush( LDAPMemCache *cache, char *dn,
int scope );Parameters
This function has the parameters listed in Table 17-120.
Table 17-120 ldap_memcache_flush() Function Parameters
Parameter
Description
cache
Pointer to the LDAPMemCache structure that you want to flush entries from.
dn
Base DN identifying the search requests that you want flushed from the cache. If the base DN of a search request is within the scope specified by this DN and the scope argument, the search request is flushed from the cache. If this argument is NULL, the entire cache is flushed.
scope
Scope that (together with the dn argument) identifies the search requests that you want flushed from the cache. If the base DN of the request is within the scope specified by this argument and the dn argument, the request is flushed from the cache. This argument can have one of the following values:
Description
The ldap_memcache_flush() function flushes search requests from the cache. If the base DN of a search request is within the scope specified by the dn and scope arguments, the search request is flushed from the cache. If no DN is specified, the entire cache is flushed.
ldap_memcache_get()The ldap_memcache_get() function gets the in-memory cache associated with an LDAP connection handle.
Syntax
#include <ldap.h>
int ldap_memcache_get( LDAP *ld, LDAPMemCache **cachep );Parameters
This function has the parameters listed in Table 17-121.
Table 17-121 ldap_memcache_get() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
cachep
When you call ldap_memcache_get(), it sets this parameter to the pointer to the LDAPMemCache structure associated with the connection handle.
Returns
One of the following values:
- 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_init()The ldap_memcache_init() function creates an in-memory cache for your LDAP client that you can associate with an LDAP connection.
Syntax
#include <ldap.h>
int ldap_memcache_init( unsigned long ttl, unsigned long size,
char **baseDNs, struct ldap_thread_fns *thread_fns,
LDAPMemCache **cachep );Parameters
This function has the parameters listed in Table 17-122.
Table 17-122 ldap_memcache_init() Function Parameters
Parameter
Description
ttl
The maximum amount of time (in seconds) that an item can be cached. If 0, there is no limit to the amount of time that an item can be cached.
size
Maximum amount of memory (in bytes) that the cache will consume. If 0, the cache has no size limit.
baseDNs
An array of the base DN strings representing the base DNs of the search requests you want cached. If not NULL, only the search requests with the specified base DNs will be cached. If NULL, all search requests are cached.
thread_fns
An ldap_thread_fns structure specifying the functions that you want used to ensure that the cache is thread-safe. You should specify this if you have multiple threads that are using the same connection handle and cache. If you are not using multiple threads, pass NULL for this parameter.
cachep
When you call this function, it sets this parameter to the pointer to the newly created LDAPMemCache structure.
Returns
One of the following values:
- 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.
Caution
On Windows� NT, if the ldap_memcache_init() function returns an LDAP_PARAM_ERROR result code, verify that your client is using the version of the nsldap32v30.dll file provided with the LDAP SDK for C, v5.2.
See Also
LDAPMemCache, ldap_memcache_set(), ldap_memcache_flush(), ldap_memcache_destroy(), ldap_memcache_update()
ldap_memcache_set()The ldap_memcache_set() function associates an in-memory cache with an LDAP connection handle.
Syntax
#include <ldap.h>
int ldap_memcache_set( LDAP *ld, LDAPMemCache *cache );Parameters
This function has the parameters listed in Table 17-123.
Table 17-123 ldap_memcache_set() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
cache
Pointer to an LDAPMemCache structure, which represents the cache that you want used for this connection.
Returns
One of the following values:
- 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
This function has the parameter listed in Table 17-124.
Table 17-124 ldap_memcache_update() Function Parameter
Parameter
Description
cache
Pointer to an LDAPMemCache structure, which represents the cache that you want to updated.
Description
The ldap_memcache_update() function checks the cache for items that have expired and removes them. This check is typically done as part of the way the cache normally works. You do not need to call this function unless you want to update the cache at this point in time.
Tip
This function is only useful in a multithreaded application, since it will not return until the cache is destroyed.
See Also
ldap_memfree()The ldap_memfree() function frees memory allocated by an LDAP API function call.
Syntax
#include <ldap.h>
void ldap_memfree( void *p );Parameters
This function has the parameter listed in Table 17-125.
Table 17-125 ldap_memfree() Function Parameter
Parameter
Description
p
Pointer to memory used by the LDAP library.
Description
For more information, see "Managing Memory" of Chapter 4, "Using the LDAP API."
Example
Code Example 17-33 frees the memory allocated by the ldap_get_dn() function.
Code Example 17-33 ldap_memfree() Code Example
#include <ldap.h>
...
LDAP *ld;
char *dn;
LDAPMessage *entry;
...
/* Get the distinguished name (DN) for an entry */
dn = ldap_get_dn( ld, entry );
...
/* When you are finished working with the DN, free the memory allocated for the DN */
ldap_memfree( dn );
...
See Also
ldap_free_friendlymap(), ldap_free_urldesc(), ldap_msgfree(), ldap_value_free(), ldap_value_free_len()
ldap_modify()The ldap_modify() function modifies an existing entry in the directory asynchronously.
Note
This is an older function included in the SDK for backward-compatibility. If you are writing a new LDAP client, use ldap_modify_ext() instead.
Syntax
#include <ldap.h>
int ldap_modify( LDAP *ld, const char *dn, LDAPMod **mods );Parameters
This function has the parameters listed in Table 17-126.
Table 17-126 ldap_modify() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
dn
DN of the entry to modify.
mods
Pointer to a NULL-terminated array of pointers to LDAPMod structures representing the attributes that you want to modify.
Returns
Returns the message ID of the ldap_modify() operation. To check the result of this operation, call ldap_result() and ldap_result2error(). For a list of possible result codes for an LDAP modify operation, see ldap_modify_ext_s().
Description
Please use the newer version of this function, ldap_modify_ext().
Example
Code Example 17-34 uses the asynchronous ldap_modify() function to modify the entry for Barbara Jensen in the directory. It makes the following changes to the entry:
- Adds the homePhone attribute.
- Changes the telephoneNumber attribute.
- Removes the facsimileTelephoneNumber attribute.
Code Example 17-34 ldap_modify() Code Example
#include <ldap.h>
...
LDAP *ld;
LDAPMod *list_of_attrs[4];
LDAPMod attribute1, attribute2, attribute3;
LDAPMessage *result;
int msgid, rc;
struct timeval tv;
/* Distinguished name of the entry that you want to modify. */
char *dn = "uid=bjensen,ou=People,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()The ldap_modify_ext() function modifies an existing entry in the directory asynchronously.
Note
ldap_modify_ext() is a new version of the ldap_modify() function. If you are writing a new LDAP client, use ldap_modify_ext().
Syntax
#include <ldap.h>
int ldap_modify_ext( LDAP *ld, const char *dn, LDAPMod **mods,
LDAPControl **serverctrls, LDAPControl **clientctrls,
int *msgidp );Parameters
This function has the parameters listed in Table 17-127.
Table 17-127 ldap_modify_ext() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
dn
DN of the entry to modify.
mods
Pointer to a NULL-terminated array of pointers to LDAPMod structures representing the attributes that you want to modify.
serverctrls
Pointer to an array of LDAPControl structures representing LDAP server controls that apply to this operation. If you do not want to pass any server controls, specify NULL for this argument.
clientctrls
Pointer to an array of LDAPControl structures representing LDAP client controls that apply to this operation. If you do not want to pass any client controls, specify NULL for this argument.
msgidp
Pointer to an integer that will be set to the message ID of the LDAP operation. To check the result of this operation, call ldap_result() and ldap_parse_result().
Returns
One of the following values:
- 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 LDAPv3. Make sure that you set the version of your LDAP client to version 3 before calling this function. For details, see "Specifying the LDAP Version of Your Client" of Chapter 3, "Writing an LDAP Client."
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.
For more information on modifying entries in the directory, see "Modifying an Entry" of Chapter 17, "Function Reference." For a list of possible result codes for an LDAP modify operation, see ldap_modify_ext_s(). For information on using the LDAPMod structure to specify a change, see "LDAPMod" of Chapter 16, "Data Type Reference."
Example
See Code Example 7-17 of Chapter 7, "Adding, Modifying and Deleting Entries."
See Also
ldap_modify_ext_s(), ldap_result(), ldap_parse_result(), LDAPMod
ldap_modify_ext_s()The ldap_modify_ext_s() modifies an existing entry in the directory synchronously.
Note
ldap_modify_ext_s() is a new version of the ldap_modify_s() function. If you are writing a new LDAP client, use ldap_modify_ext_s().
Syntax
#include <ldap.h>
int ldap_modify_ext_s( LDAP *ld, const char *dn, LDAPMod **mods,
LDAPControl **serverctrls, LDAPControl **clientctrls );Parameters
This function has the parameters listed in Table 17-128.
Table 17-128 ldap_modify_ext_s() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
dn
DN of the entry to modify.
mods
Pointer to a NULL-terminated array of pointers to LDAPMod structures representing the attributes that you want to modify.
serverctrls
Pointer to an array of LDAPControl structures representing LDAP server controls that apply to this operation. If you do not want to pass any server controls, specify NULL for this argument.
clientctrls
Pointer to an array of LDAPControl structures representing LDAP client controls that apply to this operation. If you do not want to pass any client controls, specify NULL for this argument.
Returns
One of the following values:
- 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 LDAPv3. Make sure that you set the version of your LDAP client to version 3 before calling this function. For details, see "Specifying the LDAP Version of Your Client" of Chapter 3, "Writing an LDAP Client."
Description
The ldap_modify_ext_s() modifies an entry in the directory. ldap_modify_ext_s() is a synchronous function, which directly returns the results of the operation. If you want to perform other operations while waiting for the results of this operation, call the asynchronous function ldap_modify_ext() instead.
To make changes to an entry to the directory, you need to specify the following information:
For more information on modifying entries in the directory, see "Modifying an Entry" of Chapter 17, "Function Reference." For information on using the LDAPMod structure to specify a change, see "LDAPMod" of Chapter 16, "Data Type Reference."
Example
See Code Example 7-15 of Chapter 7, "Adding, Modifying and Deleting Entries."
See Also
ldap_modify_s()The ldap_modify_s() function modifies an existing entry in the directory synchronously.
Note
This is an older function that is included in the SDK for backward-compatibility. If you are writing a new LDAP client, use ldap_modify_ext_s() instead.
Syntax
#include <ldap.h>
int ldap_modify_s( LDAP *ld, const char *dn, LDAPMod **mods );Parameters
This function has the parameters listed in Table 17-129.
Table 17-129 ldap_modify_s() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
dn
DN of the entry to modify.
mods
Pointer to a NULL-terminated array of pointers to LDAPMod structures representing the attributes that you want to modify.
Returns
For a list of possible result codes for an LDAP modify operation, see ldap_modify_ext_s().
Description
Please use the newer version of this function, ldap_modify_ext_s().
Example
Code Example 17-35 uses the synchronous ldap_modify_s() function to makes the following changes to the Barbara Jensen entry:
- Adds the homePhone attribute.
- Changes the telephoneNumber attribute.
- Removes the facsimileTelephoneNumber attribute.
Code Example 17-35 ldap_modify_s() Code Example
#include <ldap.h>
...
LDAP *ld;
LDAPMod *list_of_attrs[4];
LDAPMod attribute1, attribute2, attribute3;
LDAPControl **srvrctrls, **clntctrls;
/* Distinguished name of the entry that you want to modify. */
char *dn = "uid=bjensen,ou=People,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_modrdn()
Caution
This function is deprecated and should not be used. It is included in ldap-deprecated.h for backward-compatibility. Please use ldap_rename().
ldap_modrdn_s()
Caution
This function is deprecated and should not be used. It is included in ldap-deprecated.h for backward-compatibility. Please use ldap_rename_s().
ldap_modrdn2()
Caution
This function is deprecated and should not be used. It is included in ldap-deprecated.h for backward-compatibility. Please use ldap_rename() instead.
The ldap_modrdn2() function changes the relative distinguished name (RDN) of an entry in the directory asynchronously.
Syntax
#include <ldap-deprecated.h>
int ldap_modrdn2( LDAP *ld, const char *dn, const char *newrdn,
int deleteoldrdn );Parameters
This function has the parameters listed in Table 17-130.
Table 17-130 ldap_modrdn2() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
dn
DN of the entry to modify.
newrdn
New RDN to assign to the entry.
deleteoldrdn
If this is a non-zero value, the old RDN is not retained as a value in the modified entry. If 0, the old RDN is retained as an attribute in the modified entry.
Returns
Returns the message ID of the ldap_modrdn2() operation. To check the result of this operation, call ldap_result() and ldap_result2error(). For a list of possible result codes, see ldap_rename().
Description
Please use the newer version of this function, ldap_rename().
Example
Code Example 17-36 uses the asynchronous ldap_modrdn2() function to change the RDN of an entry from uid=bjensen to uid=babs. The code removes the existing RDN bjensen from the uid attribute of the entry.
Code Example 17-36 ldap_modrdn2() Code Example
#include <ldap-deprecated.h>
...
LDAP *ld;
LDAPMessage *result;
int msgid, rc;
struct timeval tv;
/* Distinguished name of the entry that you want to rename. */
char *dn = "uid=bjensen,ou=People,dc=example,dc=com";
/* New relative distinguished name (RDN) of the entry */
char *rdn = "uid=babs";
...
/* Set up the timeout period to wait for the "modify RDN" operation */
tv.tv_sec = tv.tv_usec = 0;
/* Rename the entry */
if ( ( msgid = ldap_modrdn2( ld, dn, rdn, 1 ) ) == -1 ) {
ldap_perror( ld, "ldap_modrdn2" );
return( 1 );
}
/* Check to see if the operation has completed */
while ( ( rc = ldap_result( ld, msgid, 0, &tv, &result ) ) == 0 ) {
...
/* do other work while waiting for the operation to complete */
...
}
/* Check the result to see if any errors occurred */
ldap_result2error( ld, result, 1 );
ldap_perror( ld, "ldap_modrdn2" );
...
See Also
ldap_modrdn2_s()
Caution
This function is deprecated and should not be used. It is included in ldap-deprecated.h for backward-compatibility. Please use ldap_rename_s() instead.
The ldap_modrdn2_s() function changes the relative distinguished name (RDN) of an entry in the directory synchronously.
Syntax
#include <ldap-deprecated.h>
int ldap_modrdn2_s( LDAP *ld, const char *dn,
const char *newrdn, int deleteoldrdn );Parameters
This function has the parameters listed in Table 17-131.
Table 17-131 ldap_modrdn2_s() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
dn
DN of the entry to modify.
newrdn
New RDN to assign to the entry.
deleteoldrdn
If this is a non-zero value, the old RDN is not retained as a value in the modified entry. If 0, the old RDN is retained as an attribute in the modified entry.
Returns
For a list of possible result codes, see ldap_rename_s().
Description
Please use the newer version of this function, ldap_rename_s().
Example
Code Example 17-37 uses the synchronous ldap_modrdn2_s() function to change the RDN of an entry from uid=bjensen to uid=babs. The code removes the existing RDN babs from the uid attribute of the entry.
Code Example 17-37 ldap_modrdn2_s() Code Example
#include <ldap.h>
...
LDAP *ld;
/* Distinguished name of the entry that you want to rename. */
char *dn = "uid=bjensen,ou=People,dc=example,dc=com";
/* New relative distinguished name (RDN) of the entry */
char *rdn = "uid=babs";
...
/* Rename the entry */
if ( ldap_modrdn2_s( ld, dn, rdn, 1 ) != LDAP_SUCCESS ) {
ldap_perror( ld, "ldap_modrdn2_s" );
return( 1 );
}
...
See Also
ldap_mods_free()The ldap_mods_free() function frees the LDAPMod structures that you’ve allocated to add or modify entries.
Note
You need to call this function only if you’ve allocated memory for these structures yourself. For more information, see the ldap-extension.h header file.
Syntax
#include <ldap.h>
void ldap_mods_free( LDAPMod **mods, int freemods );Parameters
This function has the parameters listed in Table 17-132
Table 17-132 ldap_mods_free() Function Parameters
Parameter
Description
mods
Pointer to a NULL-terminated array of pointers to LDAPMod structures.
freemods
If this is a non-zero value, frees the array of pointers as well as the LDAPMod structures. If 0, just frees the LDAPMod structures.
Example
Code Example 17-38 allocates memory for LDAPMod structures and frees them when done.
Code Example 17-38 ldap_mods_free() Code Example
#include <stdio.h>
#include <ldap.h>
...
LDAP *ld;
char *dn;
int i, msgid;
LDAPMod **mods;
...
/* Construct the array of values to add */
mods = ( LDAPMod ** ) malloc(( NMODS + 1 ) * sizeof( LDAPMod * ));
if ( mods == NULL ) {
fprintf( stderr, "Cannot allocate memory for mods array\n" );
}
for ( i = 0; i < NMODS; i++ ) {
if (( mods[ i ] = ( LDAPMod * ) malloc( sizeof( LDAPMod ))) == NULL) {
fprintf( stderr, "Cannot allocate memory for mods element\n" );
exit( 1 );
}
}
...
/* Code for filling the structures goes here. */
...
/* Initiate the add operation */
if (( msgid = ldap_add( ld, dn, mods )) < 0 ) {
ldap_perror( ld, "ldap_add" );
ldap_mods_free( mods, 1 );
return( 1 );
}
...
ldap_msgfree()The ldap_msgfree() function frees the memory allocated for a result by ldap_result() or ldap_search_s().
Syntax
#include <ldap.h>
int ldap_msgfree( LDAPMessage *lm );Parameters
This function has the parameter listed in Table 17-133.
Table 17-133 ldap_msgfree() Function Parameter
Parameter
Description
lm
Pointer to the result to be freed from memory.
Returns
One of the following values:
- LDAP_RES_BIND indicates that the LDAPMessage structure contains the result of an LDAP bind operation.
- LDAP_RES_SEARCH_ENTRY indicates that the LDAPMessage structure contains an entry found during an LDAP search operation.
- LDAP_RES_SEARCH_REFERENCE indicates that the LDAPMessage structure contains an LDAPv3 search reference (a referral to another LDAP server) found during an LDAP search operation.
- LDAP_RES_SEARCH_RESULT indicates that the LDAPMessage structure contains the result of an LDAP search operation.
- LDAP_RES_MODIFY ndicates that the LDAPMessage structure contains the result of an LDAP modify operation.
- LDAP_RES_ADD indicates that the LDAPMessage structure contains the result of an LDAP add operation.
- LDAP_RES_DELETE indicates that the LDAPMessage structure contains the result of an LDAP delete operation.
- LDAP_RES_MODRDN or LDAP_RES_RENAME indicates that the LDAPMessage structure contains the result of an LDAP modify DN operation.
- LDAP_RES_COMPARE indicates that the LDAPMessage structure contains the result of an LDAP compare operation.
- LDAP_RES_EXTENDED indicates that the LDAPMessage structure contains the result of an LDAPv3 extended operation.
- 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.
See Chapter 18, "Result Codes" for a complete listing.
Description
For more information, see "Freeing the Search Results" of Chapter 5, "Searching a LDAP Directory."
Example
Code Example 17-39 frees the results of a search.
Code Example 17-39 ldap_msgfree() Code Example
#include <stdio.h>
#include <ldap.h>
...
LDAP *ld;
LDAPMessage *result;
char *my_searchbase = "dc=example,dc=com";
char *my_filter = "(sn=Jensen)";
char *get_attr[] = { "cn", "mail", NULL };
...
/* Search the directory */
if ( ldap_search_s( ld, my_searchbase, LDAP_SCOPE_SUBTREE, my_filter, get_attr, 0, &result ) != LDAP_SUCCESS ) {
ldap_perror( ld, "ldap_search_s" );
return( 1 );
}
...
/* Free the results when done */
ldap_msgfree( result );
...
See Also
ldap_result(), ldap_search_s()
ldap_msgid()The ldap_msgid() function determines the message ID of a result obtained by calling ldap_result() or ldap_search_s().
Syntax
#include <ldap.h>
int ldap_msgid( LDAPMessage *lm );Parameters
This function has the parameter listed in Table 17-134.
Table 17-134 ldap_msgid() Function Parameter
Parameter
Description
lm
Pointer to the result to check.
Returns
One of the following values:
Example
Code Example 17-40 prints the message ID from the result obtained from a synchronous LDAP search operation.
Code Example 17-40 ldap_msgid() Code Example
#include <stdio.h>
#include <ldap.h>
...
LDAP *ld;
LDAPMessage *result;
...
/* Perform a search */
if ( ldap_search_s( ld, MY_SEARCHBASE, LDAP_SCOPE_SUBTREE, MY_FILTER,
NULL, 0, &result ) != LDAP_SUCCESS ) {
ldap_perror( ld, "ldap_search_s" );
return( 1 );
}
/* Get and print the message ID */
if ( ldap_msgid( result ) != -1 ) {
printf( "Message ID: %d\n" );
} else {
printf( "An error occurred.\n" );
}
...
See Also
ldap_msgtype(), ldap_result(), ldap_search_s()
ldap_msgtype()The ldap_msgtype() function determines the type of result obtained by calling ldap_result() or ldap_search_s().
Syntax
#include <ldap.h>
int ldap_msgtype( LDAPMessage *lm );Parameters
This function has the parameter listed in Table 17-135.
Table 17-135 ldap_msgtype() Function Parameter
Parameter
Description
lm
Pointer to the LDAPMessage structure to check.
Returns
One of the following values:
- LDAP_RES_BIND indicates that the LDAPMessage structure contains the result of an LDAP bind operation.
- LDAP_RES_SEARCH_ENTRY indicates that the LDAPMessage structure contains an entry found during an LDAP search operation.
- LDAP_RES_SEARCH_REFERENCE indicates that the LDAPMessage structure contains an LDAPv3 search reference (a referral to another LDAP server) found during an LDAP search operation.
- LDAP_RES_SEARCH_RESULT indicates that the LDAPMessage structure contains the result of an LDAP search operation.
- LDAP_RES_MODIFY ndicates that the LDAPMessage structure contains the result of an LDAP modify operation.
- LDAP_RES_ADD indicates that the LDAPMessage structure contains the result of an LDAP add operation.
- LDAP_RES_DELETE indicates that the LDAPMessage structure contains the result of an LDAP delete operation.
- LDAP_RES_MODRDN or LDAP_RES_RENAME indicates that the LDAPMessage structure contains the result of an LDAP modify DN operation.
- LDAP_RES_COMPARE indicates that the LDAPMessage structure contains the result of an LDAP compare operation.
- LDAP_RES_EXTENDED indicates that the LDAPMessage structure contains the result of an LDAPv3 extended operation.
- -1 indicates that the lm argument is not a pointer to a valid LDAPMessage structure.
Example
Code Example 17-41 prints the message type for a result obtained from a synchronous LDAP search operation.
Code Example 17-41 ldap_msgtype() Code Example
#include <stdio.h>
#include <ldap.h>
...
LDAP *ld;
LDAPMessage *result;
int msgtype;
...
/* Perform a search */
if ( ldap_search_s( ld, MY_SEARCHBASE, LDAP_SCOPE_SUBTREE, MY_FILTER,
NULL, 0, &result ) != LDAP_SUCCESS ) {
ldap_perror( ld, "ldap_search_s" );
return( 1 );
}
/* Get and print the message type */
msgtype = ldap_msgtype( result );
if ( msgtype != -1 ) {
printf( "Message type: %d\n", msgtype );
} else {
printf( "An error occurred.\n" );
}
...
See Also
ldap_msgid(), ldap_result(), ldap_search_s()
ldap_multisort_entries()The ldap_multisort_entries() function sorts a chain of entries retrieved from an LDAP search call (ldap_search_s() or ldap_result()) by either a specified set of attributes in the entries or DN.
Syntax
#include <ldap.h>
int ldap_multisort_entries( LDAP *ld, LDAPMessage **chain,
char **attr, LDAP_CMP_CALLBACK *cmp );Parameters
This function has the parameters listed in Table 17-136.
Table 17-136 ldap_multisort_entries() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
chain
Chain of entries returned by the ldap_result() or ldap_search_s() function.
attr
Array of attributes to use for sorting the results. If NULL, results are sorted by DN.
cmp
Comparison function used when sorting the values. For details, see "Sorting Entries by an Attribute" of Chapter 5, "Searching a LDAP Directory."
Returns
One of the following values:
- 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
Code Example 17-42 sorts entries first by the roomNumber attribute, then by the telephoneNumber attribute.
Code Example 17-42 ldap_multisort_entries() Code Example
#include <stdio.h>
#include <string.h>
#include <ldap.h>
...
LDAP *ld;
LDAPMessage *result;
char *my_searchbase = "dc=example,dc=com";
char *my_filter = "(sn=Jensen)";
char *attrs[3];
attrs[0] = "roomNumber";
attrs[1] = "telephoneNumber";
attrs[2] = NULL;
...
/* Search the directory */
if ( ldap_search_s( ld, my_searchbase, LDAP_SCOPE_SUBTREE, my_filter, NULL, 0, &result ) != LDAP_SUCCESS ) {
ldap_perror( ld, "ldap_search_s" );
return( 1 );
}
/* Sort the results, using strcasecmp */
if ( ldap_multisort_entries( ld, &result, attrs, strcasecmp ) != LDAP_SUCCESS ) {
ldap_perror( ld, "ldap_multisort_entries" );
return( 1 );
}
...
See Also
ldap_result(), ldap_search_s(), ldap_sort_entries(), LDAP_CMP_CALLBACK
ldap_name2template()The ldap_name2template() function obtains a pointer to the correct ldap_disptmpl structure.
Syntax
#include <disptmpl.h>
struct ldap_disptmpl * ldap_name2template( char *name
struct ldap_disptmpl *tmpllist );Parameters
This function has the parameters listed in Table 17-137.
Table 17-137 ldap_name2template() Function Parameters
Parameter
Description
name
Name of the template.
tmpllistp
Pointer to a list of template data structures.
Returns
Description
ldap_name2template() obtains a pointer to the correct ldap_disptmpl structure. Links to templates can be defined by name.
ldap_next_attribute()The ldap_next_attribute() function returns the name of the next attribute in an entry returned by ldap_first_entry() or ldap_next_entry().
Syntax
#include <ldap.h>
char * ldap_next_attribute( LDAP *ld, LDAPMessage *entry,
BerElement *ber);Parameters
This function has the parameters listed in Table 17-138.
Table 17-138 ldap_next_attribute() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
entry
Pointer to the LDAPMessage structure representing the entry returned by the ldap_first_entry() or ldap_next_entry() function.
ber
A pointer to a BerElement allocated to keep track of its current position. Pass this pointer to subsequent calls to ldap_next_attribute() to step through the entry's attributes.
Returns
One of the following values:
- If successful, returns the name of the next attribute in an entry. When you are done using this data, you should free the memory by calling the ldap_memfree() function.
- If no more attributes exist in the entry, returns a NULL.
- If unsuccessful, returns a NULL and sets the appropriate error code in the LDAP structure. To get the error code, call the ldap_get_lderrno() function.
See Chapter 18, "Result Codes" for a complete listing of error codes.
Description
The ldap_first_attribute() function returns a pointer to a BerElement. You use this pointer with ldap_next_attribute() to iterate through the list of elements. After the last call to ldap_next_element(), you should free the BerElement pointer using ldap_ber_free(). When calling ldap_ber_free(), make sure to specify that the buffer is not freed (pass 0 for the freebuf parameter).
For more information, see "Getting Attribute Names from an Entry" of Chapter 5, "Searching a LDAP Directory."
Example
See the example under ldap_first_attribute().
See Also
ldap_first_attribute(), ldap_getfirstfilter(), ldap_next_entry()
ldap_next_disptmpl()The ldap_next_disptmpl() function returns the next template in a list.
Syntax
#include <disptmpl.h>
struct ldap_disptmpl * ldap_next_disptmpl( struct ldap_disptmpl *tmpllist,
struct ldap_disptmpl *tmpl );;Parameters
This function has the parameters listed in Table 17-139.
Table 17-139 ldap_next_disptmpl() Function Parameters
Parameter
Description
tmpl
Defines a template from the template list tmpllist. A NULL pointer is returned if tmpl is the last template in the list.
tmpllistp
Pointer to a list of template data structures typically obtained by calling ldap_init_templates().
Returns
Description
ldap_next_disptmpl() returns the template following the previous one in the list of templates pointed to by the parameter tmpllistp. tmpllistp is typically obtained by calling ldap_init_templates().
See Also
ldap_next_entry()The ldap_next_entry() function returns a pointer to the LDAPMessage structure representing the next directory entry in a chain of search results.
Syntax
#include <ldap.h>
LDAPMessage * ldap_next_entry( LDAP *ld, LDAPMessage *entry );Parameters
This function has the parameters listed in Table 17-140.
Table 17-140 ldap_next_entry() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
entry
Pointer to an LDAPMessage structure in a chain of search results.
Returns
One of the following values:
- 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.
For more information, see "Sorting the Search Results" in Chapter 5, "Searching a LDAP Directory."
See Also
ldap_next_message()The ldap_next_message() function returns a pointer to the next LDAPMessage structure in a chain of search results.
Syntax
#include <ldap.h>
LDAPMessage * ldap_next_message( LDAP *ld, LDAPMessage *msg );Parameters
This function has the parameters listed in Table 17-141.
Table 17-141 ldap_next_message() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
msg
Pointer to an LDAPMessage structure in a chain of search results.
Returns
One of the following values:
- 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).
For more information, see "Sorting the Search Results" in Chapter 5, "Searching a LDAP Directory."
Example
See Code Example 5-4 and Code Example 5-7 of Chapter 5, "Searching a LDAP Directory."
See Also
ldap_first_message(), ldap_msgtype()
ldap_next_reference()The ldap_next_reference() function returns a pointer to the LDAPMessage structure representing the next search reference in a chain of search results.
Syntax
#include <ldap.h>
LDAPMessage * ldap_next_reference( LDAP *ld, LDAPMessage *ref );Parameters
This function has the parameters listed in Table 17-142.
Table 17-142 ldap_next_reference() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
msg
Pointer to an LDAPMessage structure in a chain of search results.
Returns
One of the following values:
- 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 as messages containing search references have the type LDAP_RES_SEARCH_REFERENCE.
For more information, see "Sorting the Search Results" in Chapter 5, "Searching a LDAP Directory."
See Also
ldap_next_searchobj()The ldap_next_searchobj() function returns the following search preference in a defined list.
Syntax
#include <ldap.h>
struct ldap_searchobj * ldap_next_searchobj
( struct ldap_searchobj *sollist, struct ldap_searchobj *so );Parameters
This function has the parameters listed in Table 17-143.
Table 17-143 ldap_next_searchobj() Function Parameters
Parameter
Description
sollist
Pointer to a list of data structures, typically obtained by calling ldap_init_searchprefs().
so
Pointer to the most recent search object returned in the template list sollist. The search object returned by ldap_next_searchobj() follows this one.
Returns
Description
The search object returned by ldap_next_searchobj() follows the one defined by the so parameter.
See Also
ldap_init_searchprefs(), ldap_first_searchobj()
ldap_next_tmplcol()The ldap_next_tmplcol() function returns a pointer to the following item (in the column) within a template.
Syntax
#include <disptmpl.h>
struct ldap_tmplitem * ldap_next_tmplcol( struct ldap_disptmpl *tmpl,
struct ldap_tmplitem *row, struct ldap_tmplitem *col );Parameters
This function has the parameters listed in Table 17-144.
Table 17-144 ldap_next_tmplcol() Function Parameters
Parameter
Description
tmpl
The name of the template to be retrieved.
row
The row in which the item is to be retrieved from.
col
The column in which the item is to be retrieved from.
Returns
Description
ldap_next_tmplcol() returns a pointer to the next item (in the column) of the row, defined by row, within the template defined by tmpl.
See Also
ldap_next_tmplrow()The ldap_next_tmplrow() function returns a pointer to the following row in a template.
Syntax
#include <disptmpl.h>
struct ldap_tmplitem * ldap_next_tmplrow( struct ldap_disptmpl *tmpl,
struct ldap_tmplitem *row );Parameters
This function has the parameters listed in Table 17-145.
Table 17-145 ldap_next_tmplrow() Function Parameters
Parameter
Description
tmpl
The name of the template to be retrieved.
row
The row in the template to be retrieved.
Returns
Description
ldap_next_tmplrow() returns a pointer to the row that follows the one defined by row in the template defined by tmpl.
ldap_oc2template()The ldap_oc2template() function obtains a pointer to the correct ldap_disptmpl structure.
Syntax
#include <disptmpl.h>
struct ldap_disptmpl * ldap_oc2template( char **oclist,
struct ldap_disptmpl *tmpllist );Parameters
This function has the parameters listed in Table 17-146.
Table 17-146 ldap_oc2template() Function Parameters
Parameter
Description
oclist
A NULL-terminated array of strings that contains the values of the objectClass attribute of the entry.
tmpllistp
Pointer to a list of template data structures.
Returns
Description
ldap_oc2template()searches tmpllist for the best template to use to display an entry that has a specific set of objectClass values.
ldap_open()
Caution
This function is deprecated and should not be used. Please use ldap_init().
The ldap_open() function opens a connection to an LDAP server and allocates an LDAP structure which is used to identify the connection and maintain per-connection information.
Syntax
#include <ldap-deprecated.h>
ldap_open( const char *host, int port );Parameters
This function has the parameters listed in Table 17-148.
Table 17-147 ldap_open() Function Parameters
Parameter
Description
host
The hostname on which the LDAP server is running. It may contain a blank-separated list of hosts to try to connect to, and each host may optionally be of the form host:port. If present, port overrides the port parameter. Upon successfully making a connection to an LDAP server, ldap_open() returns a pointer to an LDAP structure, which should be passed to subsequent calls (ldap_bind(), ldap_search(), and so forth).
port
The port number to which to connect. If the default IANA-assigned port of 389 is desired, LDAP_PORT should be specified as the value of port.
Description
Please use the newer version of this function, ldap_init().
ldap_parse_entrychange_control()The ldap_parse_entrychange_control() function examines a list of controls returned from a persistent search operation, retrieves an entry change control, and parses that control for information (such as the type of change made to the entry and the change number).
Note
This function implements an extension to the LDAPv3. Entry change notification is an optional feature; it may not be supported on all LDAP servers. Call this function when interacting with LDAP servers that support this LDAPv3 extension. See "Determining Supported Extended Operations" of Chapter 15, "Extended Operations" to determine if the server supports extended operations.
Syntax
#include <ldap.h>
int ldap_parse_entrychange_control( LDAP *ld,
LDAPControl **ctrls, int *chgtypep, char **prevdnp,
int *chgnumpresentp, long *chgnump );Parameters
This function has the parameters listed in Table 17-148.
Table 17-148 ldap_parse_entrychange_control() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
ctrlp
An array of controls returned by the server. You obtain these controls by calling the ldap_get_entry_controls() function on an entry returned by the server.
changetypes
Pointer to an integer specifying the type of change made to the entry. This field can have one of the following values:
- LDAP_CHANGETYPE_ADD specifies that the entry was added to the directory.
- LDAP_CHANGETYPE_DELETE specifies that the entry was deleted from the directory.
- LDAP_CHANGETYPE_MODIFY specifies that the entry was modified.
- LDAP_CHANGETYPE_MODDN specifies that the DN or RDN of the entry was changed (a modify RDN or modify DN operation was performed).
prevdnp
Pointer to the previous DN of the entry, if the changetypes argument is LDAP_CHANGETYPE_MODDN. (If the changetypes argument has a different value, this argument is set to NULL.) When done, you can free this by calling the ldap_memfree() function.
chgnumpresentp
Pointer to an integer specifying whether or not to the change number is included in the control. The parameter can have the following possible values:
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.
Note
This function implements an extension to the LDAPv3. Extended operations might not be supported on all LDAP servers. Call this function only when interacting with LDAP servers that support this LDAPv3 extension. See "Determining Supported Extended Operations" of Chapter 15, "Extended Operations" to determine if the server supports extended operations.
Syntax
#include <ldap.h>
int ldap_parse_extended_result( LDAP *ld, LDAPMessage *res,
char **retoidp, struct berval **retdatap, int freeit );Parameters
This function has the parameters listed in Table 17-149.
Table 17-149 ldap_parse_extended_result() Function Parameters
Parameters
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
res
Pointer to the LDAPMessage structure containing the results of an LDAP operation.
retoidp
Pointer to the OID returned by the server after performing the extended operation. When done, you can free this by calling the ldap_memfree() function.
retdatap
Pointer to the pointer to a berval structure containing the data returned by the server after performing the extended operation. When done, you can free this by calling the ber_bvfree() function.
freeit
Specifies whether or not to free the results of the operation (the LDAPMessage structure specified by the res argument). The parameter can have the following possible values:
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 LDAPv3. Make sure that you set the version of your LDAP client to version 3 before calling this function. (For details, see "Specifying the LDAP Version of Your Client" of Chapter 3, "Writing an LDAP Client.")
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().
Note
The LDAP server must support the extended operation. Sun Java System Directory Server supports a server plug-in interface that you can use to add support for extended operations. For details, see the Sun ONE Directory Server Plug-In Programming Guide.
See Also
ldap_extended_operation_s(), ldap_get_lderrno()
ldap_parse_reference()The ldap_parse_reference() function parses search references from the results received from an LDAP server.
Note
Search references are part of the LDAPv3. When calling this function, make sure that you are working with a server that supports the LDAPv3.
Syntax
#include <ldap.h>
int ldap_parse_reference( LDAP *ld, LDAPMessage *ref,
char ***referralsp, LDAPControl ***serverctrlsp,
int freeit );Parameters
This function has the parameters listed in Table 17-150.
Table 17-150 ldap_parse_reference() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
ref
Pointer to an LDAPMessage structure of the type LDAP_RES_SEARCH_REFERENCE.
referralsp
Pointer to an array of strings representing the referrals found by an LDAP search operation and returned by the server (applicable only if the LDAP operation was a search operation). When done, you can free this by calling the ldap_value_free() function.
serverctrlsp
Pointer to an array of LDAPControl structures, which represent the LDAPv3 server controls returned by the server. When done, you can free this by calling the ldap_controls_free() function.
freeit
Specifies whether or not to free the results of the operation (the LDAPMessage structure specified by the res argument). The parameter can have the following possible values:
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.
ldap_parse_result()The ldap_parse_result() function parses the results of an LDAP operation received from an LDAP server.
Syntax
#include <ldap.h>
int ldap_parse_result( LDAP *ld, LDAPMessage *res,
int *errcodep, char **matcheddnp, char **errmsgp,
char ***referralsp, LDAPControl ***serverctrlsp, int freeit);Parameters
This function has the parameters listed in Table 17-151.
Table 17-151 ldap_parse_result() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
res
Pointer to the LDAPMessage structure containing the results of an LDAP operation.
errcodep
Pointer to the LDAP result code specifying the result of the operation.
matcheddnp
Pointer to a string specifying the portion of a DN that finds an existing entry (in cases where the server cannot find the entry specified by a DN). See"Receiving the Matching Portion of a DN" of Chapter 4, "Using the LDAP API" for details. When done, you can free this by calling the ldap_memfree() function.
errmsgp
Pointer to an additional error message string sent from the server. When done, you can free this by calling the ldap_memfree() function.
referralsp
Pointer to an array of strings representing the referrals returned by the server. When done, you can free this by calling the ldap_value_free() function.
serverctrlsp
Pointer to an array of LDAPControl structures, which represent the LDAPv3 server controls returned by the server. When done, you can free this by calling the ldap_controls_free() function.
freeit
Specifies whether or not to automatically free the results of the operation (the LDAPMessage structure specified by the res argument). The parameter can have the following possible values:
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). (See "Receiving the Matching Portion of a DN" in Chapter 4, "Using the LDAP API" for details.)
- A set of referrals, if the server does not contain the entries that you’ve specified and if the server is configured to refer clients to other servers (referralsp).
- A set of server response controls that are relevant to the operation (serverctrlsp).
Calling this function creates an array of LDAPControl structures that you can pass to subsequent API functions (such as the ldap_parse_sort_control() function.
For more information, see "Performing an Asynchronous Authentication Operation" in Chapter 3, "Writing an LDAP Client."
Note
This function is not intended to be used to parse entries and search references. Use the ldap_msgtype() function to determine the type of result contained in the LDAPMessage structure. If the result is an entry returned as a search result, call the ldap_first_entry() function to retrieve the entry. If the result is a search reference, call the ldap_parse_reference() function to retrieve the reference.
Example
See the examples as follow:
- For an example of parsing the results of an asynchronous LDAP add operation, see Code Example 7-9.
- For an example of parsing the results of an asynchronous LDAP modify operation, see Code Example 7-17.
- For an example of parsing the results of an asynchronous LDAP delete operation, see Code Example 7-21.
- For an example of parsing the results of an asynchronous LDAP modify DN operation, see Code Example 7-24.
See the example in Chapter 3, "Writing an LDAP Client" as follows:
- For an example of parsing the results of an asynchronous LDAP bind operation, see Code Example 3-9.
See the example in Chapter 4, "Using the LDAP API" as follows:
- For an example of parsing the results of an asynchronous LDAP bind operation, see Code Example 4-5.
See the example in Chapter 5, "Searching a LDAP Directory" as follows:
- For an example of parsing the results of an asynchronous LDAP search operation, see Code Example 5-7.
See Also
ldap_parse_sasl_bind_result()The ldap_parse_sasl_bind_result() function parses the results of an LDAP SASL bind operation and retrieves data returned by the server.
Note
SASL authentication is part of the LDAPv3. When calling this function, make sure that you are working with a server that supports the LDAPv3.
Syntax
#include <ldap.h>
int ldap_parse_sasl_bind_result( LDAP *ld, LDAPMessage *res,
struct berval **servercredp, int freeit );Parameters
This function has the parameters listed in Table 17-152.
Table 17-152 ldap_parse_sals_bind_result() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
res
Pointer to the LDAPMessage structure containing the results of an LDAP operation.
servercredp
Pointer to a pointer to an berval structure containing any challenge or credentials returned by the server. When done, you can free this by calling the ber_bvfree() function.
freeit
Specifies whether or not to free the results of the operation (the LDAPMessage structure specified by the res argument). The parameter can have the following possible values:
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 LDAPv3. Make sure that you set the version of your LDAP client to version 3 before calling this function. (For details, see "Specifying the LDAP Version of Your Client" of Chapter 3, "Writing an LDAP Client.")
Description
After you call the ldap_sasl_bind() function and the ldap_result() function, you can pass the results to ldap_parse_sasl_bind_result() for parsing. This function gets the following data from the server’s response:
- 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().
See Also
ldap_sasl_bind(), ldap_get_lderrno()
ldap_parse_sort_control()The parse_sort_control() function parses the result returned from a search operation that used a server control for sorting search results.
Note
This function implements an extension to the LDAPv3. Server-pside sorting is an optional feature; it may not be supported on all LDAP servers. Call this function when interacting with LDAP servers that support this LDAPv3 extension. See "Determining Supported Extended Operations" of Chapter 15, "Extended Operations" to determine if the server supports extended operations.
Syntax
#include <ldap.h>
int ldap_parse_sort_control( LDAP *ld, LDAPControl **ctrls,
unsigned long *result, char **attribute );Parameters
This function has the parameters listed in Table 17-153.
Table 17-153 ldap_parse_sort_control() Function Parameters
Parameters
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
ctrls
An array of controls returned by the server. You obtain these controls by calling the ldap_parse_result() function on the set of results returned by the server.
result
Pointer to the sort control result code retrieved by this function.
attribute
If the sorting operation fails, the function sets this to point to the name of the attribute that caused the failure. When done, you can free this by calling the ldap_memfree() function.
Returns
One of the following values, which indicates the result of parsing the server’s response:
- 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_parse_virtuallist_control()The ldap_parse_virtuallist_control() function parses the result returned from a search operation that used a server control for virtual list views.
Note
This function implements an extension to the LDAPv3. A virtual list view is an optional LDAP server feature that may not be supported on all LDAP servers. For more information about this control, see "Using the Virtual List View Control" of Chapter 13, "Working with LDAP Controls." For information on determining if a server supports this or other LDAPv3 controls, see "Determining LDAPv3 Support" of Chapter 10, "Retrieving Server Information."
Syntax
#include <ldap.h>
int ldap_parse_virtuallist_control( LDAP *ld,
LDAPControl **ctrls, unsigned long *target_posp,
unsigned long *list_sizep, int *errcodep );Parameters
This function has the parameters listed in Table 17-154.
Table 17-154 ldap_parse_virtuallist_control() Function Parameters
Parameters
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
ctrls
An array of controls returned by the server. You obtain these controls by calling the ldap_parse_result() function on the set of results returned by the server.
target_posp
Pointer to an unsigned long that is set by the function. The function sets this to the index or offset of the selected entry in the list of entries.
list_sizep
Pointer to an unsigned long that is set by the function. The function sets this to the number of entries in the total number of entries in the entire list (not just the subset).
errcodep
Pointer to the sort control result code retrieved by this function.
Returns
One of the following values:
- 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 LDAPv3. Make sure that you set the version of your LDAP client to version 3 before calling this function. (For details, see "Specifying the LDAP Version of Your Client" of Chapter 3, "Writing an LDAP Client.")
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_perror()
Caution
This function is deprecated and should not be used. It is included in ldap-deprecated.h for backward-compatibility. Please use ldap_get_lderrno() instead.
The ldap_perror() function prints, to standard output, the last LDAP error message.
Syntax
#include <ldap-deprecated.h>
void ldap_perror( LDAP *ld, const char *s );Parameters
This function has the parameters listed in Table 17-155.
Table 17-155 ldap_perror() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
s
Optional text to print out before printing the error message.
Description
Please use the newer version of this function, ldap_get_lderrno().
For more information, see "Printing Out Error Messages" of Chapter 4, "Using the LDAP API."
Example
Code Example 17-43 prints out an error message if the search operation cannot complete successfully.
Code Example 17-43 ldap_perror() Code Example
...
if ( ldap_search_s( ld, my_searchbase, LDAP_SCOPE_SUBTREE, my_filter,
get_attr, 0, &result ) != LDAP_SUCCESS ) {
ldap_perror( ld, "ldap_search_s" );
return( 1 );
...
See Also
ldap_get_lderrno(), ldap_err2string(), ldap_result2error(), ldap_set_lderrno()
ldap_rename()The ldap_rename() function changes the DN of an entry in the directory asynchronously.
Note
ldap_rename() is a new version of the ldap_modrdn2() function. If you are writing a new LDAP client, you should call ldap_rename().
Syntax
#include <ldap.h>
int ldap_rename( LDAP *ld, const char *dn, const char *newrdn,
const char *newparent, int deleteoldrdn,
LDAPControl **serverctrls, LDAPControl **clientctrls,
int *msgidp );Parameters
This function has the parameters listed in Table 17-156.
Table 17-156 ldap_rename() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
dn
DN of the entry to rename.
newrdn
New Relative Distinguished Name (RDN) to assign to the entry.
newparent
DN of the new parent entry you want to move the entry under. Pass NULL if you do not want to move the entry to a different location in the directory tree.
deleteoldrdn
Specifies whether or not the old RDN is retained as an attribute of the entry. For example, an entry has the following values for the cn attribute:
cn: Barbara Jensen
cn: Babs Jensen
If you change the RDN to cn=Barbie Jensen” and pass 1 as deleteoldrdn, the resulting entry has the following values:
cn: Barbie Jensen
cn: Babs Jensen
If instead you pass 0 as deleteoldrdn, the Barbara Jensen value is not removed from the entry:
cn: Barbie Jensen
cn: Babs Jensen
cn: Barbara Jensen
So, if this is a non-zero value, the old RDN is not retained as a value in the entry. If 0, the old RDN is retained as an attribute in the entry.
serverctrls
Pointer to an array of LDAPControl structures representing LDAP server controls that apply to this LDAP operation. If you do not want to pass any server controls, specify NULL for this argument.
clientctrls
Pointer to an array of LDAPControl structures representing LDAP client controls that apply to this LDAP operation. If you do not want to pass any client controls, specify NULL for this argument.
msgidp
Pointer to an integer that will be set to the message ID of the LDAP operation. To check the result of this operation, call the ldap_result() and ldap_parse_result() functions.
Returns
One of the following values:
- 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 LDAPv3. Make sure that you set the version of your LDAP client to version 3 before calling this function. (For details, see "Specifying the LDAP Version of Your Client" of Chapter 3, "Writing an LDAP Client.")
Description
The ldap_rename() changes the DN of an entry in the directory and allows you to move the entry under a different parent entry in the directory tree. ldap_rename() is an asynchronous function; it does not directly return results. In order to get the results of the LDAP rename operation, you need to call the ldap_result() function and the ldap_parse_result() function. If you want the results to be returned directly by the function, call the synchronous function ldap_rename_s() instead.
For more information on changing the DN of an entry, see "Changing the DN of an Entry" of Chapter 17, "Function Reference." For a list of possible result codes for an LDAP rename operation, see the RETURNS section of the ldap_rename_s() function.
Example
See Code Example 7-24 in Chapter 7, "Adding, Modifying and Deleting Entries."
See Also
ldap_rename_s(), ldap_result(), ldap_parse_result()
ldap_rename_s()The ldap_rename_s() function changes the DN of an entry in the directory synchronously.
Note
ldap_rename_s() is a new version of the ldap_modrdn2_s() function. If you are writing a new LDAP client, you should call ldap_rename_s().
Syntax
#include <ldap.h>
int ldap_rename_s( LDAP *ld, const char *dn, const char *newrdn,
const char *newparent, int deleteoldrdn,
LDAPControl **serverctrls, LDAPControl **clientctrls );Parameters
This function has the parameters listed in Table 17-157.
Table 17-157 ldap_rename() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
dn
DN of the entry to rename.
newrdn
New Relative Distinguished Name (RDN) to assign to the entry.
newparent
DN of the new parent entry you want to move the entry under. Pass NULL if you do not want to move the entry to a different location in the directory tree.
deleteoldrdn
Specifies whether or not the old RDN is retained as an attribute of the entry. For example, an entry has the following values for the cn attribute:
cn: Barbara Jensen
cn: Babs Jensen
If you change the RDN to cn=Barbie Jensen and pass 1 as deleteoldrdn, the resulting entry has the following values:
cn: Barbie Jensen
cn: Babs Jensen
If instead you pass 0 as deleteoldrdn, the Barbara Jensen value is not removed from the entry:
cn: Barbie Jensen
cn: Babs Jensen
cn: Barbara Jensen
So, if this is a non-zero value, the old RDN is not retained as a value in the entry. If 0, the old RDN is retained as an attribute in the entry.
serverctrls
Pointer to an array of LDAPControl structures representing LDAP server controls that apply to this operation. If you do not want to pass any server controls, specify NULL for this argument.
clientctrls
Pointer to an array of LDAPControl structures representing LDAP client controls that apply to this operation. If you do not want to pass any client controls, specify NULL for this argument.
Returns
One of the following values:
- 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. (For details, see "Specifying the LDAP Version of Your Client" of Chapter 3, "Writing an LDAP Client.")
Description
The ldap_rename_s() changes the DN of an entry in the directory and allows you to move the entry under a different parent entry in the directory tree. The function ldap_rename_s() is synchronous; it directly returns the results of the operation. If you want to perform other operations while waiting for the results of this operation, call the asynchronous function ldap_rename().
For more information on changing the DN of an entry, see "Changing the DN of an Entry" of Chapter 17, "Function Reference."
Example
See Code Example 7-25 in Chapter 7, "Adding, Modifying and Deleting Entries."
See Also
ldap_result()The function ldap_result() waits for and returns the result of an LDAP operation initiated by one of the asynchronous LDAP API functions.
Syntax
#include <ldap.h>
int ldap_result( LDAP *ld, int msgid, int all,
struct timeval *timeout, LDAPMessage **result );Parameters
This function has the parameters listed in Table 17-158.
Table 17-158 ldap_result() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
msgid
Asynchronous functions return a unique message ID. This parameter takes message ID of the operation for which you want the results. To check any operation, pass LDAP_RES_ANY as the value of this parameter.
all
Specifies how the results of a search are returned. This parameter can have the following values:
timeout
Specifies a maximum interval to wait for the selection to complete. If timeout is a NULL pointer, the select blocks indefinitely. To effect a poll, the timeout parameter should be a non-NULL pointer, pointing to a zero-valued timeval structure.
result
Result of the operation. To interpret the results, pass this to the LDAP parsing routines, such as ldap_result2error(), ldap_parse_result(), and ldap_first_entry().
Returns
One of the following values:
- LDAP_RES_BIND indicates that the LDAPMessage structure contains the result of an LDAP bind operation.
- LDAP_RES_SEARCH_ENTRY indicates that the LDAPMessage structure contains an entry found during an LDAP search operation.
- LDAP_RES_SEARCH_REFERENCE indicates that the LDAPMessage structure contains an LDAPv3 search reference (a referral to another LDAP server) found during an LDAP search operation.
- LDAP_RES_SEARCH_RESULT indicates that the LDAPMessage structure contains the result of an LDAP search operation.
- LDAP_RES_MODIFY indicates that the LDAPMessage structure contains the result of an LDAP modify operation.
- LDAP_RES_ADD indicates that the LDAPMessage structure contains the result of an LDAP add operation.
- LDAP_RES_DELETE indicates that the LDAPMessage structure contains the result of an LDAP delete operation.
- LDAP_RES_MODDN or LDAP_RES_RENAME indicates that the LDAPMessage structure contains the result of an LDAP modify DN operation.
- LDAP_RES_COMPARE indicates that the LDAPMessage structure contains the result of an LDAP compare operation.
- LDAP_RES_EXTENDED indicates that the LDAPMessage structure contains the result of an LDAPv3 extended operation.
- -1 indicates that an error occurred. The error code is set in the LDAP structure. To get the error code, call the ldap_get_lderrno() function. (See Chapter 18, "Result Codes" for a complete listing of error codes.)
- 0 indicates that the operation has timed out.
Description
For more information, see "Performing an Asynchronous Authentication Operation" in Chapter 3, "Writing an LDAP Client" and "To Retrieve the Server Response" in Chapter 4, "Using the LDAP API."
Example
See the examples in the following sections:
- For examples of an asynchronous LDAP add operation, see "Asynchronous Add Operation" of Chapter 7, "Adding, Modifying and Deleting Entries."
- For examples of getting the results of an asynchronous LDAP modify operation, see "Asynchronous Modify Operation" of Chapter 7, "Adding, Modifying and Deleting Entries."
- For examples of getting the results of an asynchronous LDAP delete operation, see "Asynchronous Delete Operation" of Chapter 7, "Adding, Modifying and Deleting Entries."
- For examples of getting the results of an asynchronous LDAP modify DN operation, see "Changing the DN of an Entry" of Chapter 7, "Adding, Modifying and Deleting Entries."
- For examples of getting the results of an asynchronous LDAP search operation, see "Getting Results Asynchronously" of Chapter 5, "Searching a LDAP Directory."
- For examples of getting the results of an asynchronous LDAP bind operation, see "Performing an Asynchronous Authentication Operation" of Chapter 3, "Writing an LDAP Client."
See Also
ldap_add_ext(), ldap_compare_ext(), ldap_delete_ext(), ldap_modify_ext(), ldap_rename(), ldap_simple_bind(), ldap_url_search()
ldap_result2error()
Caution
This function is deprecated and should not be used. It is included in ldap-deprecated.h for backward-compatibility. Please use the newer version, ldap_parse_result().
The ldap_result2error() function returns the corresponding error code for a result produced by the ldap_result() and ldap_search_s() functions.
Syntax
#include <ldap-deprecated.h>
int ldap_result2error( LDAP *ld, LDAPMessage *r, int freeit );Parameters
This function has the parameters listed in Table 17-159.
Table 17-159 ldap_result2error() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
r
Pointer to the LDAPMessage structure representing the results returned by the ldap_result() or ldap_search() function.
freeit
Specifies whether or not the result should be freed after the error code is extracted. The parameter can have the following possible values:
Returns
One of the following values:
- If successful, sets the error code and other error information in the LDAP structure and returns the error code. See Chapter 18, "Result Codes" for a complete listing of error codes.
- 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. Sun Java System Directory Server supports a server plug-in interface that you can use to add SASL support to the server. For details, see the Sun ONE Directory Server Plug-In Programming Guide (http://docs.sun.com/doc/816-6702-10).
Syntax
#include <ldap.h>
int ldap_sasl_bind( LDAP *ld, const char *dn,
const char *mechanism, const struct berval *cred,
LDAPControl **serverctrls, LDAPControl **clientctrls,
int *msgidp );Parameters
This function has the parameters listed in Table 17-160.
Table 17-160 ldap_sasl_bind() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
dn
DN of the user who wants to authenticate. For anonymous authentication, set this to NULL.
mechanism
Name of the SASL mechanism that you want to use for authentication.
cred
Pointer to the berval structure containing the credentials that you want to use for authentication.
serverctrls
Pointer to an array of LDAPControl structures representing LDAP server controls that apply to this operation. If you do not want to pass any server controls, specify NULL for this argument.
clientctrls
Pointer to an array of LDAPControl structures representing LDAP client controls that apply to this operation. If you do not want to pass any client controls, specify NULL for this argument.
msgidp
Pointer to an integer that will be set to the message ID of the LDAP operation. To check the result of this operation, call ldap_result() and ldap_parse_sasl_bind_result() functions.
Returns
One of the following values:
- 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. (For details, see "Specifying the LDAP Version of Your Client" of Chapter 3, "Writing an LDAP Client.")
- LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request to send to the server.
- LDAP_NO_MEMORY if memory cannot be allocated.
- LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.
Description
The ldap_sasl_bind() function authenticates your client to an LDAP server by using a specified SASL mechanism. ldap_sasl_bind() is an asynchronous function; it does not directly return results. If you want the results to be returned directly by the function, call the synchronous function ldap_sasl_bind_s(). In order to get the results of the LDAP SASL bind operation, call the ldap_result(), the ldap_parse_sasl_bind_result(), and the ldap_get_lderrno() functions.
For more details, see "Binding and Authenticating to an LDAP Server" of Chapter 3, "Writing an LDAP Client." For additional information on authenticating through SASL mechanisms, see Chapter 12, "Using SASL Authentication." For a list of possible result codes for an LDAP SASL bind operation, see ldap_sasl_bind_s().
See Also
ldap_result(), ldap_parse_sasl_bind_result(), ldap_get_lderrno(), ldap_sasl_bind_s()
ldap_sasl_bind_s()The ldap_sasl_bind_s() function authenticates your client to an LDAP server synchronously using an SASL mechanism.
Note
The LDAP server must support authentication through SASL. Sun Java System Directory Server supports a server plug-in interface that you can use to add SASL support to the server. For details, see the Sun ONE Directory Server Plug-In Programming Guide (http://docs.sun.com/doc/816-6702-10).
Syntax
#include <ldap.h>
int ldap_sasl_bind_s( LDAP *ld, const char *dn,
const char *mechanism, const struct berval *cred,
LDAPControl **serverctrls, LDAPControl **clientctrls,
struct berval **servercredp );Parameters
This function has the parameters listed in Table 17-161.
Table 17-161 ldap_sasl_bind_s() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
dn
DN of the user who wants to authenticate. For anonymous authentication, set this to NULL.
mechanism
Name of the SASL mechanism that you want to use for authentication.
cred
Pointer to the berval structure containing the credentials that you want to use for authentication.
serverctrls
Pointer to an array of LDAPControl structures representing LDAP server controls that apply to this operation. If you do not want to pass any server controls, specify NULL for this argument.
clientctrls
Pointer to an array of LDAPControl structures representing LDAP client controls that apply to this operation. If you do not want to pass any client controls, specify NULL for this argument.
servercredp
Pointer to a pointer to an berval structure containing any credentials returned by the server. When done, you can free this by calling the ber_alloc() function.
Returns
One of the following values:
- 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. (For details, see "Specifying the LDAP Version of Your Client" of Chapter 3, "Writing an LDAP Client.")
- LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request to send to the server.
- LDAP_DECODING_ERROR if an error occurred when the LDAP API library was decoding the BER-encoded results received from the server.
- LDAP_NO_MEMORY if memory cannot be allocated.
- LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.
- LDAP_LOCAL_ERROR if an error occurred when receiving the results from the server.
Description
The ldap_sasl_bind_s() function authenticates your client to an LDAP server by using a specified SASL mechanism. It is a synchronous function, which directly returns the results of the operation. If you want to perform other operations while waiting for the results of this operation, call the asynchronous function ldap_sasl_bind(). After authenticating a client through SASL, an LDAP server can return a set of credentials in the results. The servercredp argument points to this value.
For more details, see "Binding and Authenticating to an LDAP Server" of Chapter 3, "Writing an LDAP Client." For additional information on authenticating through SASL mechanisms, see Chapter 12, "Using SASL Authentication."
See Also
ldap_search()The ldap_search() function searches the directory asynchronously.
Note
This is an older function that is included in the SDK for backward-compatibility. If you are writing a new LDAP client, use ldap_search_ext() instead.
Syntax
#include <ldap.h>
int ldap_search( LDAP *ld, const char *base, int scope,
const char* filter, char **attrs, int attrsonly );Parameters
This function has the parameters detailed in Table 17-162.
Table 17-162 ldap_search() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
base
DN of the entry that serves as the starting point for the search. For example, setting base to dc=example,dc=com restricts the search to entries at example.com.
scope
Scope of the search, which can be one of the following values:
filter
String representation of the filter to apply in the search. You can specify simple filters with the following syntax:
(attributetype=attributevalue)
For details on the syntax for filters, see "Defining a Search Filter" of Chapter 5, "Searching a LDAP Directory."
attrs
A NULL-terminated array of attribute types to return from entries that match filter. If you specify a NULL, all attributes will be returned.
attrsonly
Specifies whether or not attribute values are returned along with the attribute types. This parameter can have the following values:
Returns
Returns the message ID of the ldap_search() operation.
Note
To check the result of this operation, call ldap_result() and ldap_result2error(). See ldap_search_ext_s() for a list of possible result codes.
Description
Please use the newer version of this function, ldap_search_ext().
Example
Code Example 17-44 searches a directory.
Code Example 17-44 ldap_search() Code Example
#include "examples.h"
static void do_other_work();
unsigned long global_counter = 0;
int
main( int argc, char **argv )
{
LDAP *ld;
LDAPMessage *result, *e;
BerElement *ber;
char *a, *dn;
char **vals;
int i, rc, finished, msgid;
int num_entries = 0;
struct timeval zerotime;
zerotime.tv_sec = zerotime.tv_usec = 0L;
/* get a handle to an LDAP connection */
if ( (ld = ldap_init( MY_HOST, MY_PORT )) == NULL ) {
perror( "ldap_init" );
return( 1 );
}
/* authenticate to the directory as nobody */
if ( ldap_simple_bind_s( ld, NULL, NULL ) != LDAP_SUCCESS ) {
ldap_perror( ld, "ldap_simple_bind_s" );
return( 1 );
}
/* search for all entries with surname of Jensen */
if (( msgid = ldap_search( ld, MY_SEARCHBASE, LDAP_SCOPE_SUBTREE,
MY_FILTER, NULL, 0 )) == -1 ) {
ldap_perror( ld, "ldap_search" );
return( 1 );
}
/* Loop, polling for results until finished */
finished = 0;
while ( !finished ) {
/*
* Poll for results. We call ldap_result with the "all" parameter
* set to zero. This causes ldap_result() to return exactly one
* entry if at least one entry is available. This allows us to
* display the entries as they are received.
*/
result = NULL;
rc = ldap_result( ld, msgid, 0, &zerotime, &result );
switch ( rc ) {
case -1:
/* some error occurred */
ldap_perror( ld, "ldap_result" );
return( 1 );
case 0:
/* Timeout was exceeded. No entries are ready for retrieval. */
if ( result != NULL ) {
ldap_msgfree( result );
}
break;
default:
/*
* Either an entry is ready for retrieval, or all entries have
* been retrieved.
*/
if (( e = ldap_first_entry( ld, result )) == NULL ) {
/* All done */
finished = 1;
if ( result != NULL ) {
ldap_msgfree( result );
}
continue;
}
/* for each entry print out name + all attrs and values */
num_entries++;
if (( dn = ldap_get_dn( ld, e )) != NULL ) {
printf( "dn: %s\n", dn );
ldap_memfree( dn );
}
for ( a = ldap_first_attribute( ld, e, &ber );
a != NULL; a = ldap_next_attribute( ld, e, ber ) ) {
if (( vals = ldap_get_values( ld, e, a )) != NULL ) {
for ( i = 0; vals[ i ] != NULL; i++ ) {
printf( "%s: %s\n", a, vals[ i ] );
}
ldap_value_free( vals );
}
ldap_memfree( a );
}
if ( ber != NULL ) {
ldap_ber_free( ber, 0 );
}
printf( "\n" );
ldap_msgfree( result );
}
/* Do other work here while you are waiting... */
do_other_work();
}
/* All done. Print a summary. */
printf( "%d entries retrieved. I counted to %ld "
"while waiting.\n", num_entries, global_counter );
ldap_unbind( ld );
return( 0 );
}
/*
* Perform other work while polling for results. */
static void
do_other_work()
{
global_counter++;
}
See Also
ldap_search_ext()The ldap_search_ext() function searches the directory asynchronously.
Note
ldap_search_ext() is a new version of the ldap_search() function. If you are writing a new LDAP client, you should call ldap_search_ext().
Syntax
#include <ldap.h>
int ldap_search_ext( LDAP *ld, const char *base, int scope,
const char *filter, char **attrs, int attrsonly,
LDAPControl **serverctrls, LDAPControl **clientctrls,
struct timeval *timeoutp, int sizelimit, int *msgidp );Parameters
This function has the parameters listed in Table 17-163.
Table 17-163 ldap_search_ext() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
base
DN of the entry that serves as the starting point for the search. For example, setting base to dc=example,dc=com restricts the search to entries at example.com.
scope
Scope of the search, which can be one of the following values:
filter
String representation of the filter to apply in the search. You can specify simple filters with the following syntax:
(attributetype=attributevalue)
For details on the syntax for filters, see "Defining a Search Filter" of Chapter 5, "Searching a LDAP Directory."
attrs
A NULL-terminated array of attribute types to return from entries that match filter. If you specify a NULL, all attributes will be returned.
attrsonly
Specifies whether or not attribute values are returned along with the attribute types. This parameter can have the following values:
serverctrls
Pointer to an array of LDAPControl structures representing LDAP server controls that apply to this operation. If you do not want to pass any server controls, specify NULL for this argument.
clientctrls
Pointer to an array of LDAPControl structures representing LDAP client controls that apply to this operation. If you do not want to pass any client controls, specify NULL for this argument.
timeoutp
Pointer to a timeval structure specifying the maximum time to wait for the results of the search. Pass NULL to use the default time limit for the current connection. To specify an infinite time limit, set the tv_sec and tv_usec fields in the timeval structure to 0. See "Setting Search Preferences" of Chapter 5, "Searching a LDAP Directory."
sizelimit
Maximum number of results to return in the search. Pass -1 to use the default size limit for the current connection.
msgidp
Pointer to an integer that will be set to the message ID of the LDAP operation.
Returns
One of the following values:
- 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. (For details, see "Specifying the LDAP Version of Your Client" of Chapter 3, "Writing an LDAP Client.")
- LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request to send to the server.
- LDAP_NO_MEMORY if memory cannot be allocated.
- LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.
Description
The ldap_search_ext() function searches the directory for matching entries. ldap_search_ext() is an asynchronous function; it does not directly return results. If you want the results to be returned directly by the function, call the synchronous function ldap_search_ext_s(). You can also use this function to pass LDAP server controls to the server if you want the server to sort the results or if you want to request a persistent search. (See ldap_create_sort_control() and ldap_create_persistentsearch_control() for more information.) In order to get the results of the ldap_search_ext() operation, you need to call the ldap_result() and the ldap_parse_result() functions.
For more information on searching the directory, see Chapter 5, "Searching a LDAP Directory." For a list of possible result codes for an LDAP search operation, see ldap_search_ext_s().
Example
See Code Example 5-7 of Chapter 5, "Searching a LDAP Directory."
See Also
ldap_search_ext_s(), ldap_result(), ldap_parse_result()
ldap_search_ext_s()The ldap_search_ext_s() function searches the directory synchronously.
Note
ldap_search_ext_s() is a new version of the ldap_search_s() function. If you are writing a new LDAP client, you should call ldap_search_ext_s().
Syntax
#include <ldap.h>
int ldap_search_ext_s( LDAP *ld, const char *base, int scope,
const char *filter, char **attrs, int attrsonly,
LDAPControl **serverctrls, LDAPControl **clientctrls,
struct timeval *timeoutp, int sizelimit, LDAPMessage **res );Parameters
This function has the parameters listed in Table 17-164.
Table 17-164 ldap_search_ext_s() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
base
DN of the entry that serves as the starting point for the search. For example, setting base to dc=example,dc=com restricts the search to entries at example.com.
scope
Scope of the search, which can be one of the following values:
filter
String representation of the filter to apply in the search. You can specify simple filters with the following syntax:
(attributetype=attributevalue)
For details on the syntax for filters, see "Defining a Search Filter" of Chapter 5, "Searching a LDAP Directory."
attrs
A NULL-terminated array of attribute types to return from entries that match filter. If you specify a NULL, all attributes will be returned.
attrsonly
Specifies whether or not attribute values are returned along with the attribute types. This parameter can have the following values:
serverctrls
Pointer to an array of LDAPControl structures representing LDAP server controls that apply to this operation. If you do not want to pass any server controls, specify NULL for this argument.
clientctrls
Pointer to an array of LDAPControl structures representing LDAP client controls that apply to this operation. If you do not want to pass any client controls, specify NULL for this argument.
timeoutp
Pointer to a timeval structure specifying the maximum time to wait for the results of the search. See "Setting Search Preferences" of Chapter 5, "Searching a LDAP Directory."
sizelimit
Maximum number of results to return in the search.
res
Results of the search (when the call is completed).
Returns
One of the following values:
- 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. (For details, see "Specifying the LDAP Version of Your Client" of Chapter 3, "Writing an LDAP Client.")
- LDAP_FILTER_ERROR if an error occurred when parsing and BER-encoding the search filter specified by the filter argument.
- LDAP_TIMEOUT if the search exceeded the time specified by the timeoutp argument.
- 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.
Description
The ldap_search_ext_s() searches the directory for matching entries. The function ldap_search_ext_s() is synchronous; it directly returns the results of the operation. If you want to perform other operations while waiting for the results of this operation, call the asynchronous function ldap_search_ext(). You can also use ldap_search_ext_s() to pass LDAP server controls to the server if you want the server to sort the results or if you want to request a persistent search. (See ldap_create_sort_control() and ldap_create_persistentsearch_control() for more information.)
For more information on searching the directory, see Chapter 5, "Searching a LDAP Directory."
Example
See Code Example 5-4 of Chapter 5, "Searching a LDAP Directory."
See Also
ldap_search_s()The ldap_search_s() function searches the directory synchronously.
Note
This is an older function that is included in the SDK for backward-compatibility. If you are writing a new LDAP client, use ldap_search_ext_s() instead.
Syntax
#include <ldap.h>
int ldap_search_s( LDAP *ld, const char *base, int scope,
const char* filter, char **attrs, int attrsonly,
LDAPMessage **res );Parameters
This function has the parameters listed in Table 17-165.
Table 17-165 ldap_search_s() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
base
DN of the entry that serves as the starting point for the search. For example, setting base to dc=example,dc=com restricts the search to entries at example.com.
scope
Scope of the search, which can be one of the following values:
filter
String representation of the filter to apply in the search. You can specify simple filters with the following syntax:
(attributetype=attributevalue)
For details on the syntax for filters, see "Defining a Search Filter" of Chapter 5, "Searching a LDAP Directory."
attrs
A NULL-terminated array of attribute types to return from entries that match filter. If you specify a NULL, all attributes will be returned.
attrsonly
Specifies whether or not attribute values are returned along with the attribute types. This parameter can have the following values:
res
Results of the search (when the call is completed).
Returns
For a list of possible result codes for an LDAP search operation, see ldap_search_ext_s().
Description
Please use the newer version of this function, ldap_search_ext_s().
Example
Code Example 17-45 searches the directory for all people whose surname (last name) is “Jensen”.
Code Example 17-45 ldap_search_s() Code Example
#include "examples.h"
int main( int argc, char **argv )
{
LDAP *ld;
LDAPMessage *result, *e;
BerElement *ber;
char *a, *dn;
char **vals;
int i;
/* get a handle to an LDAP connection */
if ( (ld = ldap_init( MY_HOST, MY_PORT )) == NULL ) {
perror( "ldap_init" );
return( 1 );
}
/* authenticate to the directory as nobody */
if ( ldap_simple_bind_s( ld, NULL, NULL ) != LDAP_SUCCESS ) {
ldap_perror( ld, "ldap_simple_bind_s" );
return( 1 );
}
/* search for all entries with surname of Jensen */
if ( ldap_search_s( ld, MY_SEARCHBASE, LDAP_SCOPE_SUBTREE,
MY_FILTER, NULL, 0, &result ) != LDAP_SUCCESS ) {
ldap_perror( ld, "ldap_search_s" );
return( 1 );
}
/* for each entry print out name + all attrs and values */
for ( e = ldap_first_entry( ld, result ); e != NULL;
e = ldap_next_entry( ld, e ) ) {
if ( (dn = ldap_get_dn( ld, e )) != NULL ) {
printf( "dn: %s\n", dn );
ldap_memfree( dn );
}
for ( a = ldap_first_attribute( ld, e, &ber );
a != NULL; a = ldap_next_attribute( ld, e, ber ) ) {
if ((vals = ldap_get_values( ld, e, a)) != NULL ) {
for ( i = 0; vals[i] != NULL; i++ ) {
printf( "%s: %s\n", a, vals[i] );
}
ldap_value_free( vals );
}
ldap_memfree( a );
}
if ( ber != NULL ) {
ldap_ber_free( ber, 0 );
}
printf( "\n" );
}
ldap_msgfree( result );
ldap_unbind( ld );
return( 0 );
}
See Also
ldap_search_st()The ldap_search_st() function searches the directory synchronously within a specified time limit.
Note
This is an older function that is included in the SDK for backward-compatibility. If you are writing a new LDAP client, use ldap_search_ext_s() instead.
Syntax
#include <ldap.h>
int ldap_search_st( LDAP *ld, const char *base, int scope,
const char* filter, char **attrs, int attrsonly,
struct timeval *timeout, LDAPMessage **res );Parameters
This function has the parameters listed in Table 17-166.
Table 17-166 ldap_search_st() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
base
DN of the entry that serves as the starting point for the search. For example, setting base to dc=example,dc=com restricts the search to entries at example.com.
scope
Scope of the search, which can be one of the following values:
filter
String representation of the filter to apply in the search. You can specify simple filters with the following syntax:
(attributetype=attributevalue)
For details on the syntax for filters, see "Defining a Search Filter" of Chapter 5, "Searching a LDAP Directory."
attrs
A NULL-terminated array of attribute types to return from entries that match filter. If you specify a NULL, all attributes will be returned.
attrsonly
Specifies whether or not attribute values are returned along with the attribute types. This parameter can have the following values:
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_set_filter_additions()The ldap_set_filter_additions() function sets a prefix to be prepended and a suffix to be appended to all filters returned by the ldap_getfirstfilter() and ldap_getnextfilter() function calls.
Syntax
#include <ldap.h>
int ldap_set_filter_additions( LDAPFiltDesc *lfdp, char *prefix,
char *suffix );Parameters
This function has the parameters listed in Table 17-167.
Table 17-167 ldap_set_filter_additions() Function Parameters
Parameter
Description
lfdp
Pointer to an LDAPFiltDesc structure.
prefix
Prefix to prepend to all filters. If NULL, no prefix is prepended.
suffix
Suffix to append to all filters. If NULL, no suffix is appended.
Returns
One of the following values:
- LDAP_SUCCESS if successful.
- If unsuccessful, returns an LDAP error code. See Chapter 18, "Result Codes" for a complete listing.
Example
Code Example 17-46 loads the filter configuration file named myfilters.conf into memory and adds the prefix "(&(objectClass=person)" and the suffix ")" to each filter retrieved.
Code Example 17-46 ldap_set_filter_additions() Code Example
#include <ldap.h>
...
LDAPFiltDesc *lfdp;
char *filter_file = "myfilters.conf";
char *prefix = "(&(objectClass=person)";
char *suffix = ")";
int rc;
...
lfdp = ldap_init_getfilter( filter_file );
rc = ldap_set_filter_additions( ldfp, prefix, suffix );
if ( rc != LDAP_SUCCESS ) {
printf( "Error setting filter prefix and suffix\n");
return( rc );
}
...
See Also
ldap_getfirstfilter(), ldap_getnextfilter()
ldap_setfilteraffixes()
Caution
This function is deprecated and should not be used. It is included in ldap-deprecated.h for backward-compatibility. Please use ldap_set_filter_additions().
For more information, see the man page for ldap_setfilteraffixes.
See Also
ldap_set_lderrno()The ldap_set_lderrno() function sets an error code and information about an error in an LDAP structure.
Syntax
#include <ldap.h>
int ldap_set_lderrno( LDAP *ld, int e, char *m, char *s );Parameters
This function has the parameters listed in Table 17-168.
Table 17-168 ldap_set_lderrno() Function Parameters
Parameter
Description
ld
Pointer to an LDAP structure containing information about the connection to the LDAP server.
e
The error code that you want to set.
m
In the event that an entry for a specified DN cannot be found, set this parameter to the portion of the DN that identifies an existing entry. (See "Receiving the Matching Portion of a DN" of Chapter 4, "Using the LDAP API" for details.)
s
The text of the error message that you want associated with this error code.
Returns
One of the following values:
- LDAP_SUCCESS if successful.
- If unsuccessful, returns an LDAP error code. See Chapter 18, "Result Codes" for a complete listing.
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.
For more information, see "Setting Error Codes" of Chapter 4, "Using the LDAP API."
Example
Code Example 17-47 attempts to perform an operation. If the operation fails, the LDAP_PARAM_ERROR error code is placed in the LDAP structure.
Code Example 17-47 ldap_set_lderrno() Code Example
#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
This function has the parameters listed in Table 17-169.
Table 17-169 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 17-170 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 Table 17-170.
The option parameter can have one of the values listed in Table 17-170.
Table 17-170 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 LDAPv3 client controls you want sent with every request by default.
The data type for the optdata parameter is (LDAPControl ***).
LDAP_OPT_DESC
Socket descriptor underlying the main LDAP connection. The LBER_SOCKET data type depends on the platform that you are using:
The data type for the optdata parameter is (LBER_SOCKET *).
LDAP_OPT_DEREF
Determines how aliases work during a search. optdata can be one of the following values:
- LDAP_DEREF_NEVER specifies that aliases are never dereferenced.
- LDAP_DEREF_SEARCHING specifies that aliases are dereferenced when searching under the base object (but not when finding the base object).
- LDAP_DEREF_FINDING specifies that aliases are dereferenced when finding the base object (but not when searching under the base object).
- LDAP_DEREF_ALWAYS specifies that aliases are always dereferenced when finding and searching under the base object.
The data type for the optdata parameter is (int *).
LDAP_OPT_DNS_FN_PTRS
DEPRECATED OPTION: Lets you use alternate DNS functions for getting the host entry of the LDAP server.
The data type for the optdata parameter is (struct ldap_dns_fns *).
LDAP_OPT_ERROR_NUMBER
Retrieves the result code for the most recent LDAP error that occurred in this session.
The data type for the optdata parameter is (int *).
LDAP_OPT_ERROR_STRING
Retrieves the error message returned with the result code for the most recent LDAP error that occurred in this session.
The data type for the optdata parameter is (char **).
LDAP_OPT_EXTRA_THREAD_FN_PTRS
Lets you specify the locking and semaphore functions that you want called when getting results from the server. (See Chapter 14, "Writing Multithreaded Clients" for details.)
The data type for the optdata parameter is (struct ldap_extra_thread_fns *).
LDAP_OPT_HOST_NAME
Sets the host name (or list of hosts) for the primary LDAP server.
The data type for the optdata parameter is (char **).
LDAP_OPT_IO_FN_PTRS
DEPRECATED OPTION: Lets you use alternate communication stacks.
The data type for the optdata parameter is (struct ldap_io_fns *).
LDAP_OPT_MATCHED_DN
Gets the matched DN value returned with the most recent LDAP error that occurred for this session.
The data type for the optdata parameter is (char **)
LDAP_OPT_MEMALLOC_FN_PTRS
Gets a pointer to the callback structure which you previously set.
The data type for the optdata parameter is (struct ldap_memalloc_fnsldap_io_fns *).
LDAP_OPT_PROTOCOL_VERSION
Version of the protocol supported by your client. You can specify either LDAP_VERSION2 or LDAP_VERSION3. If no version is set, the default is LDAP_VERSION2. In order to use LDAPv3 features, you need to set the protocol version to LDAP_VERSION3.
The data type for the optdata parameter is (int *).
LDAP_OPT_REBIND_ARG
Lets you set the last argument passed to the routine specified by LDAP_OPT_REBIND_FN. You can also set this option by calling the ldap_set_rebind_proc() function.
The data type for the optdata parameter is (void *).
LDAP_OPT_REBIND_FN
Lets you set the routine to be called when you need to authenticate a connection with another LDAP server (for example, during the course of following a referral). You can also set this option by calling the ldap_set_rebind_proc() function.
The data type for the optdata parameter is (LDAP_REBINDPROC_CALLBACK *).
LDAP_OPT_RECONNECT
If the connection to the server is lost, determines whether or not the same connection handle should be used to reconnect to the server. By default, this option is off. For details, see "Handling Failover" of Chapter 4, "Using the LDAP API." optdata can be one of the following values:
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:
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:
The data type for the optdata parameter is (int *).
LDAP_OPT_SERVER_CONTROLS
Pointer to an array of LDAPControl structures representing the LDAPv3 server controls you want sent with every request by default. Typically, since controls are specific to the type of request, you may want to pass the controls using operation-specific functions (such as ldap_add_ext()) instead.
The data type for the optdata parameter is (LDAPControl ***).
LDAP_OPT_SIZELIMIT
Maximum number of entries that should be returned by the server in search results. The LDAP server may impose a smaller size limit than the limit you specify as the server administrator also has the ability to set this limit.
The data type for the optdata parameter is (int *).
LDAP_OPT_SSL
Determines whether or not SSL is enabled. optdata can be one of the following values:
The data type for the optdata parameter is (int *).
LDAP_OPT_THREAD_FN_PTRS
Lets you specify the thread function pointers. (See Chapter 14, "Writing Multithreaded Clients" for details.)
The data type for the optdata parameter is (struct ldap_thread_fns *).
LDAP_OPT_TIMELIMIT
Maximum number of seconds that should be spent by the server when answering a search request. The LDAP server may impose a shorter time limit than the limit you specify as the server administrator also has the ability to set this limit.
The data type for the optdata parameter is (int *).
LDAP_X_OPT_EXTIO_FN_PTRS
Extended I/O function callback option.
LDAP_X_OPT_CONNECT_TIMEOUT
Value of a timeout (expressed in milliseconds) for nonblocking connect call.
The data type for the optdata parameter is (int *).
LDAP_X_OPT_SOCKBUF
Socket buffer structure associated to the LDAP connection.
Returns
One of the following values:
- LDAP_SUCCESS if successful.
- -1 if unsuccessful.
Description
For more information, see "Setting Session Preferences" of Chapter 3, "Writing an LDAP Client."
Example
Code Example 17-48 sets the maximum number of entries returned in a search.
Code Example 17-48 ldap_set_option() Code 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 */
if ( ( ld = ldap_init( host, LDAP_PORT ) ) == NULL ) {
perror( "ldap_init" );
return( 1 );
}
/* Set the maximum number of entries returned */
if (ldap_set_option( ld, LDAP_OPT_SIZELIMIT, &max_ret) != LDAP_SUCCESS) {
ldap_perror( ld, "ldap_set_option" );
return( 1 );
}
...
See Also
ldap_init(), ldap_get_option()
ldap_set_rebind_proc()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
This function has the parameters listed in Table 17-171.
Table 17-171 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 );
Note
LDAP_CALL and LDAP_CALLBACK are used to set up calling conventions, such as Pascal calling conventions on Windows. These are defined in the lber.h header file.
The following procedure explains what the rebind function is expected to do. LDAP clients that are built with Sun Java System LDAP SDK for C use this procedure when following referrals.
- The LDAP server sends a referral back to the client.
- The client calls the rebind function, passing 0 as the freeit argument.
- The rebind function sets the dnp, passwdp, and authmethodp arguments to point to the following information:
- If successful, the rebind function returns LDAP_SUCCESS, and referral processing continues. (If any other value is returned, referral processing stops, and that value is returned as the result code for the original LDAP request.)
- The client gets the DN, credentials, and authentication method from the arguments of the rebind function and uses this information to authenticate to the new LDAP server.
- The client calls the rebind function again, passing 1 as the freeit argument.
- The rebind function frees any memory allocated earlier to specify the DN and credentials.
You need to write a rebind function that does the following:
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.
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
Code Example 17-49 demonstrates how to write and register a rebind function.
Code Example 17-49 ldap_set_rebind_proc() Code Example
#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=Directory Manager";
/* Get a handle to an LDAP connection */
if ( (ld = ldap_init( "directory.myhost.com", 389 )) == NULL ) {
perror( "ldap_init" );
return( 1 );
}
/* Specify the function used for reauthentication on referrals */
ldap_set_rebind_proc( ld, rebindproc, (void *)testarg );
/* Authenticate */
if ( ldap_simple_bind_s( ld, "uid=bjensen,ou=People,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
This function has the parameters listed in Table 17-172.
Table 17-172 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. ldap_simple_bind() is an asynchronous function; it does not directly return results. If you want the results to be returned directly by the function, call the synchronous function ldap_simple_bind_s().
Note
If you specify a DN but no password, your client will bind to the server anonymously. If you want a NULL password to be rejected as an incorrect password, you need to write code to perform the check before you call the ldap_simple_bind() function.
For additional information on authenticating to the LDAP server, see "Binding and Authenticating to an LDAP Server" of Chapter 3, "Writing an LDAP Client."
Caution
The use of this function may be a security threat if used on a non-secured connection as the password is transmitted in cleartext. For password-based authentication, use a secure connection (ldapssl_init() or ldapssl_tls_start_s()) or SASL Digest-MD5 mechanism (ldap_sasl_bind() or ldap_sasl_bind_s()).
Example
Code Example 17-50 calls ldap_simple_bind() to authenticate the user Barbara Jensen to the directory.
Code Example 17-50 ldap_simple_bind() Code Example
#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.sun.com:389 */
if ( ( ld = ldap_init( host, LDAP_PORT ) ) == NULL ) {
perror( "ldap_init" );
return( 1 );
}
/* Attempt to bind with the LDAP server */
msgid = ldap_simple_bind( ld, dn, pw );
/* Initialize the value returned by ldap_result() */
rc = 0;
/* While the operation is still running, do this: */
while ( rc == 0 ) {
... /* do other work while waiting */...
/* Check the status of the LDAP operation */
rc = ldap_result( ld, msgid, NULL, &zerotime, &result );
switch( rc ) {
/* If -1 was returned, an error occurred */
case -1:
ldap_perror( ld, "Error in results: " );
return( 1 );
/* If 0 was returned, the operation is still in progress */
case 0:
continue;
/* If any other value is returned, assume we are done */
default:
/* Check if the "bind" operation was successful */
if ( ldap_result2error( result ) != LDAP_SUCCESS ) {
ldap_perror( ld, "Error binding to server: " );
return( 1 );
}
}
}
...
See Also
ldap_simple_bind_s()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
This function has the parameters listed in Table 17-173.
Table 17-173 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 LDAPv3. Make sure that you set the version of your LDAP client to version 3 before calling this function. (For details, see "Specifying the LDAP Version of Your Client" of Chapter 3, "Writing an LDAP Client.")
- LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request to send to the server.
- LDAP_DECODING_ERROR if an error occurred when the LDAP API library was decoding the BER-encoded results received from the server.
- LDAP_NO_MEMORY if memory cannot be allocated.
- LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.
- LDAP_LOCAL_ERROR if an error occurred when receiving the results from the server.
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. ldap_simple_bind_s() is a synchronous function, which directly returns the results of the operation. If you want to perform other operations while waiting for the results of this operation, call the asynchronous function ldap_simple_bind() instead.
Note
If you specify a DN but no password, your client will bind to the server anonymously. If you want a NULL password to be rejected as an incorrect password, you need to write code to perform the check before you call the ldap_simple_bind_s() function.
For additional information on authenticating to the LDAP server, see "Binding and Authenticating to an LDAP Server" of Chapter 3, "Writing an LDAP Client."
Caution
The use of this function may be a security threat if used on a non-secured connection as the password is transmitted in cleartext. For password-based authentication, use a secure connection (ldapssl_init() or ldapssl_tls_start_s()) or SASL Digest-MD5 mechanism (ldap_sasl_bind() or ldap_sasl_bind_s()).
Example
Code Example 17-51 uses the synchronous ldap_simple_bind_s() function to authenticate to the directory as the user Barbara Jensen.
Code Example 17-51 ldap_simple_bind_s() Code Example
#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 */
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_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
This function has the parameters listed in Table 17-174.
Table 17-174 ldap_sort_entires() 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. For details, see "Sorting Entries by an Attribute" of Chapter 5, "Searching a LDAP Directory."
Returns
One of the following values:
- LDAP_SUCCESS if successful.
- If unsuccessful, returns a NULL and sets the appropriate error code in the LDAP structure. To get the error code, call ldap_get_lderrno(). (See Chapter 18, "Result Codes" for a complete listing of error codes.)
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.
For additional information, see "Sorting the Search Results" of Chapter 5, "Searching a LDAP Directory."
Example
Code Example 17-52 sorts entries by the roomNumber attribute.
Code Example 17-52 ldap_sort_entries() Code Example
#include <stdio.h>
#include <string.h>
#include <ldap.h>
LDAP *ld;
LDAPMessage *result;
char *my_searchbase = "dc=example,dc=com";
char *my_filter = "(sn=Jensen)";
char *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_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
This function has the parameters listed in Table 17-175.
Table 17-175 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:
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 comparision 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
This function has the parameters listed in Table 17-176.
Table 17-176 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.
See Chapter 18, "Result Codes" for a complete listing of error codes.
Description
For additional information, see "Sorting the Search Results" in Chapter 5, "Searching a LDAP Directory."
Example
Code Example 17-53 sorts the values of attributes before printing them.
Code Example 17-53 ldap_sort_values() Code Example
#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
This function has the parameters listed in Table 17-177.
Note
Please see the description of the sslstrength value and note the potential problems that can be caused by passing in wrong host and portname values.
Table 17-177 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:
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:
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, 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:
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. For details, see Chapter 11, "Connecting Over SSL."
Example
Code Example 17-54 initializes a client before connecting with a secure LDAP server.
Code Example 17-54 ldapssl_advclientauth_init() Code Example
#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(), 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
This function has the parameters listed in Table 17-178.
Table 17-178 ldapssl_client_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 used currently.)
Returns
One of the following values:
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.
Note
You must call ldapssl_client_init() before calling the ldapssl_init() function to connect to the server. For details, see Chapter 11, "Connecting Over SSL."
Example
Code Example 17-55 initializes a client before connecting with a secure LDAP server.
Code Example 17-55 ldapssl_client_init() Code Example
#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 );
}
...
See Also
ldap_init(), 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
This function has the parameters listed in Table 17-179.
Table 17-179 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:
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:
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. For details, see Chapter 11, "Connecting Over SSL."
Example
Code Example 17-56 initializes a client before connecting with a secure LDAP server.
Code Example 17-56 ldapssl_clientauth_init() Code Example
#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(), 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
This function has the parameters listed in Table 17-180.
Table 17-180 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:
See Also
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
This function has the parameters listed in Table 17-181.
Table 17-181 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:
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:
The errors returned by these functions are usually related to certificate database corruption, missing certs in a certificate database, client authentication failures, and other general SSL errors.
For more information, see "Getting the Error Message from an Error Code" of Chapter 4, "Using the LDAP API."
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
This function has the parameters listed in Table 17-182.
Table 17-182 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 a -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. For details, see Chapter 11, "Connecting Over SSL."
Note
Calling this function is equivalent to calling ldap_init() followed by ldapssl_install_routines() and ldap_set_option() to set the LDAP_OPT_SSL option to LDAP_OPT_ON.
Example
Code Example 17-57 connects your client to a secure LDAP server.
Code Example 17-57 ldapssl_init() Code Example
#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.netscape.com", LDAPS_PORT, 1 )) == NULL {
perror( "ldapssl_init" );
return( 1 );
}
...
/* Client can now perform LDAP operations on the secure LDAP server */
...
See Also
ldap_init(), ldapssl_client_init(), ldapssl_install_routines()
ldapssl_install_routines()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
This function has the parameter listed in Table 17-183.
Table 17-183 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:
Description
You need to call ldapssl_install_routines() in combination with ldap_init() 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
Code Example 17-58 connects your client to a secure LDAP server.
Code Example 17-58 ldapssl_install_routines() Code Example
#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 */
if ( (ld = ldap_init( MY_HOST, 6360 )) == NULL ) {
perror( "ldap_init" );
return( 1 );
}
/* Load SSL routines */
if ( ldapssl_install_routines( ld ) != LDAP_SUCCESS ) {
ldap_perror( ld, "ldapssl_install_routines" );
return( 1 );
}
/* Set the option to use SSL with the default connection */
if (ldap_set_option( ld, LDAP_OPT_SSL, LDAP_OPT_ON ) != LDAP_SUCCESS) {
ldap_perror( ld, "ldap_set_option" );
return( 1 );
}
...
See Also
ldap_init(), ldapssl_init(), ldapssl_client_init()
ldapssl_pkcs_init()
Caution
This function is deprecated and should not be used. It is included in ldap-deprecated.h for backward-compatibility.
The ldap_pcks_init() function provides thread-safe SSL 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. Consult the NSPR documentation at http://www.mozilla.org/projects/nspr/ for more information.
Description
The ldap_pkcs_init() structure sets up callbacks for the security library to obtain required runtime information. It should be used in place of ldapssl_client_init(), ldapssl_clientauth_init(), and ldapssl_advclientauth_init().
Note
The LDAP SDK for C uses the Public Key Cryptography Standard (PKCS) API implemented in Network Security Services (NSS) to provide SSL security support. Specifically, NSS implements the security API as defined in the PKCS#11 standard.
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. Code Example 17-59 defines the ldapssl_pkcs_fns structure.
Code Example 17-59 ldapssl_pkcs_fns Structure Definition
typedef int (LDAP_PKCS_GET_TOKEN_CALLBACK)
(void *context, char **tokenname);
typedef int (LDAP_PKCS_GET_PIN_CALLBACK)
(void *context, const char *tokenname, char **tokenpin);
typedef int (LDAP_PKCS_GET_CERTPATH_CALLBACK)
(void *context, char **certpath);
typedef int (LDAP_PKCS_GET_KEYPATH_CALLBACK)(void *context,
char **keypath);
typedef int (LDAP_PKCS_GET_MODPATH_CALLBACK)
(void *context, char **modulepath);
typedef int (LDAP_PKCS_GET_CERTNAME_CALLBACK)
(void *context, char **certname);
typedef int (LDAP_PKCS_GET_DONGLEFILENAME_CALLBACK)
(void *context, char **filename);
#define PKCS_STRUCTURE_ID 1
struct ldapssl_pkcs_fns {
int local_structure_id;
void *local_data;
LDAP_PKCS_GET_CERTPATH_CALLBACK *pkcs_getcertpath;
LDAP_PKCS_GET_CERTNAME_CALLBACK *pkcs_getcertname;
LDAP_PKCS_GET_KEYPATH_CALLBACK *pkcs_getkeypath;
LDAP_PKCS_GET_MODPATH_CALLBACK *pkcs_getmodpath;
LDAP_PKCS_GET_PIN_CALLBACK *pkcs_getpin;
LDAP_PKCS_GET_TOKEN_CALLBACK *pkcs_gettokenname;
LDAP_PKCS_GET_DONGLEFILENAME_CALLBACK *pkcs_getdonglefilename;
};
See Also
ldapssl_client_init(), ldapssl_clientauth_init(), ldapssl_advclientauth_init()
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
This function has the parameters listed in Table 17-184.
Note
Please see the description of the sslstrength value and note the potential problems that can be caused by passing in wrong host and portname values.
Table 17-184 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:
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(), 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
This function has the parameters listed in Table 17-185.
Note
Please see the description of the sslstrength value and note the potential problems that can be caused by passing in wrong host and portname values.
Table 17-185 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
This function has the parameter listed in Table 17-186.
Table 17-186 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
This function has the parameters listed in Table 17-187.
Table 17-187 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
Description
The attribute list should be freed using ldap_value_free().
See Also
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
This function has the parameter listed in Table 17-188.
ldap_ufn_search_c()
Caution
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_ct()
Caution
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()
Caution
This function will be deprecated and should not be used. It is included in ldap-to-be-deprecated.h for backward-compatibility.
ldap_ufn_setfilter()
Caution
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()
Caution
This function will be deprecated and should not be used. It is included in ldap-to-be-deprecated.h for backward-compatibility.
ldap_ufn_timeout()
Caution
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
This function has the parameter listed in Table 17-189.
Table 17-189 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.
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.
For additional information, see "Closing the Connection to the Server" of Chapter 3, "Writing an LDAP Client."
Example
Code Example 17-60 closes the current connection with the LDAP server.
Code Example 17-60 ldap_unbind() Code Example
#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
This function has the parameter listed in Table 17-190.
Table 17-190 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.
For additional information, see "Closing the Connection to the Server" of Chapter 3, "Writing an LDAP Client."
Example
Code Example 17-61 closes the current connection with the LDAP server.
Code Example 17-61 ldap_unbind_s() Code Example
#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
This function has the parameters listed in Table 17-191.
Table 17-191 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 LDAPv3. Make sure that you set the version of your LDAP client to version 3 before calling this function. (For details, see "Specifying the LDAP Version of Your Client" of Chapter 3, "Writing an LDAP Client.")
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.
Note
Unlike the other two unbind functions, ldap_unbind_ext() allows you to explicitly include both server and client controls in your unbind request. However, since there is no server response to an unbind request, there is no way to receive a response from a server control that is included.
For additional information, see "Closing the Connection to the Server" of Chapter 3, "Writing an LDAP Client."
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
This function has the parameters listed in Table 17-192.
Table 17-192 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.
Description
For more information, see "Getting the Components of an LDAP URL" in Chapter 9, "Working with LDAP URLs."
Example
Code Example 17-62 parses an LDAP URL and prints out each component of it.
Code Example 17-62 ldap_url_parse() Code Example
#include <stdio.h>
#include <ldap.h>
...
char *my_url = "ldap://ldap.sun.com:5000/dc=example,dc=com?cn,mail,telephoneNumber?sub?(sn =Jensen)";
LDAPURLDesc *ludpp;
int res, i;
...
if ( ( res = ldap_url_parse( my_url, &ludpp ) ) != 0 ) {
switch( res ){
case LDAP_URL_ERR_NOTLDAP:
printf( "URL does not begin with \"ldap://\"\n" );
break;
case LDAP_URL_ERR_NODN:
printf( "URL 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_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
This function has the parameters listed in Table 17-193.
Table 17-193 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
This function has the parameters listed in Table 17-194.
Table 17-194 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:
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().
For more information on processing LDAP searches specified as URLs, see "Processing an LDAP URL" of Chapter 9, "Working with LDAP URLs."
Example
Code Example 17-63 returns the message ID.
Code Example 17-63 ldap_url_search() Code Example
#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 */
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
This function has the parameters listed in Table 17-195.
Table 17-195 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:
res
Results of the search (when the call is completed).
Returns
One of the following values:
- LDAP_SUCCESS if successful.
- If unsuccessful, returns the LDAP error code for the operation.
See Chapter 18, "Result Codes" for a complete listing.
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().
For more information on processing LDAP searches specified as URLs, see "Processing an LDAP URL" of Chapter 9, "Working with LDAP URLs."
Example
Code Example 17-64 processes a search request from an LDAP URL.
Code Example 17-64 ldap_url_search_s() Code Example
#include <stdio.h>
#include <ldap.h>
...
LDAP *ld;
LDAPMessage *result;
char *my_url = "ldap://ldap.sun.com/dc=example,dc=com?cn,mail,telephoneNumber?sub?(sn=Jens en)";
...
/* 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
This function has the parameters listed in Table 17-196.
Table 17-196 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:
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 LDAPv3. Make sure that you set the version of your LDAP client to version 3 before calling this function. (For details, see "Specifying the LDAP Version of Your Client" of Chapter 3, "Writing an LDAP Client.")
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 timeout period for the search.
For more information, see "Processing an LDAP URL" of Chapter 9, "Working with LDAP URLs."
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
This function has the parameter listed in Table 17-197.
Table 17-197 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
This function has the parameter listed in Table 17-198.
Table 17-198 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
This function has the parameter listed in Table 17-199.
Table 17-199 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
This function has the parameter listed in Table 17-200.
Table 17-200 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
This function has the parameter listed in Table 17-201.
Table 17-201 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
This function has the parameter listed in Table 17-202.
Table 17-202 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
This function has the parameter listed in Table 17-203.
Table 17-203 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
This function has the parameter listed in Table 17-204.
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
This function has the parameter listed in Table 17-205.
Table 17-205 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
This function has the parameter listed in Table 17-206.
Table 17-206 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
This function has the parameter listed in Table 17-207.
Table 17-207 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_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
This function has the parameters listed in Table 17-208.
Table 17-208 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 pre-defined 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()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
This function has the parameters listed in Table 17-209.
Table 17-209 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 pre-defined 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_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
This function has the parameter listed in Table 17-210.
Description
Use the ldap_value_free_len() function if the values are berval structures.
For additional information, see "Getting the Values of an Attribute" of Chapter 5, "Searching a LDAP Directory."
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
This function has the parameters listed in Table 17-211.
Table 17-211 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.
For additional information, see "Getting the Values of an Attribute" of Chapter 5, "Searching a LDAP Directory."
Example
See the example under ldap_get_values_len().
See Also
ldap_get_values(), ldap_get_values_len()
ldap_version()
Caution
This function is deprecated and should not be used. It is included in ldap-deprecated.h for backward-compatibility. Please use ldap_get_option() with LDAP_OPT_API_INFO and an LDAPAPIInfo structure.
The ldap_version() function gets version information about the LDAP SDK for C libraries.
Syntax
#include <ldap.h>
int ldap_version( LDAPVersion *ver );Parameters
This function has the parameter listed in Table 17-212.
Table 17-212 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 SDK for C, multiplied by 100. For example, for version 1.0, the function returns 100.
See Also
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
This function has the parameters listed in Table 17-214.
Table 17-213 ldap_x_calloc() Function Parameters
Parameter
Description
nelem
Number of elements for which memory is to be allocated.
elsize
Size of each element.
Returns
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
This function has the parameter listed in Table 17-214.
Table 17-214 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.
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.
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
This function has the parameter listed in Table 17-215.
Table 17-215 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
This function has the parameters listed in Table 17-216.
Table 17-216 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
This function has the parameters listed in Table 17-217.
Table 17-217 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
This function has the parameters listed in Table 17-218.
Table 17-218 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_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_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
This function has the parameters listed in Table 17-219.
Table 17-219 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_init()The prldap_init() function creates a new session handle with Netscape Portable Runtime (NSPR) I/O, threading, and DNS functions installed.
Syntax
#include <ldappr.h>
LDAP * prldap_init( const char *defhost, int defport, int shared );Parameters
This function has the parameters listed in Table 17-220.
Table 17-220 prldap_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.
shared
Pass a non-zero value if you plan to use this LDAP handle for more than one thread.
Returns
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()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
This function has the parameters listed in Table 17-221.
Table 17-221 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_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
This function has the parameters listed in Table 17-225.
Table 17-222 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_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
This function has the parameters listed in Table 17-223.
Table 17-223 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_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
This function has the parameters listed in Table 17-224.
Table 17-224 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_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
This function has the parameters listed in Table 17-225.
Table 17-225 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
