functions C SDK functions C SDK functions This chapter contains detailed reference material for each public function of &DirectorySDKForC;. Each reference gives a description of the function, and its usage syntax, parameters and return values. In many cases, an example program is also included. The chapter contains the following sections: Typographic Conventions Function Summary by Task Functions Alphabetically The general purpose of a function is usually given by its name. Table 21–1 lists the naming conventions used when adding suffixes to function names. Suffix Description _ext Identifies extended functions introduced for LDAP v3. These functions are augmented through additional parameters, as compared to the functions they replace. As LDAP v3 has become widely adopted, it is recommended you use extended functions whenever possible in your new applications. _s Identifies the synchronous form of functions. A synchronous function will not return until it receives a response from the server, thereby blocking the caller. Similar function names without this suffix are asynchronous, allowing the caller to perform other operations while waiting for a result. The synchronous and asynchronous forms exist only for functions which involve possible delays due to communication with the LDAP server. Functions which do not involve communication do not use this suffix. C SDK functions summary of functions C SDK In the following sections the functions of &DirectorySDKForC; are grouped into task categories. C SDK functions for BER The functions listed in Table 21–2 may be used to encode and decode with Basic Encoding Rules (BER). They are often used inside of control and extension values. Function Description ber_alloc, ber_alloc_t , ber_sockbuf_alloc, ber_special_alloc Allocate new BER elements. ber_bvecfree, ber_bvfree , ber_free, ber_sockbuf_free , ber_sockbuf_free_data Free allocated memory. ber_bvdup, ber_dup Duplicate BER structures. ber_init, ber_init_w_nullchar Construct new structures. ber_get_boolean, ber_get_int, ber_get_next, ber_get_next_buffer, ber_get_next_buffer_ext , ber_get_null, ber_get_option, ber_get_stringa, ber_get_stringal, ber_get_stringb Retrieve miscellaneous information. ber_put_bitstring, ber_put_boolean, ber_put_enum, ber_put_int, ber_put_null, ber_put_ostring, ber_put_seq, ber_put_set, ber_put_string Write miscellaneous information. ber_first_element, ber_next_element, ber_peek_tag , ber_skip_tag Target specific elements and tags. ber_set_option, ber_set_string_translators Set session parameters. ber_flatten, ber_printf , ber_read, ber_reset , ber_scanf, ber_sockbuf_get_option , ber_sockbuf_set_option, ber_start_seq, ber_start_seq, ber_start_set, ber_svecfree, ber_write Miscellaneous functions. C SDK functions for LDAP sessions The functions listed in Table 21–3 manage the different phases of an LDAP session: initialization, configuration, authentication (binding) and termination (unbinding). Function Description ldap_init, prldap_init (IPv6) Initializes an LDAP session. ldapssl_init Initializes an LDAP session over SSL. ldapssl_pkcs_init Initializes a thread-safe session over SSL. ldap_get_option, ldap_set_option Read and writes the current preference settings for a session. ldap_memcache_init, ldap_memcache_set, ldap_memcache_get , ldap_memcache_update, ldap_memcache_flush, ldap_memcache_destroy Creates a memory cache and uses it for search results from this session. Manages the data in the cache and frees the memory when the cache is no longer needed. The in-memory cache for search results is an extension to the API. ldap_unbind_ext Ends an LDAP session and frees the associated data structures. C SDK functions for LDAP operations The functions listed in Table 21–4 perform LDAP operations on a server and retrieve the results. Function Description ldap_add_ext or ldap_add_ext_s Adds a new entry to the directory. ldap_modify_ext or ldap_modify_ext_s Modifies an entry in the directory ldap_delete_ext or ldap_delete_ext_s Deletes an entry from the directory. ldap_rename orldap_rename_s Renames or moves one or more entries. ldap_search_ext or ldap_search_ext_s Searches the directory. ldap_compare_ext or ldap_compare_ext_s Compares a value with the values of an entry's attribute. ldap_result Checks the results of an asynchronous operation. ldap_abandon_ext Cancels an asynchronous operation. ldap_extended_operation or ldap_extended_operation_s Performs an LDAP v3 extended operation. ldap_parse_extended_result Parses the results of an LDAP v3 extended operation. ldap_msgfree Frees the memory used by the data structure for the results. ldap_simple_bind or ldap_simple_bind_s Authenticates to an LDAP server using a password. ldap_sasl_bind and ldap_parse_sasl_bind_result or ldap_sasl_bind_s Authenticates to an LDAP server using a SASL mechanism. ldap_set_rebind_proc Specifies the function used to get authentication information when following referrals. C SDK functions for search results processing 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 21–5 retrieve the results of a search operation and process the data structures which are returned. Function Description ldap_first_message Gets the first message (an entry or search reference) in a chain of search results. ldap_next_message Gets the next message (an entry or search reference) in a chain of search results. ldap_count_messages Counts the number of messages (entries and search references) in a chain of search results. ldap_msgid Gets the ID number of a message structure containing part of a result. ldap_msgtype Determines whether a message structure contains an entry or a search reference. ldap_msgfree Frees the memory allocated for search results or other LDAP operation results. ldap_first_entry Gets the first entry in a chain of search results. ldap_next_entry Gets the next entry in a chain of search results. ldap_count_entries Counts the number of entries in a chain of search results. ldap_first_reference Gets the first search reference in a chain of search results. ldap_next_reference Gets the next search reference in a chain of search results. ldap_count_references Counts the number of search references in a chain of search results. ldap_parse_reference Extracts the referral strings from a search reference. C SDK functions for reading entry contents The functions listed in Table 21–6 are used to access the contents of an entry returned as a search result. Function Description ldap_get_dn Get the DN for an entry. ldap_explode_dn ldap_explode_rdn Split a DN or relative DN into its components. ldap_explode_dns Takes a DNS-style DN and breaks it up into its components. ldap_is_dns_dn Determines the style of the DN. ldap_dn2ufn Removes cryptic type names to make a DN easier to read. ldap_first_attribute Get the name of the first attribute in an entry. ldap_next_attribute Get the name of the next attribute in an entry. ldap_get_values Get the string values of an attribute. ldap_get_values_len Get the binary values of an attribute. ldap_count_values Count the string values of an attribute. ldap_count_values_len Count the binary values of an attribute. ldap_value_free Free the memory allocated for the string values of an attribute. ldap_value_free_len Free the memory allocated for the binary values of an attribute. C SDK functions for sorting search results With the functions listed in Table 21–7, your LDAP client can sort the data structures returned as search results. Function Description ldap_sort_entries Sorts search results by DN or by a single attribute. ldap_multisort_entries Sorts search results by multiple attributes ldap_keysort_entries Sorts search results using key(s). ldap_sort_values Sorts the values of an attribute. ldap_sort_strcasecmp A case-insensitive comparison function that you can pass to ldap_sort_values. &cnDirectoryServer; and others also provide server-side sorting through LDAP v3 controls. Function Description ldap_create_sort_keylist Define the criteria for sorting entries by attribute values. ldap_free_sort_keylist Free the memory for the sort criteria data structure. ldap_create_sort_control Create the sort control structure needed for server-side sorting. ldap_control_free Free the memory for the sort control data structure. ldap_parse_sort_control Analyze the server’s response to the sort control. ldap_controls_free Free the memory for the sort control response data structure. C SDK functions for search filters The functions listed in Table 21–9 retrieve and build filters using a filter configuration file. Use this mechanism to create complex filters to pass to the search functions. Function Description ldap_init_getfilter Read a filter configuration file into memory. ldap_init_getfilter_buf Read a filter configuration string from a buffer. ldap_getfilter_free Free the filter configuration data structure from memory. ldap_set_filter_additions Specify the prefix and suffix to be added to all filters retrieved from the filter configuration. ldap_getfirstfilter Retrieve the first matching filter from the filter configuration. ldap_getnextfilter Retrieve the next matching filter from the filter configuration. ldap_create_filter Build a filter without using the filter configuration file mechanism. C SDK functions for LDAP v3 controls &cnDirectoryServer; and others also provide additional functionality through LDAP v3 controls. The functions listed in Table 21–10 configure LDAP v3 control structures which ask the server to perform advanced operations. Function Description ldap_create_authzid_control, ldap_parse_authzid_control Examine the authorization ID used for the operation. ldap_create_persistentsearch_control, ldap_get_entry_controls, ldap_parse_entrychange_control Track changes to an entry or a set of entries by setting the persistent search control and analyzing the entry change control sent by the server. ldap_create_proxiedauth_control Define a proxy authorization control to perform an operation under a different bind DN ldap_create_pwdpolicy_control , ldap_parse_pwdpolicy_control Examine password policy information for an entry. ldap_create_sort_keylist, ldap_free_sort_keylist, ldap_create_sort_control , ldap_parse_sort_control Define and send criteria for server-side sorting of search results and check the server’s response ldap_create_userstatus_control , ldap_parse_userstatus_control Examine account availability information for an entry. ldap_create_virtuallist_control, ldap_parse_virtuallist_control Use in conjunction with server-side sorting to limit and handle the number of results returned to the client. ldap_parse_result Parse an LDAP response from the server to extract the result and the response to the control. C SDK functions for parsing host lists The functions listed in Table 21–11 are utility functions for parsing space-separated host lists. This is useful for implementing an extended I/O CONNECT callback function. Function Description ldap_x_hostlist_first, ldap_x_hostlist_next, ldap_x_hostlist_status Utility functions for parsing space-separated host lists. C SDK functions for LDAP URLs The functions listed in Table 21–12 interpret LDAP URLs, universal resource locators of the form ldap://... . Function Description ldap_is_ldap_url Determine if a URL is an LDAP URL. ldap_url_parse Split up an LDAP URL into its components. ldap_url_search, ldap_url_search_s, ldap_url_search_st Perform the search specified by an LDAP URL. ldap_free_urldesc Free the memory allocated for a parsed URL. C SDK functions for UTF-8 encoding The functions listed in Table 21–13 work with strings and characters that use UTF-8 encoding. Function Description ldap_utf8len Function to determine byte length. ldap_utf8next Function to get next character. ldap_utf8prev Function to get previous character. ldap_utf8copy Function to copy a character to a destination. ldap_utf8characters Function to return the number of characters. ldap_utf8getcc Function moves the pointer to the next character following a UCS-4 character. ldap_utf8strtok_r Function moves the pointer to the next character following a UCS-4 character. ldap_utf8isalnum, ldap_utf8isalpha, ldap_utf8isdigit, ldap_utf8len, ldap_utf8isspace Functions to determine characteristics of the character. C SDK functions for error handling The functions listed in Table 21–14 handle errors returned by the functions. Chapter 22, Directory SDK for C Result Codes lists all of the error and status codes used in the &DirectorySDKForC;. You can also find details about possible errors in the reference section for each function. Function Description ldap_parse_result Get the error code resulting from an asynchronous LDAP operation. ldap_get_lderrno Get information about the last error that occurred. ldap_set_lderrno Set information about an error. ldap_err2string Get the error message for a specific error code. ldapssl_err2string Get the error message for a specific SSL error code. C SDK functions for memory management The functions listed in Table 21–15 free memory allocated by the &DirectorySDKForC; functions. Function Description ber_bvfree Free the memory allocated for a berval structure. ber_free Free the memory of a BerElement structure. ldap_control_free Free the memory of an LDAPControl structure. ldap_controls_free Free an array of LDAPControl structures. ldap_free_friendlymap Free the memory of a FriendlyMap structure ldap_free_sort_keylist Free an array of LDAPsortkey structures ldap_free_urldesc Free the memory of an LDAPURLDesc structure ldap_getfilter_free Free the memory of an LDAPFiltDesc structure. ldap_memfree General function for freeing memory of any other data structure ldap_mods_free Free an array of LDAPMod structure. ldap_msgfree Free the memory of an LDAPMessage structure. ldap_value_free Free the memory allocated for the string values of an attribute. ldap_value_free_len Free the memory allocated for the binary values of an attribute (an array of berval structures) You may also manage memory directly with the functions in Table 21–16. Function Description ldap_x_malloc Allocates memory. ldap_x_calloc Allocates memory for an array of elements. ldap_x_realloc Changes the size of a memory block. ldap_x_free Frees a block of memory. C SDK functions for NSPR The functions listed in Table 21–17 tie libldap into Netscape Portable Runtime, NSPR. Function Description prldap_get_default_socket_info Gets default socket information. prldap_get_session_info Gets application-specific data. prldap_get_session_option Gets a session option specific to the prldap layer. prldap_get_socket_info Gets socket information. prldap_init Creates a new NSPR session handle. prldap_install_routines Installs NSPR functions for use with LDAP handle. prldap_set_default_socket_info Sets default socket information. prldap_set_session_info Sets application-specific data. prldap_set_session_option Sets a session option specific to the prldap layer. prldap_set_socket_info Sets socket information. C SDK functions deprecated The functions listed in first column of Table 21–18 should no longer be used; they have been superseded by the newer functions listed in the second column. Deprecated functions are those being dropped from the standard or from extensions to &DirectorySDKForC;. Outdated functions are those which are not officially deprecated but which have newer, extended functions for performing the same operation. Deprecated functions are not guaranteed to be implemented in future versions of the API. However, all of these functions are still implemented in this version for backwards compatibility. For maintenance reasons, they have often been implemented to call the newer function which performs the same task. Deprecated Function Replacement ldap_ber_free Replaced by ber_free. ldap_bind, ldap_bind_s Replaced by ldap_simple_bind and ldap_simple_bind_s respectively. ldap_build_filter Replaced by ldap_create_filter. ldap_cache_flush Replaced by ldap_memcache_* functions. ldap_charray_add, ldap_charray_dup, ldap_charray_free, ldap_charray_inlist, ldap_charray_merge , ldap_charray_position, ldap_str2charray None documented to replace these character array functions. ldap_create_proxyauth_control Replaced by ldap_create_geteffectiveRights_control . ldap_get_lang_values, ldap_get_lang_values_len Rarely used, no replacement. ldap_modrdn Replaced by ldap_modrdn2, itself outdated by ldap_rename. ldap_modrdn_s Replaced by ldap_modrdn2_s, itself outdated by ldap_rename_s. ldap_open Replaced by ldap_init and one of the bind functions. ldap_result2error Replaced by ldap_parse_result. ldap_setfilteraffixes Replaced by ldap_set_filter_additions. ldap_ufn_search_c, ldap_ufn_search_ct, ldap_ufn_search_s , ldap_ufn_setfilter, ldap_ufn_setprefix, ldap_ufn_timeout None documented to replace these user-friendly search functions. ldap_version Replaced by ldap_get_option. C SDK functions outdated Many LDAP v2 functions are outdated now that LDAP v3 has been widely adopted. Table 21–19 lists both the outdated function and its new equivalent. Although LDAP v2 functions remain in the standard specification, you should use the LDAP v3 functions in any new client applications. Again, for maintenance reasons, the outdated functions have often been implemented to call the newer function. LDAP v2 Functions LDAP v3 Equivalent ldap_abandon ldap_abandon_ext ldap_add, ldap_add_s ldap_add_ext, ldap_add_ext_s ldap_compare, ldap_compare_s ldap_compare_ext, ldap_compare_ext_s ldap_delete, ldap_delete_s ldap_delete_ext, ldap_delete_ext_s ldap_modify, ldap_modify_s ldap_modify_ext, ldap_modify_ext_s ldap_modrdn2, ldap_modrdn2_s ldap_rename, ldap_rename_s ldap_search, ldap_search_s , ldap_search_st ldap_search_ext, ldap_search_ext_s, ldap_search_ext_s - use timeout argument ldap_unbind, ldap_unbind_s ldap_unbind_ext replaces both forms which are identical besides the suffix. C SDK functions alphabetically functions C SDK C SDK, functions The ber_alloc function is used to allocate a new Basic Encoding Rules (BER) BerElement structure. #include <lber.h> BerElement* ber_alloc( void ); This function has no parameters. If successful, a pointer to the newly allocated BerElement structure. If unsuccessful, a NULL pointer. ber_alloc is used to allocate a new BerElement structure for encoding data with the BER. ber_printf, BerElement The ber_alloc_t function constructs and returns a BerElement structure. #include <lber.h> BerElement* ber_alloc_t( int options ); 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. If successful, a pointer to the newly allocated BerElement structure. If unsuccessful, a NULL pointer. This function is the same as ber_alloc except it has an option. ber_printf, BerElement The ber_bvecfree function frees an array of berval structures. #include <lber.h> void ber_bvecfree( struct berval **bv ); Parameter Description bv Pointer to the array that you want to free from memory. Each berval in the array is freed using ber_bvfree, and then the array itself is freed. ber_bvfree The ber_bvdup function returns a copy of a berval structure. #include <lber.h> berval* ber_bvdup( const struct berval *bv ); Parameter Description bv Pointer to the berval structure to be duplicated. If successful, a pointer to the newly allocated berval structure. If unsuccessful, a NULL pointer. 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 . The ber_bvfree function frees a berval structure. #include <lber.h> void ber_bvfree( struct berval *bv ); Parameter Description bv Pointer to the berval structure that you want to free from memory. 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. ldap_extended_operation_s, ldap_parse_extended_result, ldap_sasl_bind_s , ldap_parse_sasl_bind_result The ber_dup function returns a copy of a BerElement structure. #include <lber.h> BerElement* ber_dup( BerElement *ber ); Parameter Description ber Pointer to the BerElement to be duplicated. If successful, a pointer to the newly allocated BerElement structure. If unsuccessful, a NULL pointer. The ber_dup function returns a copy of a BerElement structure. The ber_first_element function is used to return the tag and length of the first element in a set or sequence. #include <lber.h> unsigned long ber_first_element( BerElement *ber, unsigned long *len, char **last ); 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. NULL pointer is returned on error. 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 . ber_next_element The ber_flatten function allocates a berval structure whose contents are taken from a source BerElement structure. #include <lber.h> int ber_flatten( BerElement *ber, struct berval **bvPtr ); Parameter Description ber Pointer to the source BerElement. bvPtr Pointer to the newly allocated berval structure which must be freed using ber_bvfree. Returns 0 on success and -1 on error. This function is usually used when encoding LDAP v3 controls or extended operations values. ber_bvfree 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. #include <ldap.h> void ber_free( BerElement *ber, int freebuf ); 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. 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. 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 21–1 frees the BerElement structure allocated by the ldap_first_attribute function. LDAP *ld; LDAPMessage *a, *e; BerElement *ber; ... for ( a = ldap_first_attribute( ld, e, &ber ); a != NULL; a =ldap_next_attribute( ld, e, ber ) { ... /* Retrieve the value of each attribute */ ... } /* Free the BerElement when done */ if ( ber != NULL ) { ber_free( ber, 0 ); } ... ber_alloc, ber_alloc_t , ber_init, ldap_first_attribute , ldap_next_attribute The ber_get_boolean function is used to read a boolean value. #include <lber.h> unsigned long ber_get_boolean( BerElement *ber, int *boolval ); Parameter Description ber Pointer to the BerElement structure that contains the boolean. boolval Specifies the boolean to read. The value is returned on success and LBER_ERROR ( -1) on failure. The ber_get_int function tries to interpret the next element as an integer, returning the result in num. #include <lber.h> unsigned long ber_get_int( BerElement *ber, int *num ); Parameter Description ber Pointer to the BerElement structure that contains the boolean. num Pointer to the result. The tag of whatever it finds is returned on success and LBER_ERROR (-1) on failure. The ber_get_next function reads the next BER element. #include <lber.h> unsigned long ber_get_next( Sockbuf *sb, unsigned long *len, BerElement *ber ); 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. 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. The ber_get_next_buffer function reads the next BER element from a byte buffer. 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. The ber_get_next_buffer_ext function reads the next BER element from a byte buffer. 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 . #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 ); 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. The ber_get_null function is used to read a NULL element. #include <lber.h> unsigned long ber_get_null( BerElement *ber ); Parameter Description ber Pointer to a BerElement. Returns the tag of the element it skips over. The ber_get_option function is used to retrieve information about the API and about the specific implementation being used. #include <lber.h> int ber_get_option( BerElement *ber, int option, void *value ); The ber_get_stringa function is used to allocate memory space into which an octet string is read. #include <lber.h> unsigned long ber_get_stringa( BerElement *ber, char **buf ); The ber_get_stringal function is used to allocate memory space into which an octet string and its length are read. #include <lber.h> unsigned long ber_get_stringal( BerElement *ber, struct berval **bv ); It takes a berval structure, and returns the result in this parameter. The ber_get_stringb function is used to read an octet string into a preallocated buffer. #include <lber.h> unsigned long ber_get_stringb( BerElement *ber, char *buf, unsigned long *len ); 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. The ber_init function constructs a new BerElement. #include <lber.h> BerElement * ber_init( const struct berval *bv ); Parameter Description bv Pointer to a berval. If successful, returns a new BerElement containing a copy of the data in the bv argument. If not, returns a NULL pointer. The ber_init_w_nullchar function constructs a new BerElement with a NULL character. #include <lber.h> void ber_init_w_nullchar( BerElement *ber, int options ); The ber_next_element function is used to return the tag and length of the next element in a set or sequence. #include <lber.h> unsigned long ber_next_element( BerElement *ber, unsigned long *len, char *last ); 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. NULL pointer is returned on error. The ber_next_element function is used to return the tag and length of the first element in a set or sequence. ber_first_element The ber_peek_tag function returns the tag of the next element to be parsed in the supplied BerElement structure. #include <lber.h> unsigned long ber_peek_tag( BerElement *ber, unsigned long *len ); 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 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. The ber_printf function encodes a BER element. #include <lber.h> ber_printf( BerElement *ber, const char *fmt, ... ); 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. 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 . -1 if there is an error during encoding. The ber_put_bitstring function writes a bitstring value to the given BerElement. #include <lber.h> int ber_put_bitstring( BerElement *ber, char *str, unsigned long bitlen, unsigned long tag ); The ber_put_bitstring function writes bitlen bits starting at str as a bitstring value to the given BerElement. The ber_put_boolean function writes a boolean value to a BerElement. #include <lber.h> int ber_put_boolean( BerElement *ber, int boolval, unsigned long tag ); The boolean value is given by boolval to the BerElement. The ber_put_enum function writes an enumerated value to a BerElement. #include <lber.h> int ber_put_enum( BerElement *ber, long num, unsigned long tag ); The ber_put_int function writes an integer to a BerElement. #include <lber.h> int ber_put_int( BerElement *ber, long num, unsigned long tag ); The ber_put_null function writes a writes a NULL element to a BerElement. #include <lber.h> int ber_put_null( BerElement *ber, unsigned long tag ); The ber_put_ostring function writes bytes to a BerElement as an octet string. #include <lber.h> int ber_put_ostring( BerElement *ber, char *str, unsigned long len, unsigned long tag ); The ber_put_seq function puts a sequence to a BerElement. #include <lber.h> int ber_put_seq( BerElement *ber ); Parameter Description ber Pointer to a BerElement. 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 . The ber_put_set function puts a set to a BerElement. #include <lber.h> int ber_put_set( BerElement *ber ); Parameter Description ber Pointer to a BerElement. 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. The ber_put_string function writes a NULL terminated string (minus the terminating 0) to a BerElement as an octet string. #include <lber.h> int ber_put_string( BerElement *ber, char *str, unsigned long tag ); #include <lber.h> long ber_read( BerElement *ber, char *buf, unsigned long len ); #include <lber.h> void ber_reset( BerElement *ber, int was_writing ); The ber_scanf function decodes a BerElement. #include <lber.h> unsigned long ber_scanf( BerElement *ber, const char *fmt, ... ); 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. fmt (continued) -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. 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. ber_printf #include <lber.h> int ber_set_option( BerElement *ber, int option, void *value ); #include <lber.h> unsigned long ber_skip_tag( BerElement *ber, unsigned long *len ); The ber_skip_tag function advances the pointer to a BerElement past the first tag and length to the next tag. #include <lber.h> unsigned long ber_skip_tag( BerElement *ber, unsigned long *len ); Parameter Description ber Pointer to a BerElement. len Pointer to the length of the value to be skipped. 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. ber_peek_tag #include <lber.h> Sockbuf* ber_sockbuf_alloc( void ); #include <lber.h> void ber_sockbuf_free( Sockbuf* p ); #include <lber.h> void ber_sockbuf_free_data(Sockbuf *p); #include <lber.h> int ber_sockbuf_get_option( Sockbuf *sb, int option, void *value ); #include <lber.h> int ber_sockbuf_set_option( Sockbuf *sb, int option, void *value ); The ber_special_alloc function allocates a BerElement structure plus some extra memory. #include <lber.h> void* ber_special_alloc( size_t size, BerElement **ppBer ); Returns a pointer to the BerElement and a pointer to the extra memory. ber_special_alloc allocates a ber data buffer within the same block, thus saving a call to calloc later when we read data. The ber_special_free function frees an allocated BerElement structure. #include <lber.h> void ber_special_free( void* buf, BerElement *ber ); ber_special_alloc #include <lber.h> int) LDAP_CALL ber_stack_init(BerElement *ber, int options, char * buf, size_t size); The ber_start_seq function is used to start a sequence in a BerElement. #include <lber.h> int ber_start_seq( BerElement *ber, unsigned long tag ); ber_put_seq The ber_start_seq function is used to start a set in a BerElement. #include <lber.h> int ber_start_set( BerElement *ber, unsigned long tag ); ber_put_set #include <lber.h> void ber_svecfree( char **vals ); #include <lber.h> long ber_write( BerElement *ber, char *buf, unsigned long len, int nosos ); The ldap_abandon function cancels an asynchronous LDAP operation that is in progress. 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. #include <ldap.h> int ldap_abandon( LDAP *ld, int msgid ); Parameter Description ld Pointer to an LDAP structure containing information about the connection to the LDAP server. msgid Message ID of an LDAP operation. One of the following values: LDAP_SUCCESS if successful. -1 if unsuccessful. The appropriate LDAP error code is also set in the LDAP structure. You can retrieve the error code by calling 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. Please use the newer version of this function, ldap_abandon_ext . Example 21–2 cancels an ldap_url_search operation, abandoning the results of the operation. LDAP *ld; char *url = "ldap://ldap.example.com/c=US?o,description?one?o=sales"; int msgid; ... /* Initiate a search operation */ msgid = ldap_url_search( ld, url, 0 ); ... /* Abandon the search operation */ if ( ldap_abandon( ld, msgid ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldap_abandon" ); return( 1 ); } ... ldap_abandon_ext The ldap_abandon_ext function cancels an asynchronous LDAP operation that is in progress. ldap_abandon_ext is a new version of the ldap_abandon function. If you are writing a new LDAP client, use ldap_abandon_ext. #include <ldap.h> int ldap_abandon_ext( LDAP *ld, int msgid, LDAPControl **serverctrls, LDAPControl **clientctrls ); 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. 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. The ldap_abandon_ext function cancels an asynchronous LDAP operation that is in progress. For example, if you called ldap_search_ext to initiate an LDAP search operation on the server, you can call ldap_abandon_ext to cancel it. When you call ldap_abandon_ext, the function checks to see if the results of the operation have already been returned. If so, ldap_abandon_ext deletes the message ID from the queue of pending messages. If the results have not been returned, ldap_abandon_ext sends a request to abandon the operation. Once cancelled, the results of the operation will not be returned, even if you subsequently call ldap_result to retrieve them. To identify the operation to be cancelled, specify the message ID of the operation in the msgid argument of the ldap_abandon_ext function. Example 21–3 cancels an ldap_url_search operation, abandoning the results of the operation. LDAP *ld; char *url = "ldap://ldap.example.com/c=US?o,description?one?o=sales"; int msgid; 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 ); } ... 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 The ldap_add function adds a new entry to the directory asynchronously. 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. #include <ldap.h> int ldap_add( LDAP *ld, const char *dn, LDAPMod **attrs ); 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. The message ID of the ldap_add operation. 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. Please use the newer version of this function, ldap_add_ext . Example 21–4 adds a new entry to the directory. #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 )); } ... ldap_add_ext The ldap_add_ext function adds a new entry to the directory asynchronously. ldap_add_ext is a new version of the ldap_add function. If you are writing a new LDAP client, use ldap_add_ext. #include <ldap.h> int ldap_add_ext( LDAP *ld, const char *dn, LDAPMod **attrs, LDAPControl **serverctrls, LDAPControl **clientctrls, int *msgidp ); 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. One of the following values: LDAP_SUCCESS if successful. LDAP_PARAM_ERROR if any of the arguments are invalid. LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request. LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost. LDAP_NO_MEMORY if memory cannot be allocated. LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function. The ldap_add_ext adds a new entry to the directory. To add a new entry to the directory, you need to specify: A unique DN identifying the new entry.Use the dn argument to specify the DN of the new entry. The parents of the entry should already exist. For example, if you are adding the entry uid=bjensen,ou=People,dc=example,dc=com , the entries ou=People and dc=example,dc=com must already exist in the directory. A set of attributes for the new entry.Create an LDAPMod structure for each attribute. Set the mod_op field to 0 if the attribute values are string values. To specify values that consist of binary data (such as a sound file or a JPEG file), set the mod_op field to LDAP_MOD_BVALUES. Create an array of these LDAPMod structures and pass the array as the attrs argument. ldap_add_ext is an asynchronous function; it does not directly return results. In order to get the results of the asynchronous operation, you need to call the ldap_result and ldap_parse_result functions. If you want the results to be returned directly by the function, call the synchronous function ldap_add_ext_s. For a list of possible result codes for an LDAP add operation, see the ldap_add_ext_s function. ldap_add_ext_s, ldap_result, ldap_parse_result, LDAPMod The ldap_add_ext_s function adds a new entry to the directory synchronously. 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. #include <ldap.h> int ldap_add_ext_s( LDAP *ld, const char *dn, LDAPMod **attrs, LDAPControl **serverctrls, LDAPControl **clientctrls ); 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. One of the following values: LDAP_SUCCESS if successful. LDAP_PARAM_ERROR if any of the arguments are invalid. LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request. LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost. LDAP_NO_MEMORY if memory cannot be allocated. LDAP_LOCAL_ERROR if an error occurred when receiving the results from the server. LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded results from the server. LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function. &cnDirectoryServer; and other LDAP server products may send result codes in addition to those described. For example, the server may have loaded a plug-in that returns custom result codes. Check your LDAP server documentation for other result codes. 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. ldap_add_ext, LDAPMod The ldap_add_s function adds a new entry to the directory synchronously. 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. #include <ldap.h> int ldap_add_s( LDAP *ld, const char *dn, LDAPMod **attrs ); 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. See ldap_add_ext_s for a list of possible return codes. Please use the newer version of this function, ldap_add_ext_s . Example 21–5 adds a new entry to the directory. #include <ldap.h> ... LDAP *ld; LDAPMod *list_of_attrs[4]; LDAPMod attribute1, attribute2, attribute3; /* Distinguished name of the new entry. Note that "dc=example,dc=com" and "ou=People,dc=example,dc=com" must already exist in the directory. */ char *dn = "uid=bjensen,ou=People,dc=example, dc=com"; /* To add a "person" entry, you must specify values for the sn, cn, and objectClass attributes. (These are required attributes.) */ char *sn_values[] = { "Jensen", NULL }; /* To specify multiple values for an attribute, add the different values to the array. */ char *cn_values[] = { "Barbara Jensen", "Babs Jensen", NULL }; /* The object class for a "person" entry is "inetOrgPerson", which is a * subclass of "top", "person", and "organizationalPerson". You should add * all of these classes as values of the objectClass attribute. */ char *objectClass_values[] = { "top", "person", "organizationalPerson", "inetOrgPerson", NULL }; ... /* Specify the value and type of each attribute in separate LDAPMod structures */ attribute1.mod_type = "sn"; attribute1.mod_values = sn_values; attribute2.mod_type = "cn"; attribute2.mod_values = cn_values; attribute3.mod_type = "objectClass"; attribute3.mod_values = objectClass_values; /* Add the pointers to these LDAPMod structures to an array */ list_of_attrs[0] = &attribute1; list_of_attrs[1] = &attribute2; list_of_attrs[2] = &attribute3; list_of_attrs[3] = NULL; ... /* Add the user "Barbara Jensen" */ if ( ldap_add_s( ld, dn, list_of_attrs ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldap_add_s" ); return( 1 ); } ... ldap_add_ext_s The ldap_ber_free function frees a BerElement structure from memory. 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. #include <ldap.h> void ldap_ber_free( BerElement *ber, int freebuf ); 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. Please use the newer version of this function, ber_free . ber_free This function is deprecated and should not be used. It is included in ldap-deprecated.h for backward-compatibility. Use ldap_simple_bind instead. ldap_bind can be used when the authentication method being used needs to be selected at runtime. #include <ldap-deprecated.h> ldap_bind( LDAP *ld, const char *who, const char *passwd, int method ); 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. ldap_bind returns the message ID of the request it initiates. This is an asynchronous function that authenticates a specified entry to the directory. After a connection is made to an LDAP server using ldap_open, a bind operation must be performed before other operations can be attempted over the connection. ldap_open, ldap_init , prldap_init (IPv6), ldap_bind_s This function is deprecated and should not be used. It is included in ldap-deprecated.h for backward-compatibility. Use ldap_simple_bind_s instead. ldap_bind_s can be used when the authentication method needs to be selected at runtime. #include <ldap-deprecated.h> ldap_bind_s( LDAP *ld, const char *who, const char *cred, int method ); 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. ldap_bind_s returns an LDAP error indication. This is a synchronous function that authenticates a specified entry to the directory. After a connection is made to an LDAP server using ldap_open , a bind operation must be performed before other operations can be attempted over the connection. ldap_open, ldap_init , prldap_init (IPv6), ldap_bind This function is deprecated and should not be used. It is included in ldap-deprecated.h for backward-compatibility. Use ldap_create_filter instead. ldap_create_filter This function is deprecated and should not be used. It is included in ldap-deprecated.h for backward-compatibility. Use the ldap_memcache_* functions instead. For more specific information, see the header file ldap-deprecated.h . ldap_memcache_init, ldap_memcache_set, ldap_memcache_get , ldap_memcache_update, ldap_memcache_flush , ldap_memcache_destroy 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 . 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 . 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 . 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 . 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 . 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 . The ldap_compare function asynchronously determines if an attribute of an entry contains a specified value. 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. #include <ldap.h> int ldap_compare( LDAP *ld, const char *dn, const char *attr, const char *value ); 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 the message ID of the ldap_compare operation. 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. Please use the newer version of this function, ldap_compare_ext . Example 21–6 checks to see if Barbara Jensen has the email address bjensen@example.com. #include <stdio.h> #include <ldap.h> ... LDAP *ld; char *dn = "uid=bjensen,ou=People,dc=example, dc=com"; int msgid; ... msg_id = ldap_compare( ld, dn, "mail", "bjensen@example.com" ); ... ldap_compare_ext The ldap_compare_ext function asynchronously determines if an attribute of an entry contains a specified value. ldap_compare_ext is a new version of the ldap_compare function. If you are writing a new LDAP client, use ldap_compare_ext. #include <ldap.h> int ldap_compare_ext( LDAP *ld, const char *dn, const char *attr, struct berval *bvalue, LDAPControl **serverctrls, LDAPControl **clientctrls, int *msgidp ); 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. One of the following values: LDAP_SUCCESS if successful. LDAP_PARAM_ERROR if any of the arguments are invalid. LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request. LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost. LDAP_NO_MEMORY if memory cannot be allocated. LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function. To check the result of this operation, call ldap_result and ldap_parse_result. For a list of the possible result codes for an LDAP compare operation, see ldap_compare_ext_s. 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. ldap_compare_ext_s, ldap_result, ldap_parse_result The ldap_compare_ext_s function synchronously determines if an attribute of an entry contains a specified value. #include <ldap.h> int ldap_compare_ext_s( LDAP *ld, const char *dn, const char *attr, struct berval *bvalue, LDAPControl **serverctrls, LDAPControl **clientctrls ); 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. One of the following values: LDAP_COMPARE_TRUE if the entry contains the attribute value. LDAP_COMPARE_FALSE if the entry does not contain the attribute value. LDAP_PARAM_ERROR if any of the arguments are invalid. LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request. LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost. LDAP_NO_MEMORY if memory cannot be allocated. LDAP_LOCAL_ERROR if an error occurred when receiving the results from the server. LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded results from the server. LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function. &cnDirectoryServer; and other LDAP server products may send result codes in addition to those described. For example, the server may have loaded a plug-in that returns custom result codes. Check your LDAP server documentation for other result codes. 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. ldap_compare_ext The ldap_compare_s function synchronously determines if an attribute of an entry contains a specified value. 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. #include <ldap.h> int ldap_compare_s( LDAP *ld, const char *dn, const char *attr, const char *value ); 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. For a list of the possible result codes for an LDAP compare operation, see ldap_compare_ext_s. Please use the newer version of this function, ldap_compare_ext_s . Example 21–7 checks to see if Barbara Jensen has the email address bjensen@example.com. #include <stdio.h> #include <ldap.h> LDAP *ld; char *dn = "uid=bjensen,ou=People,dc=example, dc=com"; int has_value; ... has_value = ldap_compare_s( ld, dn, "mail", "bjensen@example.com" ); switch ( has_value ) { case LDAP_COMPARE_TRUE: printf( "The mail attribute contains bjensen@example.com.\n"); break; case LDAP_COMPARE_FALSE: printf( "The mail attribute does not contain bjensen@example.com.\n"); break; default: ldap_perror( ld, "ldap_compare_s" ); return( 1 ); } ... ldap_compare_ext_s The ldap_control_free function frees an LDAPControl structure from memory. #include <ldap.h> void ldap_control_free( LDAPControl *ctrl ); Parameter Description ctrl Pointer to an LDAPControl structure that you want to free from memory. 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. ldap_controls_free The ldap_controls_free function frees an array of LDAPControl structures from memory. #include <ldap.h> void ldap_controls_free( LDAPControl **ctrls ); Parameter Description ctrls Pointer to an array of LDAPControl structures that you want to free from memory. 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. ldap_control_free, ldap_parse_result The ldap_count_entries function returns the number of LDAPMessage structures representing directory entries in a chain of search results. #include <ldap.h> int ldap_count_entries( LDAP *ld, LDAPMessage *result ); 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. 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. 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 . 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. See the examples under ldap_search_ext and ldap_search_ext_s. ldap_result, ldap_search_ext , ldap_search_ext_s, ldap_first_entry, ldap_next_entry , ldap_first_entry, ldap_next_message The ldap_count_messages function returns the number of LDAPMessage structures in a chain of search results. #include <ldap.h> int ldap_count_messages( LDAP *ld, LDAPMessage *res ); 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. 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. 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. 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. See the examples under ldap_search_ext and ldap_search_ext_s. 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 The ldap_count_references function returns the number of LDAPMessage structures representing search references in a chain of search results. #include <ldap.h> int ldap_count_references( LDAP *ld, LDAPMessage *res ); 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. 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. The ldap_count_references function returns the number of LDAPMessage structures representing search references in a chain of search results. These messages have the type LDAP_RES_SEARCH_REFERENCE, continuation references as specified in LDAPv3 that are stored as referral entries. Like a referral, each continuation reference itself may contain a number of URLs assumed to be equivalent, and the client should use one of those URLs. 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. See the examples under ldap_search_ext and ldap_search_ext_s. ldap_result, ldap_search_ext , ldap_search_ext_s, ldap_first_reference, ldap_next_reference The ldap_count_values function returns the number of values in an array of strings. Use the ldap_count_values_len function if the array contains berval structures. #include <ldap.h> int ldap_count_values( char **values ); Parameter Description values Array of values. One of the following values: The number of values in the array, if successful. -1 if unsuccessful. Example 21–8 counts the number of values assigned to an attribute. #include <ldap.h> ... LDAP *ld; LDAPMessage *e; char *a="cn"; char **vals; int count; ... /* Get the values of the cn attribute */ vals = ldap_get_values( ld, e, a ); /* Count the values of the attribute */ count = ldap_count_values( vals ); ... ldap_count_values_len, ldap_get_values The ldap_count_values_len function returns the number of values in an array of berval structures. Use the ldap_count_values function if the array contains strings. #include <ldap.h> int ldap_count_values_len( struct berval **vals ); Parameter Description values Array of berval structures. One of the following values: The number of values in the array, if successful. -1 if unsuccessful. Example 21–9 counts the number of values assigned to an attribute. #include <ldap.h> LDAP *ld; LDAPMessage *e; char *a="jpegPhoto"; struct berval **bvals; int count; ... /* Get the values of the jpegPhoto attribute */ bvals = ldap_get_values_len( ld, e, a ); /* Count the values of the attribute */ count = ldap_count_values_len( vals ); ... ldap_count_values, ldap_get_values_len The ldap_create_authzid_control function creates a control that requests the authorization ID for a bind operation. This is defined in RFC 3829. In order for the control to work, the LDAP server that you are connecting to must support the server controls for authorization bind identity (OID 2.16.840.1.113730.3.4.16 or LDAP_CONTROL_AUTHZID_REQ , and OID 2.16.840.1.113730.3.4.15 or LDAP_CONTROL_AUTHZID_RES ). Calling ldap_create_authzid_control creates an LDAP control that you can pass to the ldap_simple_bind function to retrieve the authorization ID in the response. You call ldap_parse_authzid_control function on the controls returned with an entry to retrieve a char * containing the authorization ID. When you are done with the search, you should free the control by calling the ldap_control_free function. #include <ldap.h> LDAP_API(int) LDAP_CALL ldap_create_authzid_control( LDAP *ld, const char ctl_iscritical, LDAPControl **ctrlp ); Parameter Description ld Pointer to an LDAP structure containing information about the connection to the LDAP server. ctl_iscritical Specifies whether the control is critical to the operation. If non-zero, the control is critical to the operation. If the server does not support it, the server returns an LDAP_UNAVAILABLE_CRITICAL_EXTENSION error. If 0, the control is not critical to the operation. Even if the server does not support the control, the operation is still attempted and the control is ignored. ctrlp Pointer to an LDAPControl structure created by this function. When you are done using this control, you should free it by calling ldap_control_free. 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_parse_authzid_control The ldap_create_filter routine constructs an LDAP search filter. #include <ldap.h> int ldap_create_filter( char *buf, unsigned long buflen, char *pattern, char *prefix, char *suffix, char *attr, char *value, char **valwords ); 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. One of the following values: LDAP_SUCCESS if successful. LDAP_SIZELIMIT_EXCEEDED if the created filter exceeds the size of the buffer. LDAP_PARAM_ERROR if an invalid parameter was passed to the function. Example 21–10 builds the filter (mail=bjensen@example.com). char buf[LDAP_FILT_MAXSIZ]; char *pattern = "(%a=%v)"; char *attr = "mail"; char *value = "bjensen@example.com"; ... ldap_create_filter( buf, LDAP_FILT_MAXSIZ, pattern, NULL, NULL, attr, value, NULL ); ... ldap_init_getfilter, ldap_init_getfilter_buf, ldap_getfirstfilter , ldap_getnextfilter, ldap_set_filter_additions The ldap_create_geteffectiveRights_control function allows a user having correct privileges to query about the access rights another identity has on one or more entries in the directory. #include <ldap.h> LDAP_API(int) LDAP_CALL ldap_create_geteffectiveRights_control( LDAP *ld, const char *authzid, const char **attrlist, const char ctl_iscritical, LDAPControl **ctrlp ); Parameter Description ld Pointer to an LDAP structure containing information about the connection to the LDAP server. authzid The DN of the identity for which you are checking access rights. attrlist List of attributes to return, such as aclRights and aclRightsInfo. ctl_iscritical Specifies whether the control is critical to the operation. If non-zero, the control is critical to the operation. If the server does not support it, the server will return an LDAP_UNAVAILABLE_CRITICAL_EXTENSION error. If 0, the control is not critical to the operation. Even if the server does not support the control, the operation is still attempted and the control is ignored. ctrlp Pointer to an LDAPControl structure created by this function. When you are done using this control, you should free it by calling ldap_control_free. 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. 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). #include <ldap.h> int ldap_create_persistentsearch_control( LDAP *ld, int changetypes, int changesonly, int return_echg_ctls, char ctl_iscritical, LDAPControl **ctrlp ); Parameter Description ld Pointer to an LDAP structure containing information about the connection to the LDAP server. changetypes Specifies the types of changes that you want to keep track of. This field can have one or more of the following values: LDAP_CHANGETYPE_ADD specifies that you want to keep track of entries added to the directory. LDAP_CHANGETYPE_DELETE specifies that you want to keep track of entries deleted from the directory. LDAP_CHANGETYPE_MODIFY specifies that you want to keep track of entries that are modified. LDAP_CHANGETYPE_MODDN specifies that you want to keep track of entries that are renamed. LDAP_CHANGETYPE_ANY specifies that you want to keep track of all of the above changes to the directory.You can OR the values together to specify multiple types. changesonly Specifies whether or not you want skip the initial search and only get the latest changes as they occur: If non-zero, the initial search is skipped and only entries that have changed after the initial search are returned. If 0, the results of the initial search are returned first. return_echg_ctls Specifies whether or not entry controls are included with each entry returned to your client: If non-zero, a control is included with each entry. If 0, controls are not included with the entries returned from the server. ctl_iscritical Specifies whether the control is critical to the operation. If non-zero, the control is critical to the operation. If the server does not support it, the server will return an LDAP_UNAVAILABLE_CRITICAL_EXTENSION error. If 0, the control is not critical to the operation. Even if the server does not support the control, the operation is still attempted and the control is ignored. ctrlp Pointer to an LDAPControl structure created by this function. When you are done using this control, you should free it by calling ldap_control_free. 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. 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. ldap_search_ext, ldap_abandon_ext, ldap_get_entry_controls, ldap_parse_entrychange_control, ldap_control_free The ldap_create_pwdpolicy_control function creates a control that requests information about the status of a user account. ldap_create_pwdpolicy_control implements an extension to the LDAP v3 supported by &cnDirectoryServer;.In order for the control to work, the LDAP server that you are connecting to must support the server control for password policy (OID 1.3.6.1.4.1.42.2.27.8.5.1 , or LDAP_CONTROL_ACCOUNT_USABLE). Calling ldap_create_pwdpolicy_control creates an LDAP control that you can pass to the ldap_simple_bind functions to retrieve password policy information from bind, modify, add, compare, and potentially extended operation responses including password policy response controls. You call ldap_parse_pwdpolicy_control function on the controls returned with an entry to retrieve a LDAPpwdpolicy structure containing information about the status of the account. When you are done with the search, you should free the control by calling the ldap_control_free function. #include <ldap.h> LDAP_API(int) LDAP_CALL ldap_create_pwdpolicy_control( LDAP *ld, const char ctl_iscritical, LDAPControl **ctrlp ); Parameter Description ld Pointer to an LDAP structure containing information about the connection to the LDAP server. ctl_iscritical Specifies whether the control is critical to the operation. If non-zero, the control is critical to the operation. If the server does not support it, the server returns an LDAP_UNAVAILABLE_CRITICAL_EXTENSION error. If 0, the control is not critical to the operation. Even if the server does not support the control, the operation is still attempted and the control is ignored. ctrlp Pointer to an LDAPControl structure created by this function. When you are done using this control, you should free it by calling ldap_control_free. 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_parse_pwdpolicy_control , LDAPpwdpolicy The ldap_create_proxiedauth_control function creates an LDAP v3 control that allows a bound entity to assume the identity of another directory entry. 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 . #include <ldap.h> int ldap_create_proxiedauth_control( LDAP *ld, char *authzid, LDAPControl **ctrlp); Parameter Description ld Pointer to an LDAP structure containing information about the connection to the LDAP server. authzid The string representing the identity to assume for the access rights, defined in the format specified by the following Augmented Backus-Naur Form (ABNF) from RFC 4513: ; Specific predefined authorization (authz) ; id schemes are defined below -- ; new schemes may be defined in the future. authzId = dnAuthzId / uAuthzId ; distinguished-name-based authz id. dnAuthzId = "dn:" dn dn = utf8string ; syntax from RFC 4514 ; unspecified userid, UTF-8 encoded. uAuthzId = "u:" userid userid = utf8string ; syntax unspecified ctrlp Pointer to an LDAPControl structure created by this function. When you are done using this control, you should free it by calling ldap_control_free. More information on proxy authorization can be found in the LDAP Proxied Authorization Control Internet Draft (). 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). The ldap_create_proxyauth_control function creates an LDAP v3 control that allows a bound entity to assume the identity of another directory entry. 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 . #include <ldap.h> int ldap_create_proxyauth_control( LDAP *ld, char *DN, char ctl_iscritical, LDAPControl **ctrlp); 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. One of the following values: LDAP_SUCCESS if successful. LDAP_PARAM_ERROR if an invalid parameter was passed to the function. LDAP_NO_MEMORY if memory cannot be allocated. LDAP_ENCODING_ERROR if an error occurred when BER-encoding the control. LDAP_UNAVAILABLE_CRITICAL_EXTENSION if the server does not support proxy authorization and ctl_iscritical is set to a non-zero value. ldap_control_free The ldap_create_sort_control function creates a control that specifies the order in which you want search results returned. This function implements an extension to the LDAP v3. Server-side sorting is an optional feature; it may not be supported on all LDAP servers. Call this function when interacting with LDAP servers that support this LDAP v3 extension. #include <ldap.h> int ldap_create_sort_control( LDAP *ld, LDAPsortkey **sortKeyList, const char ctl_iscritical, LDAPControl **ctrlp ); 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. 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. The ldap_create_sort_control function allows you to specify the order in which you want to receive data from the server. Calling this function creates an LDAP control that you can pass to the ldap_search_ext and ldap_search_ext_s functions. In order for the control to work, the LDAP server that you are connecting to must support the server control for sorting search results (OID 1.2.840.113556.1.4.473, or LDAP_CONTROL_SORTREQUEST, as defined in the ldap.h header file). 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. ldap_create_sort_keylist, ldap_search_ext, ldap_search_ext_s , ldap_control_free The ldap_create_sort_keylist function creates an array of LDAPsortkey structures from a string representation of a set of sort keys. #include <ldap.h> int ldap_create_sort_keylist(LDAPsortkey ***sortKeyList, const char *string_rep); Parameter Description sortKeyList Pointer to an array of LDAPsortkey structures that specify the attribute types or matching rules used for sorting and the order (ascending or descending) in which to sort the results. string_rep String representation of a set of sort keys. The value should specify the name of the attribute that you want to sort by. To sort in reverse order, precede the attribute name with a hyphen, -. To use a matching rule for sorting, append a colon to the attribute name and specify the object identifier (OID) of a matching rule after the colon. For example: cn (sorts by the cn attribute) -cn (sorts by the cn attribute in reverse order) -cn:1.2.3.4 (sorts by the cn attribute in reverse order using the matching rule identified by the OID 1.2.3.4) 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. 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. ldap_create_sort_control, ldap_free_sort_keylist The ldap_create_userstatus_control function creates a control that requests information about the status of a user account. ldap_create_userstatus_control implements an extension to the LDAP v3 supported by &cnDirectoryServer;.In order for the control to work, the LDAP server that you are connecting to must support the server control for account availability (OID 1.3.6.1.4.1.42.2.27.9.5.8 , or LDAP_CONTROL_ACCOUNT_USABLE). Calling ldap_create_userstatus_control creates an LDAP control that you can pass to the ldap_search_ext and ldap_search_ext_s functions. You call ldap_parse_userstatus_control function on the controls returned with an entry to retrieve a LDAPuserstatus structure containing information about the status of the account. When you are done with the search, you should free the control by calling the ldap_control_free function. #include <ldap.h> LDAP_API(int) LDAP_CALL ldap_create_userstatus_control( LDAP *ld, const char ctl_iscritical, LDAPControl **ctrlp ); Parameter Description ld Pointer to an LDAP structure containing information about the connection to the LDAP server. ctl_iscritical Specifies whether the control is critical to the operation. If non-zero, the control is critical to the operation. If the server does not support it, the server returns an LDAP_UNAVAILABLE_CRITICAL_EXTENSION error. If 0, the control is not critical to the operation. Even if the server does not support the control, the operation is still attempted and the control is ignored. ctrlp Pointer to an LDAPControl structure created by this function. When you are done using this control, you should free it by calling ldap_control_free. 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_parse_userstatus_control , LDAPuserstatus The ldap_create_virtuallist_control function creates a control that requests a subset of search results for use in a virtual list box. ldap_create_virtuallist_control implements an extension to the LDAP v3 supported by &cnDirectoryServer;. #include <ldap.h> int ldap_create_virtuallist_control( LDAP *ld, LDAPVirtualList *ldvlistp, LDAPControl **ctrlp ); 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. 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. 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. In order for the control to work, the LDAP server that you are connecting to must support the server control for sorting search results (OID 2.16.840.1.113730.3.4.9, or LDAP_CONTROL_VLVREQUEST, as defined in the ldap.h header file). Calling ldap_create_virtuallist_control creates an LDAP control that you can pass to the ldap_search_ext and ldap_search_ext_s functions. You also need to pass a server-side sorting control to the search functions. You can call ldap_create_sort_keylist and ldap_create_sort_control to create a server-side sorting control. When you are done with the search, you should free the control by calling the ldap_control_free function. LDAPVirtualList, ldap_parse_virtuallist_control, ldap_search_ext , ldap_search_ext_s, ldap_control_free The ldap_delete function removes an entry from the directory asynchronously. 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. #include <ldap.h> int ldap_delete( LDAP *ld, const char *dn ); 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 the message ID of the ldap_delete operation. 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. Please use the newer version of this function, ldap_delete_ext . Example 21–11 uses the asynchronous ldap_delete function to remove the entry for Barbara Jensen from the directory. #include <ldap.h> ... LDAP *ld; LDAPMessage *result; int msgid, rc; struct timeval tv; /* Distinguished name of the entry that you want to delete. */ char *dn = "uid=bjensen,ou=People,dc=example, dc=com"; ... /* Set up the timeout period to wait for the "modify" operation */ tv.tv_sec = tv.tv_usec = 0; /* Delete the entry */ if ( ( msgid = ldap_delete( ld, dn ) ) == -1 ) { ldap_perror( ld, "ldap_delete" ); return( 1 ); } /* Check to see if the operation has completed */ while ( ( rc = ldap_result( ld, msgid, 0, &tv, &result ) ) == 0 ) { ... /* do other work while waiting for the operation to complete */ ... } /* Check the result to see if any errors occurred */ ldap_result2error( ld, result, 1 ); ldap_perror( ld, "ldap_delete" ); ... ldap_delete_ext The ldap_delete_ext function deletes an entry from the directory asynchronously. 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. #include <ldap.h> int ldap_delete_ext( LDAP *ld, const char *dn, LDAPControl **serverctrls, LDAPControl **clientctrls, int *msgidp ); 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. One of the following values: LDAP_SUCCESS if successful. LDAP_PARAM_ERROR if an invalid parameter was passed to the function. LDAP_NO_MEMORY if memory cannot be allocated. LDAP_ENCODING_ERROR if an error occurred when BER-encoding the control. LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost. LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function. 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. 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 . ldap_delete_ext_s, ldap_result, ldap_parse_result The ldap_delete_ext_s function deletes an entry from the directory synchronously. 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. #include <ldap.h> int ldap_delete_ext_s( LDAP *ld, const char *dn, LDAPControl **serverctrls, LDAPControl **clientctrls ); 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. One of the following values: One of the following values: LDAP_SUCCESS if successful. LDAP_PARAM_ERROR if an invalid parameter was passed to the function. LDAP_NO_MEMORY if memory cannot be allocated. LDAP_ENCODING_ERROR if an error occurred when BER-encoding the control. LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost. LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function. LDAP_LOCAL_ERROR if an error occurred when receiving the results from the server. LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded results from the server. &cnDirectoryServer; and other LDAP server products may send result codes in addition to those described. For example, the server may have loaded a plug-in that returns custom result codes. Check your LDAP server documentation for other result codes. 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. ldap_delete_ext The ldap_delete_s deletes an entry from the directory synchronously. 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. #include <ldap.h> int ldap_delete_s(LDAP *ld, const char *dn); Parameters Description ld Pointer to an LDAP structure containing information about the connection to the LDAP server. dn DN of the entry to remove. For a list of possible result codes for an LDAP delete operation, see the ldap_delete_ext_s function. Please use the newer version of this function, ldap_delete_ext_s . Example 21–12 uses the synchronous ldap_delete_s function to delete the entry for Barbara Jensen from the directory. #include <ldap.h> LDAP *ld; /* Distinguished name of the entry that you want to delete. */ char *dn = "uid=bjensen,ou=People,dc=example, dc=com"; ... /* Delete the entry */ if ( ldap_delete_s( ld, dn ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldap_delete_s" ); return( 1 ); } ... ldap_delete_ext_s The ldap_dn2ufn function converts a DN into a more user-friendly form by stripping off the cryptic type names. #include <ldap.h> char * ldap_dn2ufn( const char *dn ); Parameter Description dn The DN that you want converted. One of the following values: If successful, returns the DN in its friendlier form. If unsuccessful, returns NULL. For more information on user friendly naming (UFN), see RFC 1781, Using the OSI Directory to Achieve User Friendly Naming (). The ldap_entry2html function writes the HTML representation of an LDAP entry. #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 ); Parameter Description ld Pointer to an LDAP structure containing information about the connection to the LDAP server. buf A pointer to a buffer of size LDAP_DTMPL_BUFSIZ or larger. If NULL, a buffer is allocated and freed internally. entry Specifies the attribute values to be represented. tmpl Pointer to the display template to be used, usually obtained by calling ldap_oc2template. defattrs A NULL terminated array of LDAP attribute names for which you wish to provide default values. It is only used if the entry contains no values for the attribute. defvals An array of NULL terminated arrays of default values corresponding to the attributes. writeproc Your writeproc function should be declared as: int writeproc( writeparm, p, len ) void *writeparm; char *p; int len; where p is a pointer to text to be written and len is the length of the text. p is guaranteed to be zero terminated. writeparm A pointer to a structure that will be passed as the first parameter of the writeproc procedure. Typically, this is used to pass the file descriptor of the file to write to. eol Lines of text are terminated with this string. rdncount Limits the number of components that are displayed for DN attributes. opts Specifies output options. The allowed values are: zero (default output) LDAP_DISP_OPT_AUTOLABELWIDTH which causes the width for labels to be determined based on the longest label in tmpl . LDAP_DISP_OPT_HTMLBODYONLY which instructs the library not to include <HTML>, <HEAD>, <TITLE>, and <BODY> tags. In other words, an HTML fragment is generated, and the caller is responsible for prepending and appending the appropriate HTML tags to construct a correct HTML document. urlprefix Starting text to use when constructing an LDAP URL. The default is the string ldap://. base The base with which to begin when executing search actions. If NULL , search action template items are ignored. LDAP_SUCCESS if successful. An LDAP error code on error. 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. ldap_entry2text, ldap_oc2template The ldap_entry2html_search function determines the appropriate display template to use by calling ldap_oc2template . #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 ); 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:// LDAP_SUCCESS if successful. An LDAP error code on error. 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. ldap_search_s, ldap_entry2text_search , ldap_init_templates, ldap_init_templates_buf, ldap_entry2text The ldap_entry2text function writes the text representation of an LDAP entry. #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 ); 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. LDAP_SUCCESS if successful. An LDAP error code on error. 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. ldap_entry2html, ldap_oc2template The ldap_entry2text_search function determines the appropriate display template to use by calling ldap_oc2template . #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 ); 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. LDAP_SUCCESS if successful. An LDAP error code on error. ldap_entry2text_search will call ldap_search_s to retrieve any attribute values to be displayed. ldap_entry2html_search, ldap_oc2template, ldap_search_s , ldap_init_templates, ldap_init_templates_buf The ldap_err2string function returns the corresponding error message for an error code. #include <ldap.h> char * ldap_err2string( int err ); Parameter Description err Error code that you want interpreted into an error message. One of the following values: If successful, returns the corresponding error message for the error code. If unsuccessful (for example, if the error code is not a valid LDAP API error code), returns Unknown error. Example 21–13 sets the variable err_msg to the error message corresponding to the error code returned by the ldap_simple_bind_s function. #include <ldap.h> ... LDAP *ld; char *dn = "uid=bjensen,ou=People,dc=example, dc=com"; char *pw = "hifalutin"; char *err_msg; ... err_msg = ldap_err2string( ldap_simple_bind_s( ld, dn, pw ) ); ... ldap_get_lderrno, ldap_perror, ldap_result2error , ldap_set_lderrno, ldapssl_err2string The ldap_explode_dn function converts a DN into its component parts. #include <ldap.h> char ** ldap_explode_dn( const char *dn, int notypes ); Parameter Description dn DN that you want separated into components. notypes Specifies whether or not type names in the DN are returned. This parameter can have the following possible values: 0 specifies that type names are returned. A non-zero value specifies that type names are not returned. One of the following values: If successful, returns a NULL terminated array containing the components of the DN. If unsuccessful, returns NULL. 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 } ldap_explode_rdn, ldap_get_dn This function is to be deprecated and should not be used. It is included in ldap-to-be-deprecated.h for backward-compatibility. The ldap_explode_dns function takes a DNS-style DN, breaks it up into its component parts, and returns a NULL terminated array. For example, the DN ldap.example.com will return { "ldap", "example", "com", NULL }. The result can be freed by calling ldap_value_free. #include <ldap-to-be-deprecated.h> char ** ldap_explode_dns( const char *dn ); Parameter Description dn DN that you want separated into components. One of the following values: If successful, returns a NULL terminated array containing the components of the DN. If unsuccessful, returns NULL. The ldap_explode_rdn function converts a relative distinguished name (RDN) into its component parts. #include <ldap.h> char ** ldap_explode_rdn( const char *dn, int notypes ); Parameter Description dn RDN that you want separated into components. notypes Specifies whether or not type names in the RDN are returned. This parameter can have the following possible values: 0 specifies that type names are returned. A non-zero value specifies that type names are not returned. One of the following values: If successful, returns a NULL terminated array containing the components of the RDN. If unsuccessful, returns NULL. The following function call: ldap_explode_rdn( "ou=Sales + cn=Barbara Jensen", 0 ); returns this array: { "ou=Sales", "cn=Barbara Jensen", NULL } ldap_explode_dn, ldap_get_dn The ldap_extended_operation function sends a request to the server to perform an extended operation asynchronously. #include <ldap.h> int ldap_extended_operation( LDAP *ld, const char *requestoid, struct berval *requestdata, LDAPControl **serverctrls, LDAPControl **clientctrls, int *msgidp ); Parameter Description ld Pointer to an LDAP structure containing information about the connection to the LDAP server. requestoid Object identifier (OID) of the extended operation that you want the server to perform. After processing an LDAP v3 extended operation, an LDAP server can return an OID and data in the result. To parse the OID and data from the result, call the ldap_parse_extended_result function. requestdata Pointer to a berval structure containing the data that you want passed to the server to perform the extended operation. The data in the berval is a buffer of the BER encoded data type, usually obtained using the ber_flatten function. serverctrls Pointer to an array of LDAPControl structures representing LDAP server controls that apply to this operation. If you do not want to pass any server controls, specify NULL for this argument. clientctrls Pointer to an array of LDAPControl structures representing LDAP client controls that apply to this operation. If you do not want to pass any client controls, specify NULL for this argument. msgidp Pointer to an integer that will be set to the message ID of the LDAP operation. One of the following values: LDAP_SUCCESS if successful. LDAP_PARAM_ERROR if an invalid parameter was passed to the function. LDAP_NO_MEMORY if memory cannot be allocated. LDAP_ENCODING_ERROR if an error occurred when BER-encoding the control. LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost. LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function. To check the result of this operation, call ldap_result, ldap_parse_extended_result, and ldap_get_lderrno. The ldap_extended_operation function sends a request to the server to perform an LDAP v3 extended operation. ldap_extended_operation is an asynchronous function; it does not directly return results. If you want the results to be returned directly by the function, call the synchronous function ldap_extended_operation_s. ldap_extended_operation_s, ldap_result, ldap_parse_extended_result , ldap_get_lderrno, ber_flatten The ldap_extended_operation_s function sends a request to the server to perform an extended operation synchronously. #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 ); Parameter Description ld Pointer to an LDAP structure containing information about the connection to the LDAP server. requestoid Object identifier (OID) of the extended operation that you want the server to perform. requestdata Pointer to a berval structure containing the data that you want passed to the server to perform the extended operation. The data in the berval is a buffer of the BER encoded data type, usually obtained using the ber_flatten function. serverctrls Pointer to an array of LDAPControl structures representing LDAP server controls that apply to this operation. If you do not want to pass any server controls, specify NULL for this argument. clientctrls Pointer to an array of LDAPControl structures representing LDAP client controls that apply to this operation. If you do not want to pass any client controls, specify NULL for this argument. retoidp Pointer to the OID returned by the server after performing the extended operation. When done, you can free this by calling the ldap_memfree function. retdatap Pointer to the pointer for a berval structure containing the data returned by the server after performing the extended operation. When done, you can free this by calling the ber_bvfree function. One of the following values: LDAP_SUCCESS if successful. LDAP_PARAM_ERROR if an invalid parameter was passed to the function. LDAP_NO_MEMORY if memory cannot be allocated. LDAP_ENCODING_ERROR if an error occurred when BER-encoding the control. LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost. LDAP_LOCAL_ERROR if an error occurred when receiving the results from the server. LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded results from the server. LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function. &cnDirectoryServer; and other LDAP server products may send result codes in addition to those described. For example, the server may have loaded a plug-in that returns custom result codes. Check your LDAP server documentation for other result codes. The ldap_extended_operation_s function sends a request to the server to perform an LDAP v3 extended operation. The LDAP server must support the extended operation. &cnDirectoryServer; supports a server plug-in interface that you can use to add support for extended operations. 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 LDAP v3 extended operation, an LDAP server can return an object identifier and data in the results. The retoidp and retdatap arguments point to these values. ldap_extended_operation, ber_flatten 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. #include <ldap.h> char * ldap_first_attribute( LDAP *ld, LDAPMessage *entry, BerElement **ber ); 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. One of the following values: If successful, returns the pointer to the name of the first attribute in an entry. When you are done using this data, you should free the memory by calling the ldap_memfree function. If unsuccessful, returns a NULL and sets the appropriate error code in the LDAP structure. To get the error code, call the ldap_get_lderrno function. Example 21–14 retrieves each attribute for an entry. #include <stdio.h> #include <ldap.h> ... LDAP *ld; LDAPMessage *result, *e; BerElement *ber; char *a; char *my_searchbase = "dc=example,dc=com"; char *my_filter = "(sn=Jensen)" ... /* Search the directory */ if ( ldap_search_s( ld, my_searchbase, LDAP_SCOPE_SUBTREE, my_filter, NULL, 0, &result ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldap_search_s" ); return( 1 ); } /* Get the first matching entry.*/ e = ldap_first_entry( ld, result ); /* Retrieve the attributes the entry */ for ( a = ldap_first_attribute( ld, e, &ber ); a != NULL; a = ldap_next_attribute( ld, e, ber ) ) { ... /* Code to get and manipulate attribute values */ ... } ldap_memfree( a ); } /* Free the BerElement from memory when done */ if ( ber != NULL ) { ldap_ber_free( ber, 0 ); } ... ldap_first_entry, ldap_next_entry, ldap_next_attribute , BerElement The ldap_first_disptmpl function returns the first template in a list. #include <disptmpl.h> ldap_first_disptmpl( struct ldap_disptmpl *tmpllist ); Parameter Description tmpllistp Pointer to a list of template data structures. 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 . ldap_next_disptmpl, ldap_init_templates, ldap_init_templates_buf The ldap_first_entry function returns a pointer to the LDAPMessage structure representing the first directory entry in a chain of search results. #include <ldap.h> LDAPMessage * ldap_first_entry( LDAP *ld, LDAPMessage *result ); 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. 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. The ldap_first_entry function returns a pointer to the LDAPMessage structure representing the first directory entry in a chain of search results. Search result entries are in messages of the type LDAP_RES_SEARCH_ENTRY. You can use this function in conjunction with the ldap_next_entry function to iterate through the directory entries in a chain of search results. These functions skip over any messages in the chain that do not have the type LDAP_RES_SEARCH_ENTRY. Do not free the LDAPMessage structure returned by this function. Because this is a structure within a chain of search results, freeing this structure will free part of the chain of search results. When you are done working with the search results, you can free the chain itself, rather than individual structures within the chain. ldap_result, ldap_search_ext , ldap_search_ext_s, ldap_next_entry The ldap_first_message function returns a pointer to the first LDAPMessage structure in a chain of search results. #include <ldap.h> LDAPMessage * ldap_first_message( LDAP *ld, LDAPMessage *res ); 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. 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. The ldap_first_message function returns a pointer to the first LDAPMessage structure in a chain of search results. You can use this function in conjunction with the ldap_next_message function to iterate through the chain of search results. You can also call the ldap_msgtype function to determine if each message contains a matching entry, a message of the type LDAP_RES_SEARCH_ENTRY, or a search reference, a message of the type LDAP_RES_SEARCH_REFERENCE. Do not free the LDAPMessage structure returned by this function. Because this is a structure within a chain of search results, freeing this structure will free part of the chain of search results. When you are done working with the search results, you can free the chain itself, rather than individual structures within the chain. ldap_result, ldap_search_ext , ldap_search_ext_s, ldap_next_message, ldap_first_entry , 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. #include <ldap.h> LDAPMessage * ldap_first_reference(LDAP *ld, LDAPMessage *res ); 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. 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 . The ldap_first_reference function returns a pointer to the LDAPMessage structure representing the first search reference in a chain of search results. Search references are in messages of the type LDAP_RES_SEARCH_REFERENCE, continuation references as specified in LDAPv3 that are stored as referral entries. Like a referral, each continuation reference itself may contain a number of URLs assumed to be equivalent, and the client should use one of those URLs. You can use this function in conjunction with the ldap_next_reference function to iterate through the search references in a chain of search results. These functions skip over any messages in the chain that do not have the type LDAP_RES_SEARCH_REFERENCE. Do not free the LDAPMessage structure returned by this function. Because this is a structure within a chain of search results, freeing this structure will free part of the chain of search results. When you are done working with the search results, you can free the chain itself, rather than individual structures within the chain. ldap_result, ldap_search_ext , ldap_search_ext_s, ldap_next_reference, ldap_first_message The ldap_first_searchobj function returns the first search preference configuration from a data structure defined in the list solist . #include <ldap.h> ldap_searchobj * ldap_first_searchobj( struct ldap_searchobj *solist ); Parameter Description solist Pointer to the search preference data structures, typically obtained by calling ldap_init_searchprefs. 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. ldap_init_searchprefs, ldap_init_searchprefs_buf The ldap_first_tmplcol function returns a pointer to the first item within a template. #include <disptmpl.h> struct ldap_tmplitem * ldap_first_tmplcol( struct ldap_disptmpl *tmpl, struct ldap_tmplitem *row ); Parameter Description tmpl The name of the template to be retrieved. row The row in which the item is to be retrieved from. If successful, a pointer to an ldap_tmplitem structure. A NULL pointer on error. 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. ldap_first_tmplrow, ldap_next_tmplcol The ldap_first_tmplrow function returns a pointer to the first row of items in a template. #include <disptmpl.h> struct ldap_tmplitem * ldap_first_tmplrow( struct ldap_disptmpl *tmpl ); Parameter Description tmpl The name of the template to be retrieved. If successful, a pointer to an ldap_tmplitem structure. A NULL pointer on error. ldap_next_tmplrow, ldap_first_tmplcol 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. #include <ldap.h> void ldap_free_friendlymap( FriendlyMap *map ); Parameter Description map Pointer to the FriendlyMap mapping structure in memory. Example 21–15 frees memory allocated by the ldap_friendly_name function. #include <ldap.h> #include <stdio.h> ... FriendlyMap map = NULL; char *map_file = "/u/mozilla/ldapsdk/examples/ldapfriendly"; char *unfriendly_name = "IS"; char *friendly_name; ... /* Read the ldapfriendly file into the map in memory */ friendly_name = ldap_friendly_name( map_file, unfriendly_name, &map ); printf( "Friendly Name for %s: %s\n", unfriendly_name, friendly_name ); /* Since file is in memory, no need to reference it in subsequent calls */ friendly_name = ldap_friendly_name( NULL, "VI", &map ); printf( "Friendly Name for VI: %s\n", friendly_name ); ... ldap_free_friendlymap( map ); ... ldap_friendly_name, FriendlyMap The ldap_free_searchprefs function disposes of the data structures allocated by ldap_init_searchprefs. #include <ldap.h> void ldap_free_searchprefs( struct ldap_searchobj *solist ); Parameter Description solist Pointer to the data structures, typically obtained by calling ldap_init_searchprefs. ldap_init_searchprefs, ldap_init_searchprefs_buf The ldap_free_sort_keylist function frees the structures allocated by the ldap_create_sort_keylist function. #include <ldap.h> void ldap_free_sort_keylist (LDAPsortkey **sortKeyList); Parameter Description sortKeyList Array of LDAPsortkey structures that you want to free from memory. 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. ldap_create_sort_keylist, ldap_create_sort_control The ldap_free_templates function disposes of the templates allocated by ldap_init_templates. #include <disptmpl.h> void ldap_free_templates( struct ldap_disptmpl *tmpllist ); Parameter Description tmpllistp Pointer to a list of template data structures. ldap_free_templates releases the templates allocated by ldap_init_templates. Each template defined in the file is an ldap_disptmpl structure. The ldap_free_urldesc function frees memory allocated by the ldap_url_parse function. #include <ldap.h> void ldap_free_urldesc( LDAPURLDesc *ludp ); Parameter Description ludp Pointer to a LDAPURLDesc structure. Example 21–16 parses an LDAP URL and then frees the LDAPURLDesc structure from memory after verifying that the LDAP URL is valid. #include <stdio.h> #include <ldap.h> ... char *my_url = "ldap://ldap.example.com:1389/dc=example,dc=com?cn,mail,telephoneNumber? sub?(sn=Jensen)"; LDAPURLDesc *ludpp; int res, i; ... if ( ( res = ldap_url_parse( my_url, &ludpp ) ) != 0 ) { switch( res ){ case LDAP_URL_ERR_NOTLDAP: printf( "URL does not begin with \"ldap://\"\n" ); break; case LDAP_URL_ERR_NODN: printf( "URL does not contain a distinguished name\n" ); break; case LDAP_URL_ERR_BADSCOPE: printf( "URL contains an invalid scope\n" ); break; case LDAP_URL_ERR_MEM: printf( "Not enough memory\n" ); break; default: printf( "Unknown error\n" ); } return( 1 ); } printf( "URL is a valid LDAP URL\n" ); ldap_free_urldesc( ludpp ); ... ldap_url_parse 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. ldapfriendly, located in lib/ldapcsdk/etc , is a sample file that maps two letter country codes to their full names. It can be used in context with ldap_friendly_name . #include <ldap.h> char * ldap_friendly_name( char *filename, char *uname, FriendlyMap *map ); 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. One of the following values: If successful, returns the user-friendly name for the specified identifier. If unsuccessful—for example, if the file cannot be read, if the file is in a bad format, or if the map parameter is set to NULL—returns the original identifier (the value passed as the uname parameter). This function relies on the existence of a text file mapping standard identifiers to user-friendly names. The names in the file are tab-delimited. <unfriendly_name> <friendly_name> AD Andorra AE United Arab Emirates AF Afghanistan AG Antigua and Barbuda AI Anguilla Example 21–18 reads in a map of user-friendly names and prints the name corresponding to the standard identifier IS. #include <ldap.h> #include <stdio.h> ... FriendlyMap map = NULL; char *map_file = "/u/mozilla/ldapsdk/examples/ldapfriendly"; char *unfriendly_name = "IS"; char *friendly_name; ... /* Read the ldapfriendly file into the map in memory */ friendly_name = ldap_friendly_name( map_file, unfriendly_name, &map ); printf( "Friendly Name for %s: %s\n", unfriendly_name, friendly_name ); /* Since file is in memory, no need to reference it in subsequent calls */ friendly_name = ldap_friendly_name( NULL, "VI", &map ); printf( "Friendly Name for VI: %s\n", friendly_name ); ... ldap_free_friendlymap, FriendlyMap The ldap_get_dn routine returns the DN for an entry in a chain of search results. #include <ldap.h> char * ldap_get_dn( LDAP *ld, LDAPMessage *entry ); 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. 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. You can get an entry from a chain of search results by calling the ldap_first_entry and ldap_next_entry functions. Example 21–19 prints the DN for each entry found in a search. #include <stdio.h> #include <ldap.h> ... LDAP *ld; LDAPMessage *result, *e; char *dn; char *my_searchbase = "dc=example,dc=com"; char *my_filter = "(sn=Jensen)"; ... /* Search the directory */ if ( ldap_search_s( ld, my_searchbase, LDAP_SCOPE_SUBTREE, my_filter, NULL, 0, &result ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldap_search_s" ); return( 1 ); } /* For each matching entry found, print out the name of the entry.*/ for ( e = ldap_first_entry( ld, result ); e != NULL; e = ldap_next_entry( ld, e ) ) { if ( ( dn = ldap_get_dn( ld, e ) ) != NULL ) { printf( "dn: %s\n", dn ); /* Free the memory used for the DN when done */ ldap_memfree( dn ); } } /* Free the result from memory when done. */ ldap_msgfree( result ); ... ldap_first_entry, ldap_next_entry, ldap_get_lderrno The ldap_get_entry_controls function gets the LDAP controls included with a directory entry in a set of search results. #include <ldap.h> int ldap_get_entry_controls( LDAP *ld, LDAPMessage *entry, LDAPControl ***serverctrlsp ); Parameter Description ld Pointer to an LDAP structure containing information about the connection to the LDAP server. entry Pointer to an LDAPMessage structure representing an entry in a chain of search results. serverctrlsp Pointer to an array of LDAPControl structures, which represent the LDAP v3 server controls returned by the server. 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. The ldap_get_entry_controls function retrieves the LDAP v3 controls included in a directory entry in a chain of search results. The LDAP controls are specified in an array of LDAPControl structures with each structure representing one LDAP control. Other controls are returned with results sent from the server. You can call ldap_parse_result to retrieve those controls. The ldap_getfilter_free function frees the memory used by a filter set. #include <ldap.h> void ldap_getfilter_free( LDAPFiltDesc *lfdp ); Parameter Description lfdp Pointer to a LDAPFiltDesc structure. Once you call ldap_getfilter_free, the LDAPFiltDesc structure is no longer valid and cannot be used again. Example 21–20 frees the LDAPFiltDesc structure from memory after all searches are completed. #include <ldap.h> ... LDAPFiltDesc *lfdp; char *filter_file = "myfilters.conf"; ... /* Read the filter configuration file into an LDAPFiltDesc structure */ lfdp = ldap_init_getfilter( filter_file ); ... /* Retrieve filters and perform searches */ ... /* Free the configuration file (the LDAPFiltDesc structure) */ ldap_getfilter_free( lfdp ); ... ldap_init_getfilter, ldap_init_getfilter_buf The ldap_getfirstfilter function retrieves the first filter that is appropriate for a given value. #include <ldap.h> LDAPFiltInfo * ldap_getfirstfilter( LDAPFiltDesc *lfdp, char *tagpat, char *value ); 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. One of the following values: If successful, returns a pointer to an LDAPFiltInfo structure. If no more filters can be returned, returns a NULL. If unsuccessful, returns a NULL. Example 21–21 is based on the getfilt command-line program example provided with the &DirectorySDKForC;. The program prompts the user to enter search criteria and, based on the criteria entered, it retrieves filters that match the criteria. #include <stdio.h> #include <ldap.h> ... LDAP *ld; LDAPMessage *result, *e; BerElement *ber; char *a, *dn; char **vals; int i; LDAPFiltDesc *ldfp; LDAPFiltInfo *ldfi; char buf[ 80 ]; /* Contains the search criteria */ int found; ... /* Load the filter configuration file into an LDAPFiltDesc structure */ if ( ( ldfp = ldap_init_getfilter( "myfilters.conf" ) ) == NULL ) { perror( "Cannot open filter configuration file" ); return( 1 ); } /* Read a string to search for */ printf( "Enter a string to search for: " ); gets( buf ); if ( strlen( buf ) == 0 ) { fprintf( stderr, "usage: %s search-string\n", argv[ 0 ]); return( 1 ); } /* Select a filter to use when searching for the value in buf */ found = 0; for ( ldfi = ldap_getfirstfilter( ldfp, "people", buf ); ldfi != NULL; ldfi = ldap_getnextfilter( ldfp ) ) { /* Use the selected filter to search the directory */ if ( ldap_search_s( ld, "dc=example,dc=com, ldfi->lfi_scope, ldfi->lfi_filter, NULL, 0, &result ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldap_search_s" ); return( 1 ); } else { /* Once a filter gets results back, stop iterating through the different filters */ if ( ( found = ldap_count_entries( ld, result ) > 0 ) ) { break; } else { ldap_msgfree( result ); } } } if ( found == 0 ) { printf( "No matching entries found.\n" ); } else { printf( "Found %d %s match%s for \"%s\"\n\n", found, ldfi->lfi_desc, found == 1 ? "" : "es", buf ); } ldap_msgfree( result ); ldap_getfilter_free( ldfp ); ... ldap_init_getfilter, ldap_init_getfilter_buf, ldap_getnextfilter 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. #include <ldap.h> char ** ldap_get_lang_values( LDAP *ld, LDAPMessage *entry, const char *target, char **type ); 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. 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. 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. ldap_first_entry, ldap_first_attribute, ldap_get_lang_values_len , ldap_get_values, ldap_next_entry, ldap_next_attribute 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. #include <ldap-deprecated.h> struct berval ** ldap_get_lang_values_len( LDAP *ld, LDAPMessage *entry, const char *target, char **type ); 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. 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. Use the ldap_get_lang_values routine if the attribute values are string values. ldap_first_attribute, ldap_first_entry, ldap_get_lang_values , ldap_next_entry, ldap_next_attribute The ldap_get_lderrno function gets information about the last error that occurred for an LDAP operation. #include <ldap.h> int ldap_get_lderrno( LDAP *ld, char **m, char **s ); Parameter Description ld Pointer to an LDAP structure containing information about the connection to the LDAP server. m In the event of an LDAP_NO_SUCH_OBJECT error return, this parameter contains the portion of the DN that identifies an existing entry. s The text of the error message. The LDAP error code for the last operation. ldap_get_lderrno gets information about the last error that occurred for an LDAP operation. You can also call this function to get error codes for functions that do not return errors, such as ldap_next_attribute. Example 21–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. #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 Example 21–22, if no organizational unit named People exists, the matched variable is set to dc=example,dc=com . ldap_err2string, ldap_perror, ldap_result2error, ldap_set_lderrno The ldap_getnextfilter function retrieves the next filter that is appropriate for a given value. #include <ldap.h> LDAPFiltInfo * ldap_getnextfilter( LDAPFiltDesc *lfdp ); Parameter Description lfdp Pointer to an LDAPFiltDesc structure. 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. Call this function to get subsequent filters after calling ldap_getfirstfilter. See Example 21–21. ldap_getfirstfilter The function ldap_get_option retrieves session preferences from an LDAP structure. #include <ldap.h> int ldap_get_option( LDAP *ld, int option, void *optdata ); Parameter Description ld Pointer to an LDAP structure containing information about the connection to the LDAP server. option Option that you want to retrieve. This parameter must be set to one of the option values. optdata Pointer to the buffer in which the value of the option will be put. Table 21–110 describes the options that you can retrieve with ldap_get_option. Option Description LDAP_OPT_API_FEATURE_INFO Retrieves information about the revision of a supported LDAP feature. This option is READ-ONLY and cannot be set. The data type for the optdata parameter is (LDAPAPIFeatureInfo *). LDAP_OPT_API_INFO Retrieves information about the API implementation at execution time (API version, protocol version, the names of supported API extensions with their vendor name version, etc.). For details on the structure returned, refer to the ldap.h header file. This option is READ-ONLY and cannot be set. The data type for the optdata parameter is (LDAPAPIInfo *). LDAP_OPT_CLIENT_CONTROLS Pointer to an array of LDAPControl structures representing the LDAP v3 client controls you want sent with every request by default. The data type for the optdata parameter is (LDAPControl ***). LDAP_OPT_DESC Socket descriptor underlying the main LDAP connection. The LBER_SOCKET data type depends on the platform that you are using: int in UNIX. SOCKET in Windows.The data type for the optdata parameter is (LBER_SOCKET *). LDAP_OPT_DEREF Determines how aliases work during a search. optdata can be one of the following values: LDAP_DEREF_NEVER specifies that aliases are never dereferenced. LDAP_DEREF_SEARCHING specifies that aliases are dereferenced when searching under the base object (but not when finding the base object). LDAP_DEREF_FINDING specifies that aliases are dereferenced when finding the base object (but not when searching under the base object). LDAP_DEREF_ALWAYS specifies that aliases are always dereferenced when finding and searching under the base object. The data type for the optdata parameter is (int *). LDAP_OPT_DNS_FN_PTRS DEPRECATED OPTION: Lets you use alternate DNS functions for getting the host entry of the LDAP server. The data type for the optdata parameter is (struct ldap_dns_fns *). LDAP_OPT_ERROR_NUMBER Retrieves the result code for the most recent LDAP error that occurred in this session. The data type for the optdata parameter is (int *). LDAP_OPT_ERROR_STRING Retrieves the error message returned with the result code for the most recent LDAP error that occurred in this session. The data type for the optdata parameter is (char **). LDAP_OPT_EXTRA_THREAD_FN_PTRS Lets you specify the locking and semaphore functions that you want called when getting results from the server. The data type for the optdata parameter is (struct ldap_extra_thread_fns *). LDAP_OPT_HOST_NAME Sets the host name (or list of hosts) for the primary LDAP server. The data type for the optdata parameter is (char **). LDAP_OPT_IO_FN_PTRS DEPRECATED OPTION: Lets you use alternate communication stacks. The data type for the optdata parameter is (struct ldap_io_fns *). LDAP_OPT_MATCHED_DN Gets the matched DN value returned with the most recent LDAP error that occurred for this session. The data type for the optdata parameter is (char **) LDAP_OPT_MEMALLOC_FN_PTRS Gets a pointer to the callback structure which you previously set. The data type for the optdata parameter is (struct ldap_memalloc_fnsldap_io_fns *). LDAP_OPT_PROTOCOL_VERSION Version of the protocol supported by your client. You can specify either LDAP_VERSION2 or LDAP_VERSION3. If no version is set, the default is LDAP_VERSION2. In order to use LDAP v3 features, you need to set the protocol version to LDAP_VERSION3. The data type for the optdata parameter is (int *). LDAP_OPT_REBIND_ARG Lets you set the last argument passed to the routine specified by LDAP_OPT_REBIND_FN. You can also set this option by calling the ldap_set_rebind_proc function. The data type for the optdata parameter is (void *). LDAP_OPT_REBIND_FN Lets you set the routine to be called when you need to authenticate a connection with another LDAP server (for example, during the course of following a referral). You can also set this option by calling the ldap_set_rebind_proc function. The data type for the optdata parameter is (LDAP_REBINDPROC_CALLBACK *). LDAP_OPT_RECONNECT If the connection to the server is lost, determines whether or not the same connection handle should be used to reconnect to the server. By default, this option is off. You handle failover with the following values: LDAP_OPT_ON specifies that the same connection handle can be used to reconnect to the server. LDAP_OPT_OFF specifies that you want to create a new connection handle to connect to the server.The data type for the optdata parameter is (int *). LDAP_OPT_REFERRALS Determines whether or not the client should follow referrals. By default, the client follows referrals. optdata can be one of the following values: LDAP_OPT_ON specifies that the server should follow referrals. LDAP_OPT_OFF specifies that the server should not follow referrals.The data type for the optdata parameter is (int *). LDAP_OPT_REFERRAL_HOP_LIMIT Maximum number of referrals the client should follow in a sequence. In other words, the client can only be referred this number of times before it gives up. By default, the maximum number of referrals that the client can follow in a sequence is 5 for the initial connection. This limit does not apply to individual requests that generate multiple referrals in parallel. The data type for the optdata parameter is (int *). LDAP_OPT_RESTART Determines whether or not LDAP I/O operations should be restarted automatically if they are prematurely aborted. optdata can be one of the following values: LDAP_OPT_ON specifies that I/O operations should be restarted automatically. LDAP_OPT_OFF specifies that I/O operations should not be restarted automatically.The data type for the optdata parameter is (int *). LDAP_OPT_SERVER_CONTROLS Pointer to an array of LDAPControl structures representing the LDAP v3 server controls you want sent with every request by default. Typically, since controls are specific to the type of request, you may want to pass the controls using operation-specific functions, such as ldap_add_ext, instead. The data type for the optdata parameter is (LDAPControl ***). LDAP_OPT_SIZELIMIT Maximum number of entries that should be returned by the server in search results. The LDAP server may impose a smaller size limit than the limit you specify as the server administrator also has the ability to set this limit. The data type for the optdata parameter is (int *). LDAP_OPT_SSL Determines whether or not SSL is enabled. optdata can be one of the following values: LDAP_OPT_ON specifies that SSL is enabled. LDAP_OPT_OFF specifies that SSL is disabled. The data type for the optdata parameter is (int *). LDAP_OPT_THREAD_FN_PTRS Lets you specify the thread function pointers. The data type for the optdata parameter is (struct ldap_thread_fns *). LDAP_OPT_TIMELIMIT Maximum number of seconds that should be spent by the server when answering a search request. The LDAP server may impose a shorter time limit than the limit you specify as the server administrator also has the ability to set this limit. The data type for the optdata parameter is (int *). LDAP_X_OPT_EXTIO_FN_PTRS Extended I/O function callback option. LDAP_X_OPT_CONNECT_TIMEOUT Value of a time out (expressed in milliseconds) for non-blocking connect call. The data type for the optdata parameter is (int *). LDAP_X_OPT_SOCKBUF Socket buffer structure associated to the LDAP connection. See also ldap_get_option 3LDAP for details on LDAP_OPT_X_SASL* parameters. One of the following values: LDAP_SUCCESS if successful. -1 if unsuccessful. Example 21–23 gets the session preference for the maximum number of entries to be returned from search operations. #include <ldap.h> ... LDAP *ld; int max_ret; ... /* Get the maximum number of entries returned */ if (ldap_get_option, LDAP_OPT_SIZELIMIT, &max_ret) != LDAP_SUCCESS) { ldap_perror( ld, "ldap_get_option" ); return( 1 ); } Example 21–23 could also include the following two small sections of code that show how to use the LDAP_OPT_API_FEATURE_INFO and the LDAP_OPT_API_INFO options, respectively. LDAPIIFeatureInfo ldfi; ldfi.ldapaif_info_version = LDAP_FEATURE_INFO_VERSION; ldfi.ldapaif_name = "VIRTUAL_LIST_VIEW"; if (ldap_get_option(NULL, LDAP_OPT_API_FEATURE_INFO, &ldfi)==0) { /* use the info here */ } LDAPIInfo ldai; ldai.ldapiai_info_version = LDAP_API_INFO_VERSION; if (ldap_get_option( NULL, LDAP_OPT_API_INFO, &ldia ) == 0) { /* use the ldai info here */ } ldap_init, prldap_init (IPv6), ldap_set_option The ldap_get_values function returns a NULL terminated array of an attribute’s string values for a given entry. #include <ldap.h> char ** ldap_get_values( LDAP *ld, LDAPMessage *entry, const char *target ); 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. 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. Use the ldap_get_values_len function if the attribute values are binary. Example 21–25 gets and prints the values of an attribute in an entry. This example assumes that all attributes have string values. #include <stdio.h> #include <ldap.h> ... LDAP *ld; LDAPMessage *result, *e; BerElement *ber; char *a; char **vals; char *my_searchbase = "dc=example,dc=com"; char *my_filter = "(sn=Jensen)"; int i; ... /* Search the directory */ if ( ldap_search_s( ld, my_searchbase, LDAP_SCOPE_SUBTREE, my_filter, NULL, 0, &result ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldap_search_s" ); return( 1 ); } /* Get the first matching entry.*/ e = ldap_first_entry( ld, result ); /* Get the first matching attribute */ a = ldap_first_attribute( ld, e, &ber ); /* Get the values of the attribute */ if ( ( vals = ldap_get_values( ld, e, a ) ) != NULL ) { for ( i = 0; vals[i] != NULL; i++ ) { /* Print the name of the attribute and each value */ printf( "%s: %s\n", a, vals[i] ); } /* Free the attribute values from memory when done. */ ldap_value_free( vals ); } ... ldap_first_entry, ldap_first_attribute, ldap_get_values_len , ldap_next_entry, ldap_next_attribute 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. #include <ldap.h> struct berval ** ldap_get_values_len( LDAP *ld, LDAPMessage *entry, const char *target ); 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. 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. Use the ldap_get_values routine if the attribute values are string values. Example 21–26 gets the first value of the jpegPhoto attribute and saves the JPEG data to a file. #include <stdio.h> #include <ldap.h> ... LDAP *ld; LDAPMessage *result, *e; BerElement *ber; struct berval photo_data; struct berval **list_of_photos; FILE *out; char *my_searchbase = "dc=example,dc=com"; char *my_filter = "(sn=Jensen)"; ... /* Search the directory */ if ( ldap_search_s( ld, my_searchbase, LDAP_SCOPE_SUBTREE, my_filter, NULL, 0, &result ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldap_search_s" ); return( 1 ); } /* Get the first matching entry.*/ e = ldap_first_entry( ld, result ); /* Get the value of the jpegPhoto attribute */ if ( ( list_of_photos = ldap_get_values_len( ld, e, "jpegPhoto" ) ) != NULL ) { /* Prepare to write the JPEG data to a file */ if ( ( out = fopen( "photo.jpg", "wb" ) ) == NULL ) { perror( "fopen" ); return( 1 ); } /* Get the first JPEG */ photo_data = *list_of_photos[0]; /* Write the JPEG data to a file */ fwrite( photo_data.bv_val, photo_data.bv_len, 1, out ); fclose( out ); /* Free the attribute values from memory when done. */ ldap_value_free_len( list_of_photos ); } ... ldap_first_entry, ldap_first_attribute, ldap_get_values , ldap_next_entry, ldap_next_attribute 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. #include <ldap.h> LDAP * ldap_init( const char *defhost, int defport ); 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. One of the following values: If successful, returns a pointer to an LDAP structure. If unsuccessful, returns a NULL. The ldap_init function initializes a session with an LDAP server by allocating an LDAP structure containing information about the session including the host name and port of the LDAP server, preferences for the session (such as the maximum number of entries to return in a search), and the error code of the last LDAP operation performed. The LDAP structure defaults to LDAP v2. It is highly recommended to set it to LDAP v3 using the ldap_set_option. ldap_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 Example 21–27 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. ... 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 Example 21–27 ld1.example.com , port 389. If that server does not respond, the client will attempt to connect to the LDAP server on ld2.example.com , port 1389. ... LDAP *ld ... ld = ldap_init( "ld1.example.com ld2.example.com:1389", LDAP_PORT ); If you are connecting to a secure LDAP server over SSL, you should be calling the ldapssl_init function. Example 21–29 initializes a session with the LDAP server at ldap.example.com:389, and sets a session preference that identifies the client as an LDAP v3 client. #include <ldap.h> ... LDAP *ld; /* Specify the host name of the LDAP server. */ char *ldap_host = "ldap.example.com"; /* Because the LDAP server is running on the standard LDAP port (port 389), * you can use LDAP_PORT to identify the port number. */ int ldap_port = LDAP_PORT; ... /* Initialize the session with ldap.example.com:389 */ /* Use prldap_init() for IPv6 support. */ if ( ( ld = ldap_init( ldap_host, ldap_port ) ) == NULL ) { perror( "ldap_init" ); return( 1 ); } /* Specify the LDAP version supported by the client. */ version = LDAP_VERSION3; ldap_set_option( ld, LDAP_OPT_PROTOCOL_VERSION, &version ); ... /* Subsequent calls that authenticate to the LDAP server. */ ... prldap_init (IPv6), ldap_unbind, ldap_unbind_s , ldap_simple_bind, ldap_simple_bind_s The ldap_init_getfilter function reads a valid LDAP filter configuration file (such as ldapfilter.conf) and returns a pointer to an LDAPFiltDesc structure. ldapfilter.conf, the sample LDAP filter configuration file located in lib/ldapcsdk/etc directory, can be used in context with ldap_init_getfilter . #include <ldap.h> LDAPFiltDesc * ldap_init_getfilter( char *fname ); Parameter Description fname Name of the LDAP filter configuration file to use. One of the following values: If successful, returns a pointer to an LDAPFiltDesc structure. If unsuccessful (for example, if there is an error reading the file), returns a NULL. Example 21–30 loads a filter configuration file named myfilters.conf into memory. #include <ldap.h> ... LDAPFiltDesc *lfdp; char *filter_file = "myfilters.conf"; ... lfdp = ldap_init_getfilter( filter_file ); ... ldap_init_getfilter_buf, ldap_getfilter_free The ldap_init_getfilter_buf function reads LDAP filter configuration information from a buffer and returns a pointer to an LDAPFiltDesc structure. #include <ldap.h> LDAPFiltDesc * ldap_init_getfilter_buf(char *buf, long buflen ); Parameter Description buf Buffer containing LDAP filter configuration information. buflen Size of the buffer One of the following values: If successful, returns a pointer to an LDAPFiltDesc structure. If unsuccessful—for example, if there is an error reading the file—returns a NULL. Example 21–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" #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 ) ); ... ldap_init_getfilter, ldap_getfilter_free The ldap_init_searchprefs function reads a sequence of search preference configurations from a valid LDAP searchpref configuration file. #include <ldap.h> int ldap_init_searchprefs( char *file, struct ldap_searchobj **solistp ); Parameter Description file Pointer to a valid LDAP searchpref configuration file. solistp Pointer to a list of search preference data structures. One of the following values: LDAP_SEARCHPREF_ERR_VERSION. LDAP_SEARCHPREF_ERR_MEM if there is a memory allocation problem. Upon success, 0 is returned and solistp is set to point to a list of search preference data structures. ldap_init_searchprefs provides a standard way to access 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, 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. ldap_free_searchprefs, ldap_init_searchprefs_buf The ldap_init_searchprefs_buf function reads a sequence of search preference configurations from the parameter, buf. #include <ldap.h> int ldap_init_searchprefs_buf( char *buf, long buflen, struct ldap_searchobj **solistp ); 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. One of the following values: LDAP_SEARCHPREF_ERR_VERSION if buf points to data that is newer than can be handled. LDAP_SEARCHPREF_ERR_MEM if there is a memory allocation problem. Upon success, 0 is returned and solistp is set to point to a list of search preference data structures. ldap_init_searchprefs_buf reads a sequence of search preference configurations from buf. 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. ldap_init_searchprefs, ldap_free_searchprefs The ldap_init_templates function reads a sequence of templates from a valid LDAP template configuration file. #include <disptmpl.h> int ldap_init_templates( char *file, struct ldap_disptmpl **tmpllistp ); Parameter Description file Pointer to a valid LDAP template configuration file. tmpllistp Pointer to a list of template data structures. If successful, 0 is returned and tmpllistp is configured. Upon error: LDAP_TMPL_ERR_VERSION if buf points to data that is newer than can be handled. LDAP_TMPL_ERR_MEM if there is a memory allocation problem. LDAP_TMPL_ERR_SYNTAX if there is a problem with the format of the templates buffer or file. LDAP_TMPL_ERR_FILE if the file cannot be read. 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. ldap_init_templates_buf, ldap_free_templates The ldap_init_templates_buf function reads a sequence of templates from a buffer. #include <disptmpl.h> int ldap_init_templates_buf( char *buf, long buflen, struct ldap_disptmpl **tmpllistp ); 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. If successful, 0 is returned and tmpllistp is configured. Upon error: LDAP_TMPL_ERR_VERSION if buf points to data that is newer than can be handled. LDAP_TMPL_ERR_MEM if there is a memory allocation problem. LDAP_TMPL_ERR_SYNTAX if there is a problem with the format of the templates buffer or file. LDAP_TMPL_ERR_FILE if the file cannot be read. The ldap_init_templates_buf function reads a sequence of templates from a buffer. ldap_init_templates, ldap_free_templates This function is deprecated and should not be used. It is included in ldap-to-be-deprecated.h for backward-compatibility. The ldap_is_dns_dn function determines whether a DN string is of the experimental DNS-style DN (generally in the form of an RFC 822 email address) or the RFC 1779 formatted DN. This function is specific to LDAP v2 and should not be used when dealing with LDAP v3 servers or data. More information can be found in RFC 1779 - A String Representation of Distinguished Names () and RFC 822 - Standard for the Format of ARPA Internet Text Messages (). The ldap_is_ldap_url function determines whether or not a URL is an LDAP URL. #include <ldap.h> int ldap_is_ldap_url( const char *url ); Parameter Description url The URL that you want to check. One of the following values: 1 if the URL is an LDAP URL. 0 if the URL is not an LDAP URL. The ldap_is_ldap_url function determines whether or not a URL is an LDAP URL. An LDAP URL is a URL with the protocol set to ldap:// (or ldaps://, if the server is communicating over a SSL connection). Example 21–32 determines if a URL is a LDAP URL. #include <stdio.h> #include <ldap.h> ... char *my_url = "ldap://ldap.sun.com/dc=example,dc=com"; ... if ( ldap_is_ldap_url( my_url ) != 0 ) { printf( "%s is an LDAP URL.\n", my_url ); } else { printf( "%s is not an LDAP URL.\n", my_url ); } ... ldap_url_parse The ldap_keysort_entries function is used for sorting entries. #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 ); Parameter Description ld Pointer to an LDAP structure containing information about the connection to the LDAP server. chain Chain of entries returned by the ldap_result or ldap_search_s function. arg Pointer to an additional argument that you want to pass. gen Callback used to generate the key(s) for sorting once the compare function has been applied. cmp Comparison function used when sorting the values. fre Callback used to free the key once the compare function has been applied. LDAP_KEYGEN_CALLBACK, LDAP_KEYCMP_CALLBACK, LDAP_KEYFREE_CALLBACK The ldap_memcache_destroy function frees an LDAPMemCache structure from memory. #include <ldap.h> void ldap_memcache_destroy( LDAPMemCache *cache ); Parameter Description cache Pointer to the LDAPMemCache structure that you want freed from memory. The ldap_memcache_destroy function frees the specified LDAPMemCache structure from memory. Call this function after you are done working with a cache. ldap_memcache_init The ldap_memcache_flush function flushes items from the specified cache. #include <ldap.h> void ldap_memcache_flush( LDAPMemCache *cache, char *dn, int scope ); Parameter Description cache Pointer to the LDAPMemCache structure that you want to flush entries from. dn Base DN identifying the search requests that you want flushed from the cache. If the base DN of a search request is within the scope specified by this DN and the scope argument, the search request is flushed from the cache. If this argument is NULL, the entire cache is flushed. scope Scope that (together with the dn argument) identifies the search requests that you want flushed from the cache. If the base DN of the request is within the scope specified by this argument and the dn argument, the request is flushed from the cache. This argument can have one of the following values: LDAP_SCOPE_BASE LDAP_SCOPE_ONELEVEL LDAP_SCOPE_SUBTREE 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. The ldap_memcache_get function gets the in-memory cache associated with an LDAP connection handle. #include <ldap.h> int ldap_memcache_get( LDAP *ld, LDAPMemCache **cachep ); 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. 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. 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. ldap_memcache_set The ldap_memcache_init function creates an in-memory cache for your LDAP client that you can associate with an LDAP connection. #include <ldap.h> int ldap_memcache_init( unsigned long ttl, unsigned long size, char **baseDNs, struct ldap_thread_fns *thread_fns, LDAPMemCache **cachep ); 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. 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. 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. On Windows systems, if the ldap_memcache_init function returns an LDAP_PARAM_ERROR result code, verify that your client is using the version of the nsldap32v30.dll file provided with the &DirectorySDKForC;. LDAPMemCache, ldap_memcache_set , ldap_memcache_flush, ldap_memcache_destroy, ldap_memcache_update The ldap_memcache_set function associates an in-memory cache with an LDAP connection handle. #include <ldap.h> int ldap_memcache_set( LDAP *ld, LDAPMemCache *cache ); 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. 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. 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. ldap_memcache_init, ldap_memcache_get The ldap_memcache_update function checks the cache for items that have expired and removes them. #include <ldap.h> void ldap_memcache_update( LDAPMemCache *cache ); Parameter Description cache Pointer to an LDAPMemCache structure, which represents the cache that you want to updated. The ldap_memcache_update function checks the cache for items that have expired and removes them. This check is typically done as part of the way the cache normally works. You do not need to call this function unless you want to update the cache at this point in time. This function is only useful in a multithreaded application, since it will not return until the cache is destroyed. ldap_memcache_flush The ldap_memfree function frees memory allocated by an LDAP API function call. #include <ldap.h> void ldap_memfree( void *p ); Parameter Description p Pointer to memory used by the LDAP library. Example 21–33 frees the memory allocated by the ldap_get_dn function. #include <ldap.h> ... LDAP *ld; char *dn; LDAPMessage *entry; ... /* Get the distinguished name (DN) for an entry */ dn = ldap_get_dn( ld, entry ); ... /* When you are finished working with the DN, free the memory allocated. */ ldap_memfree( dn ); ... ldap_free_friendlymap, ldap_free_urldesc, ldap_msgfree , ldap_value_free, ldap_value_free_len The ldap_modify function modifies an existing entry in the directory asynchronously. 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. #include <ldap.h> int ldap_modify( LDAP *ld, const char *dn, LDAPMod **mods ); 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 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 . Please use the newer version of this function, ldap_modify_ext . Example 21–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. #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" ); ... ldap_modify_ext The ldap_modify_ext function modifies an existing entry in the directory asynchronously. ldap_modify_ext is a new version of the ldap_modify function. If you are writing a new LDAP client, use ldap_modify_ext. #include <ldap.h> int ldap_modify_ext( LDAP *ld, const char *dn, LDAPMod **mods, LDAPControl **serverctrls, LDAPControl **clientctrls, int *msgidp ); 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. One of the following values: LDAP_SUCCESS if successful. LDAP_PARAM_ERROR if an invalid parameter was passed to the function. LDAP_ENCODING_ERROR if an error occurred when BER-encoding the control. LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost. LDAP_NO_MEMORY if memory cannot be allocated. LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function. 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 entryUse the dn argument to specify the DN of the entry you want to modify. A set of attributes for the new entryCreate 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. ldap_modify_ext_s, ldap_result, ldap_parse_result , LDAPMod The ldap_modify_ext_s modifies an existing entry in the directory synchronously. 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. #include <ldap.h> int ldap_modify_ext_s( LDAP *ld, const char *dn, LDAPMod **mods, LDAPControl **serverctrls, LDAPControl **clientctrls ); 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. One of the following values: LDAP_SUCCESS if successful. LDAP_PARAM_ERROR if an invalid parameter was passed to the function. LDAP_ENCODING_ERROR if an error occurred when BER-encoding the control. LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost. LDAP_NO_MEMORY if memory cannot be allocated. LDAP_LOCAL_ERROR if an error occurred when receiving the results from the server. LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded results from the server. LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function. &cnDirectoryServer; and other LDAP server products may send result codes in addition to those described. For example, the server may have loaded a plug-in that returns custom result codes. Check your LDAP server documentation for other result codes. The ldap_modify_ext_s modifies an entry in the directory. ldap_modify_ext_s is a synchronous function, which directly returns the results of the operation. If you want to perform other operations while waiting for the results of this operation, call the asynchronous function ldap_modify_ext instead. To make changes to an entry to the directory, you need to specify the following information: A unique DN identifying the new entryUse the dn argument to specify the DN of the entry that you want to modify. A set of attributes for the new entryCreate an LDAPMod structure for change that you want to make to an attribute. Create an array of these LDAPMod structures and pass the array as the mods argument. ldap_modify_ext, LDAPMod The ldap_modify_s function modifies an existing entry in the directory synchronously. 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. #include <ldap.h> int ldap_modify_s( LDAP *ld, const char *dn, LDAPMod **mods ); 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. For a list of possible result codes for an LDAP modify operation, see ldap_modify_ext_s. Use the newer version of this function, ldap_modify_ext_s . Example 21–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. #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 ); } ... ldap_modify_ext_s This function is deprecated and should not be used. It is included in ldap-deprecated.h for backward-compatibility. Use ldap_rename instead. This function is deprecated and should not be used. It is included in ldap-deprecated.h for backward-compatibility. Use ldap_rename_s instead. This function is deprecated and should not be used. It is included in ldap-deprecated.h for backward-compatibility. Use ldap_rename instead. The ldap_modrdn2 function changes the relative distinguished name (RDN) of an entry in the directory asynchronously. #include <ldap-deprecated.h> int ldap_modrdn2( LDAP *ld, const char *dn, const char *newrdn, int deleteoldrdn ); 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 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. Please use the newer version of this function, ldap_rename . Example 21–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. #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" ); ... ldap_rename This function is deprecated and should not be used. It is included in ldap-deprecated.h for backward-compatibility. Use ldap_rename_s instead. The ldap_modrdn2_s function changes the relative distinguished name (RDN) of an entry in the directory synchronously. #include <ldap-deprecated.h> int ldap_modrdn2_s( LDAP *ld, const char *dn, const char *newrdn, int deleteoldrdn ); 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. For a list of possible result codes, see ldap_rename_s . Please use the newer version of this function, ldap_rename_s . Example 21–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. #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 ); } ... ldap_rename_s The ldap_mods_free function frees the LDAPMod structures that you’ve allocated to add or modify entries. You need to call this function only if you’ve allocated memory for these structures yourself. For more information, see the ldap-extension.h header file. #include <ldap.h> void ldap_mods_free( LDAPMod **mods, int freemods ); 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 21–38 allocates memory for LDAPMod structures and frees them when done. #include <stdio.h> #include <ldap.h> ... LDAP *ld; char *dn; int i, msgid; LDAPMod **mods; ... /* Construct the array of values to add */ mods = ( LDAPMod ** ) malloc(( NMODS + 1 ) * sizeof( LDAPMod * )); if ( mods == NULL ) { fprintf( stderr, "Cannot allocate memory for mods array\n" ); } for ( i = 0; i < NMODS; i++ ) { if (( mods[ i ] = ( LDAPMod * ) malloc( sizeof( LDAPMod ))) == NULL) { fprintf( stderr, "Cannot allocate memory for mods element\n" ); exit( 1 ); } } ... /* Code for filling the structures goes here. */ ... /* Initiate the add operation */ if (( msgid = ldap_add( ld, dn, mods )) < 0 ) { ldap_perror( ld, "ldap_add" ); ldap_mods_free( mods, 1 ); return( 1 ); } ... The ldap_msgfree function frees the memory allocated for a result by ldap_result or ldap_search_s. #include <ldap.h> int ldap_msgfree( LDAPMessage *lm ); Parameter Description lm Pointer to the result to be freed from memory. One of the following values: LDAP_RES_BIND indicates that the LDAPMessage structure contains the result of an LDAP bind operation. LDAP_RES_SEARCH_ENTRY indicates that the LDAPMessage structure contains an entry found during an LDAP search operation. LDAP_RES_SEARCH_REFERENCE indicates that the LDAPMessage structure contains an LDAP v3 search reference (a referral to another LDAP server) found during an LDAP search operation. LDAP_RES_SEARCH_RESULT indicates that the LDAPMessage structure contains the result of an LDAP search operation. LDAP_RES_MODIFY indicates that the LDAPMessage structure contains the result of an LDAP modify operation. LDAP_RES_ADD indicates that the LDAPMessage structure contains the result of an LDAP add operation. LDAP_RES_DELETE indicates that the LDAPMessage structure contains the result of an LDAP delete operation. LDAP_RES_MODRDN or LDAP_RES_RENAME indicates that the LDAPMessage structure contains the result of an LDAP modify DN operation. LDAP_RES_COMPARE indicates that the LDAPMessage structure contains the result of an LDAP compare operation. LDAP_RES_EXTENDED indicates that the LDAPMessage structure contains the result of an LDAP v3 extended operation. LDAP_SUCCESS if the operation times out. -1 indicates that the lm argument is not a pointer to a valid LDAPMessage structure. If unsuccessful, returns the LDAP error code for the operation. Example 21–39 frees the results of a search. #include <stdio.h> #include <ldap.h> ... LDAP *ld; LDAPMessage *result; char *my_searchbase = "dc=example,dc=com"; char *my_filter = "(sn=Jensen)"; char *get_attr[] = { "cn", "mail", NULL }; ... /* Search the directory */ if ( ldap_search_s( ld, my_searchbase, LDAP_SCOPE_SUBTREE, my_filter, get_attr, 0, &result ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldap_search_s" ); return( 1 ); } ... /* Free the results when done */ ldap_msgfree( result ); ... ldap_result, ldap_search_s The ldap_msgid function determines the message ID of a result obtained by calling ldap_result or ldap_search_s. #include <ldap.h> int ldap_msgid( LDAPMessage *lm ); Parameter Description lm Pointer to the result to check. One of the following values: The message ID if successful. -1 if unsuccessful. Example 21–40 prints the message ID from the result obtained from a synchronous LDAP search operation. #include <stdio.h> #include <ldap.h> ... LDAP *ld; LDAPMessage *result; ... /* Perform a search */ if ( ldap_search_s( ld, MY_SEARCHBASE, LDAP_SCOPE_SUBTREE, MY_FILTER, NULL, 0, &result ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldap_search_s" ); return( 1 ); } /* Get and print the message ID */ if ( ldap_msgid( result ) != -1 ) { printf( "Message ID: %d\n" ); } else { printf( "An error occurred.\n" ); } ... ldap_msgtype, ldap_result , ldap_search_s C SDK functions ldap_msgtype ldap_msgtype The ldap_msgtype function determines the type of result obtained by calling ldap_result or ldap_search_s. #include <ldap.h> int ldap_msgtype( LDAPMessage *lm ); Parameter Description lm Pointer to the LDAPMessage structure to check. One of the following values: LDAP_RES_BIND indicates that the LDAPMessage structure contains the result of an LDAP bind operation. LDAP_RES_SEARCH_ENTRY indicates that the LDAPMessage structure contains an entry found during an LDAP search operation. LDAP_RES_SEARCH_REFERENCE indicates that the LDAPMessage structure contains an LDAP v3 search reference (a referral to another LDAP server) found during an LDAP search operation. LDAP_RES_SEARCH_RESULT indicates that the LDAPMessage structure contains the result of an LDAP search operation. LDAP_RES_MODIFY indicates that the LDAPMessage structure contains the result of an LDAP modify operation. LDAP_RES_ADD indicates that the LDAPMessage structure contains the result of an LDAP add operation. LDAP_RES_DELETE indicates that the LDAPMessage structure contains the result of an LDAP delete operation. LDAP_RES_MODRDN or LDAP_RES_RENAME indicates that the LDAPMessage structure contains the result of an LDAP modify DN operation. LDAP_RES_COMPARE indicates that the LDAPMessage structure contains the result of an LDAP compare operation. LDAP_RES_EXTENDED indicates that the LDAPMessage structure contains the result of an LDAP v3 extended operation. -1 indicates that the lm argument is not a pointer to a valid LDAPMessage structure. Example 21–41 prints the message type for a result obtained from a synchronous LDAP search operation. #include <stdio.h> #include <ldap.h> ... LDAP *ld; LDAPMessage *result; int msgtype; ... /* Perform a search */ if ( ldap_search_s( ld, MY_SEARCHBASE, LDAP_SCOPE_SUBTREE, MY_FILTER, NULL, 0, &result ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldap_search_s" ); return( 1 ); } /* Get and print the message type */ msgtype = ldap_msgtype( result ); if ( msgtype != -1 ) { printf( "Message type: %d\n", msgtype ); } else { printf( "An error occurred.\n" ); } ... ldap_msgid, ldap_result , ldap_search_s 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. #include <ldap.h> int ldap_multisort_entries( LDAP *ld, LDAPMessage **chain, char **attr, LDAP_CMP_CALLBACK *cmp ); 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. 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 21–42 sorts entries first by the roomNumber attribute, then by the telephoneNumber attribute. #include <stdio.h> #include <string.h> #include <ldap.h> ... LDAP *ld; LDAPMessage *result; char *my_searchbase = "dc=example,dc=com"; char *my_filter = "(sn=Jensen)"; char *attrs[3]; attrs[0] = "roomNumber"; attrs[1] = "telephoneNumber"; attrs[2] = NULL; ... /* Search the directory */ if ( ldap_search_s( ld, my_searchbase, LDAP_SCOPE_SUBTREE, my_filter, NULL, 0, &result ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldap_search_s" ); return( 1 ); } /* Sort the results, using strcasecmp */ if ( ldap_multisort_entries( ld, &result, attrs, strcasecmp ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldap_multisort_entries" ); return( 1 ); } ... ldap_result, ldap_search_s , ldap_sort_entries, LDAP_CMP_CALLBACK The ldap_name2template function obtains a pointer to the correct ldap_disptmpl structure. #include <disptmpl.h> struct ldap_disptmpl * ldap_name2template( char *name struct ldap_disptmpl *tmpllist ); Parameter Description name Name of the template. tmpllistp Pointer to a list of template data structures. If successful, 0 is returned and tmpllistp is configured. Upon error: LDAP_TMPL_ERR_VERSION if buf points to data that is newer than can be handled. LDAP_TMPL_ERR_MEM if there is a memory allocation problem. LDAP_TMPL_ERR_SYNTAX if there is a problem with the format of the templates buffer or file. LDAP_TMPL_ERR_FILE if the file cannot be read. ldap_name2template obtains a pointer to the correct ldap_disptmpl structure. Links to templates can be defined by name. The ldap_next_attribute function returns the name of the next attribute in an entry returned by ldap_first_entry or ldap_next_entry. #include <ldap.h> char * ldap_next_attribute( LDAP *ld, LDAPMessage *entry, BerElement *ber); 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. 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. 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). See the example under ldap_first_attribute. ldap_first_attribute, ldap_getfirstfilter, ldap_next_entry The ldap_next_disptmpl function returns the next template in a list. #include <disptmpl.h> struct ldap_disptmpl * ldap_next_disptmpl( struct ldap_disptmpl *tmpllist, struct ldap_disptmpl *tmpl );; 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. If successful, 0 is returned and tmpllistp is configured. Upon error: LDAP_TMPL_ERR_VERSION if buf points to data that is newer than can be handled. LDAP_TMPL_ERR_MEM if there is a memory allocation problem. LDAP_TMPL_ERR_SYNTAX if there is a problem with the format of the templates buffer or file. LDAP_TMPL_ERR_FILE if the file cannot be read. 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 . ldap_first_disptmpl The ldap_next_entry function returns a pointer to the LDAPMessage structure representing the next directory entry in a chain of search results. #include <ldap.h> LDAPMessage * ldap_next_entry( LDAP *ld, LDAPMessage *entry ); 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. 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. 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. ldap_first_entry The ldap_next_message function returns a pointer to the next LDAPMessage structure in a chain of search results. #include <ldap.h> LDAPMessage * ldap_next_message( LDAP *ld, LDAPMessage *msg ); 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. 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. 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). ldap_first_message, ldap_msgtype The ldap_next_reference function returns a pointer to the LDAPMessage structure representing the next search reference in a chain of search results. #include <ldap.h> LDAPMessage * ldap_next_reference( LDAP *ld, LDAPMessage *ref ); 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. 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. The ldap_next_reference function returns a pointer to the LDAPMessage structure representing the next search reference in a chain of search results. You can use this function in conjunction with the ldap_first_reference function to iterate through the search references in a chain of search results. These functions skip over any messages in the chain that do not have the type LDAP_RES_SEARCH_REFERENCE. Messages containing search references have the type LDAP_RES_SEARCH_REFERENCE, continuation references as specified in LDAPv3 that are stored as referral entries. Like a referral, each continuation reference itself may contain a number of URLs assumed to be equivalent, and the client should use one of those URLs. ldap_first_reference The ldap_next_searchobj function returns the following search preference in a defined list. #include <ldap.h> struct ldap_searchobj * ldap_next_searchobj ( struct ldap_searchobj *sollist, struct ldap_searchobj *so ); 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. If successful, a pointer to an ldap_searchobj structure. A NULL pointer is returned if so is the last entry in the list. The search object returned by ldap_next_searchobj follows the one defined by the so parameter. ldap_init_searchprefs, ldap_first_searchobj The ldap_next_tmplcol function returns a pointer to the following item (in the column) within a template. #include <disptmpl.h> struct ldap_tmplitem * ldap_next_tmplcol( struct ldap_disptmpl *tmpl, struct ldap_tmplitem *row, struct ldap_tmplitem *col ); 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. If successful, a pointer to an ldap_tmplitem structure. A NULL pointer on error or if col was the last item. 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. ldap_first_tmplcol The ldap_next_tmplrow function returns a pointer to the following row in a template. #include <disptmpl.h> struct ldap_tmplitem * ldap_next_tmplrow( struct ldap_disptmpl *tmpl, struct ldap_tmplitem *row ); Parameter Description tmpl The name of the template to be retrieved. row The row in the template to be retrieved. If successful, a pointer to an ldap_tmplitem structure. A NULL pointer on error. ldap_next_tmplrow returns a pointer to the row that follows the one defined by row in the template defined by tmpl . The ldap_oc2template function obtains a pointer to the correct ldap_disptmpl structure. #include <disptmpl.h> struct ldap_disptmpl * ldap_oc2template( char **oclist, struct ldap_disptmpl *tmpllist ); 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. Pointer to the first template where all of the object classes listed in one of the template's dt_oclist elements are contained in oclist. A NULL pointer if no appropriate template is found. ldap_oc2templatesearches tmpllist for the best template to use to display an entry that has a specific set of objectClass values. This function is deprecated and should not be used. Use ldap_init or prldap_init (IPv6) instead. 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. #include <ldap-deprecated.h> ldap_open( const char *host, int port ); Parameter Description host The hostname on which the LDAP server is running. It may contain a blank-separated list of hosts to try to connect to, and each host may optionally be of the form host:port. If present, port overrides the port parameter. Upon successfully making a connection to an LDAP server, ldap_open returns a pointer to an LDAP structure, which should be passed to subsequent calls ldap_bind, ldap_search port The port number to which to connect. If the default IANA-assigned port of 389 is desired, LDAP_PORT should be specified as the value of port. Please use a newer version of this function, ldap_init or prldap_init (IPv6). The ldap_parse_authzid_control function parses the authorization identity bind response control retrieved from the server to extract the authorization ID. #include <ldap.h> LDAP_API(int) LDAP_CALL ldap_parse_authzid_control( LDAP *ld, LDAPControl **ctrlp, char **authzid ); Parameter Description ld Pointer to an LDAP structure containing information about the connection to the LDAP server. ctrlp Pointer to an LDAPControl structure retrieved from the server. authzid Pointer to string holding the authorization ID. One of the following values: LDAP_SUCCESS if successful. LDAP_PARAM_ERROR if any of the arguments are invalid. LDAP_NO_MEMORY if memory cannot be allocated to decode the control returned by the server. LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded message. LDAP_CONTROL_NOT_FOUND if no control can be found in the response returned from the server. LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function. ldap_create_authzid_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). This function implements an extension to the LDAP v3. Entry change notification is an optional feature; it may not be supported on all LDAP servers. Call this function when interacting with LDAP servers that support this LDAP v3 extension. #include <ldap.h> int ldap_parse_entrychange_control( LDAP *ld, LDAPControl **ctrls, int *chgtypep, char **prevdnp, int *chgnumpresentp, long *chgnump ); Parameter Description ld Pointer to an LDAP structure containing information about the connection to the LDAP server. ctrlp An array of controls returned by the server. You obtain these controls by calling the ldap_get_entry_controls function on an entry returned by the server. changetypes Pointer to an integer specifying the type of change made to the entry. This field can have one of the following values: LDAP_CHANGETYPE_ADD specifies that the entry was added to the directory. LDAP_CHANGETYPE_DELETE specifies that the entry was deleted from the directory. LDAP_CHANGETYPE_MODIFY specifies that the entry was modified. LDAP_CHANGETYPE_MODDN specifies that the DN or RDN of the entry was changed (a modify RDN or modify DN operation was performed). prevdnp Pointer to the previous DN of the entry, if the changetypes argument is LDAP_CHANGETYPE_MODDN. If the changetypes argument has a different value, this argument is set to NULL. When done, you can free this by calling the ldap_memfree function. chgnumpresentp Pointer to an integer specifying whether or not to the change number is included in the control. The parameter can have the following possible values: 0 specifies that the change number is not included. A non-zero value specifies that the change number is included and is available as the chgnump argument. chgnump Pointer to the change number identifying the change made to the entry, if chgnumpresentp points to a non-zero value. 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. 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. ldap_create_persistentsearch_control, ldap_get_entry_controls 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. This function implements an extension to the LDAP v3. Extended operations might not be supported on all LDAP servers. Call this function only when interacting with LDAP servers that support this LDAP v3 extension. #include <ldap.h> int ldap_parse_extended_result( LDAP *ld, LDAPMessage *res, char **retoidp, struct berval **retdatap, int freeit ); Parameters Description ld Pointer to an LDAP structure containing information about the connection to the LDAP server. res Pointer to the LDAPMessage structure containing the results of an LDAP operation. retoidp Pointer to the OID returned by the server after performing the extended operation. When done, you can free this by calling the ldap_memfree function. retdatap Pointer to the pointer to a berval structure containing the data returned by the server after performing the extended operation. When done, you can free this by calling the ber_bvfree function. freeit Specifies whether or not to free the results of the operation (the LDAPMessage structure specified by the res argument). The parameter can have the following possible values: 0 specifies that the result should not be freed. A non-zero value specifies that the result should be freed. One of the following values, which indicates the result of parsing the server’s response: LDAP_SUCCESS if successful. LDAP_PARAM_ERROR if any of the arguments are invalid. LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded results from the server. LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function. This value does not apply to the operation itself. 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 . The LDAP server must support the extended operation. &cnDirectoryServer; supports a server plug-in interface that you can use to add support for extended operations. ldap_extended_operation_s, ldap_get_lderrno The ldap_parse_passwd function lets you examine the result of an LDAP Password Modify extended operation to obtain the password generated by the server when you reset a password without providing a new password value. #include <ldap.h> LDAP_API(int) LDAP_CALL ldap_parse_passwd( LDAP *ld, LDAPMessage *result, struct berval *genpasswd ); Parameter Description ld Pointer to an LDAP structure containing information about the connection to the LDAP server. result Pointer to the message retrieved using the message ID from ldap_passwd. genpasswd Pointer to the BER value structure to hold the password generated by the server. One of the following values: LDAP_SUCCESS if successful. LDAP_PARAM_ERROR if any of the arguments are invalid. LDAP_NO_MEMORY if memory cannot be allocated for the authorization identity. LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded message. LDAP_NOT_SUPPORTED if your LDAP client does not specify that it is using LDAP v3.Make sure that you set the version of your LDAP client to version 3 before calling this function. The ldap_parse_passwd_result function lets you examine the result of an LDAP Password Modify extended operation to obtain the password generated by the server when you reset a password without providing a new password value. #include <ldap.h> LDAP_API(int) LDAP_CALL ldap_parse_passwd_result( LDAP *ld, int *msgidp, struct timeval *timeout, struct berval *genpasswd ); Parameter Description ld Pointer to an LDAP structure containing information about the connection to the LDAP server. msgidp Pointer to the message ID retrieved using ldap_passwd . timeout Specifies a maximum interval to wait for the selection to complete. If timeout is a NULL pointer, the select blocks indefinitely. To effect a poll, the timeout parameter should be a non-NULL pointer, pointing to a zero-valued timeval structure. genpasswd Pointer to the BER value structure to hold the password generated by the server. One of the following values: LDAP_SUCCESS if successful. LDAP_PARAM_ERROR if any of the arguments are invalid. LDAP_NO_MEMORY if memory cannot be allocated for the authorization identity. LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded message. LDAP_NOT_SUPPORTED if your LDAP client does not specify that it is using LDAP v3.Make sure that you set the version of your LDAP client to version 3 before calling this function. The ldap_parse_pwdpolicy_control function parses information about the password policy relative to a user account contained in a control returned with a bind, add, modify, or compare result after the ldap_create_userstatus_control is used to create a request control sent to the server. The ldap_parse_pwdpolicy_control function populates an LDAPpwdpolicy structure. #include <ldap.h> LDAP_API(int) LDAP_CALL ldap_parse_pwdpolicy_control( LDAP *ld, LDAPControl **ctrlp, LDAPpwdpolicy *pp ); Parameter Description ld Pointer to an LDAP structure containing information about the connection to the LDAP server. ctrlp Pointer to an LDAPControl structure retrieved from the server. pp Pointer to an LDAPpwdpolicy structure to hold the information about password policy. One of the following values: LDAP_SUCCESS if successful. LDAP_PARAM_ERROR if any of the arguments are invalid. LDAP_NO_MEMORY if memory cannot be allocated to decode the control returned by the server. LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded message. LDAP_CONTROL_NOT_FOUND if no control can be found in the response returned from the server. LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function. ldap_create_pwdpolicy_control , LDAPpwdpolicy The ldap_parse_reference function parses search references from the results received from an LDAP server. Search references are part of the LDAP v3. When calling this function, make sure that you are working with a server that supports the LDAP v3. #include <ldap.h> int ldap_parse_reference( LDAP *ld, LDAPMessage *ref, char ***referralsp, LDAPControl ***serverctrlsp, int freeit ); Parameter Description ld Pointer to an LDAP structure containing information about the connection to the LDAP server. ref Pointer to an LDAPMessage structure of the type LDAP_RES_SEARCH_REFERENCE. referralsp Pointer to an array of strings representing the referrals found by an LDAP search operation and returned by the server (applicable only if the LDAP operation was a search operation). When done, you can free this by calling the ldap_value_free function. serverctrlsp Pointer to an array of LDAPControl structures, which represent the LDAP v3 server controls returned by the server. When done, you can free this by calling the ldap_controls_free function. freeit Specifies whether or not to free the results of the operation (the LDAPMessage structure specified by the res argument). The parameter can have the following possible values: 0 specifies that the result should not be freed. A non-zero value specifies that the result should be freed. 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. The ldap_parse_reference function parses the referral URLs from an LDAPMessage structure of the type LDAP_RES_SEARCH_REFERENCE, continuation references as specified in LDAPv3 that are stored as referral entries. Like a referral, each continuation reference itself may contain a number of URLs assumed to be equivalent, and the client should use one of those URLs. The ldap_parse_result function parses the results of an LDAP operation received from an LDAP server. #include <ldap.h> int ldap_parse_result( LDAP *ld, LDAPMessage *res, int *errcodep, char **matcheddnp, char **errmsgp, char ***referralsp, LDAPControl ***serverctrlsp, int freeit); Parameter Description ld Pointer to an LDAP structure containing information about the connection to the LDAP server. res Pointer to the LDAPMessage structure containing the results of an LDAP operation. errcodep Pointer to the LDAP result code specifying the result of the operation. matcheddnp Pointer to a string specifying the portion of a DN that finds an existing entry (in cases where the server cannot find the entry specified by a DN). When done, you can free this by calling the ldap_memfree function. errmsgp Pointer to an additional error message string sent from the server. When done, you can free this by calling the ldap_memfree function. referralsp Pointer to an array of strings representing the referrals returned by the server. When done, you can free this by calling the ldap_value_free function. serverctrlsp Pointer to an array of LDAPControl structures, which represent the LDAPv3 server controls returned by the server. When done, you can free this by calling the ldap_controls_free function. freeit Specifies whether or not to automatically free the results of the operation (the LDAPMessage structure specified by the res argument). The parameter can have the following possible values: 0 specifies that the result should not be freed. A non-zero value specifies that the result should be freed. 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. The ldap_parse_result function parses the results of an LDAP operation (received from an LDAP server) and retrieves: The LDAP result code that indicates the result of the LDAP operation (errcodep). An additional error message (optional) sent by the server (errmsgp). The portion of the DN that finds an entry, if the server is unable to find an entry from a DN that you specify (matcheddnp). A set of referrals, if the server does not contain the entries that you’ve specified and if the server is configured to refer clients to other servers (referralsp). A set of server response controls that are relevant to the operation (serverctrlsp).Calling this function creates an array of LDAPControl structures that you can pass to subsequent API functions (such as the ldap_parse_sort_control function. 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. ldap_result The ldap_parse_sasl_bind_result function parses the results of an LDAP SASL bind operation and retrieves data returned by the server. SASL authentication is part of the LDAP v3. When calling this function, make sure that you are working with a server that supports the LDAP v3. #include <ldap.h> int ldap_parse_sasl_bind_result( LDAP *ld, LDAPMessage *res, struct berval **servercredp, int freeit ); Parameter Description ld Pointer to an LDAP structure containing information about the connection to the LDAP server. res Pointer to the LDAPMessage structure containing the results of an LDAP operation. servercredp Pointer to a pointer to an berval structure containing any challenge or credentials returned by the server. When done, you can free this by calling the ber_bvfree function. freeit Specifies whether or not to free the results of the operation (the LDAPMessage structure specified by the res argument). The parameter can have the following possible values: 0 specifies that the result should not be freed. A non-zero value specifies that the result should be freed. One of the following values, which indicates the result of parsing the server’s response: LDAP_SUCCESS if successful. LDAP_PARAM_ERROR if any of the arguments are invalid. LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded message. LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function. This value does not apply to the SASL bind operation itself) 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. The LDAP server must support authentication through SASL mechanisms. &cnDirectoryServer; supports a plug-in interface that you can use to add SASL support to the server. ldap_sasl_bind, ldap_get_lderrno C SDK functions ldap_parse_sort_control 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. This function implements an extension to the LDAP v3. Server-side sorting is an optional feature; it may not be supported on all LDAP servers. Call this function when interacting with LDAP servers that support this LDAP v3 extension #include <ldap.h> int ldap_parse_sort_control( LDAP *ld, LDAPControl **ctrls, unsigned long *result, char **attribute ); 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. 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. 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. ldap_create_sort_control C SDK functions ldap_parse_userstatus_control ldap_parse_userstatus_control The ldap_parse_userstatus_control function parses information about the status of a user account contained in a control returned with an entry resulting from a search request that included the control created with ldap_create_userstatus_control . The ldap_parse_userstatus_control function populates an LDAPuserstatus structure. #include <ldap.h> LDAP_API(int) LDAP_CALL ldap_parse_userstatus_control( LDAP *ld, LDAPControl **ctrlp, LDAPuserstatus *us ); Parameter Description ld Pointer to an LDAP structure containing information about the connection to the LDAP server. ctrlp Pointer to an LDAPControl structure retrieved with ldap_get_entry_controls. us Pointer to an LDAPuserstatus structure to hold the information about account status. One of the following values: LDAP_SUCCESS if successful. LDAP_PARAM_ERROR if any of the arguments are invalid. LDAP_NO_MEMORY if memory cannot be allocated to decode the control returned by the server. LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded message. LDAP_CONTROL_NOT_FOUND if no control can be found in the response returned from the server. LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function. ldap_create_userstatus_control , LDAPuserstatus C SDK functions ldap_parse_whoami ldap_parse_whoami The ldap_parse_whoami function retrieves the authorization identity from the result of an asynchronous Who am I? extended operation request. #include <ldap.h> LDAP_API(int) LDAP_CALL ldap_parse_whoami_result( LDAP *ld, LDAPMessage *result, char **authzid ); Parameter Description ld Pointer to an LDAP structure containing information about the connection to the LDAP server. result Pointer to the message retrieved using the message ID from ldap_whoami. authzid Pointer to the string to hold the authorization identity retrieved for the connection. One of the following values: LDAP_SUCCESS if successful. LDAP_PARAM_ERROR if any of the arguments are invalid. LDAP_NO_MEMORY if memory cannot be allocated for the authorization identity. LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded message. LDAP_NOT_SUPPORTED if your LDAP client does not specify that it is using LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function. C SDK functions ldap_parse_whoami_result ldap_parse_whoami_result The ldap_parse_whoami_result function retrieves the authorization identity from the result of an asynchronous Who am I? extended operation request. #include <ldap.h> LDAP_API(int) LDAP_CALL ldap_parse_whoami_result( LDAP *ld, int *msgidp, struct timeval *timeout, char **authzid ); Parameter Description ld Pointer to an LDAP structure containing information about the connection to the LDAP server. msgidp Pointer to the message ID retrieved using ldap_whoami . timeout Specifies a maximum interval to wait for the selection to complete. If timeout is a NULL pointer, the select blocks indefinitely. To effect a poll, the timeout parameter should be a non-NULL pointer, pointing to a zero-valued timeval structure. authzid Pointer to the string to hold the authorization identity retrieved for the connection. One of the following values: LDAP_SUCCESS if successful. LDAP_PARAM_ERROR if any of the arguments are invalid. LDAP_NO_MEMORY if memory cannot be allocated for the authorization identity. LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded message. LDAP_NOT_SUPPORTED if your LDAP client does not specify that it is using LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function. C SDK functions ldap_parse_virtuallist_control ldap_parse_virtuallist_control The ldap_parse_virtuallist_control function parses the result returned from a search operation that used a server control for virtual list views. This function implements an extension to the LDAP v3. A virtual list view is an optional LDAP server feature that may not be supported on all LDAP servers. #include <ldap.h> int ldap_parse_virtuallist_control( LDAP *ld, LDAPControl **ctrls, unsigned long *target_posp, unsigned long *list_sizep, int *errcodep ); 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. One of the following values: LDAP_SUCCESS if successful. LDAP_PARAM_ERROR if any of the arguments are invalid. LDAP_NO_MEMORY if memory cannot be allocated to decode the control returned by the server. LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded message. LDAP_CONTROL_NOT_FOUND if no control can be found in the response returned from the server. LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function. 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. ldap_create_virtuallist_control C SDK functions ldap_passwd ldap_passwd The ldap_passwd asynchronous function allows you to perform an LDAP Password Modify extended operation, as defined in RFC 3062. #include <ldap.h> int ldap_passwd( LDAP *ld, struct berval *userid, struct berval *oldpasswd, struct berval *newpasswd, LDAPControl **serverctrls, LDAPControl **clientctrls, int *msgidp ); Parameter Description ld Pointer to an LDAP structure containing information about the connection to the LDAP server. userid DN of the user whose password you want to modify. oldpasswd Old password used before expiration. If the password has not yet expired, this is the current password. newpasswd New password to use after modification serverctrls Pointer to an array of LDAPControl structures representing LDAP server controls that apply to this LDAP operation. If you do not want to pass any server controls, specify NULL for this argument. clientctrls Pointer to an array of LDAPControl structures representing LDAP client controls that apply to this LDAP operation. If you do not want to pass any client controls, specify NULL for this argument. msgidp Pointer to an integer to be set to the message ID of the operation. To check the result of this operation, call the ldap_result and ldap_parse_passwd function, or ldap_parse_passwd_result function. One of the following values: LDAP_SUCCESS if successful. LDAP_PARAM_ERROR if an invalid parameter was passed to the function. LDAP_NO_MEMORY if memory cannot be allocated. LDAP_ENCODING_ERROR if an error occurred when BER-encoding the control. LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost. LDAP_NOT_SUPPORTED if your LDAP client does not specify that it is using LDAP v3.Make sure that you set the version of your LDAP client to version 3 before calling this function. C SDK functions ldap_passwd_s ldap_passwd_s The ldap_passwd_s synchronous function allows you to perform an LDAP Password Modify extended operation, as defined in RFC 3062. #include <ldap.h> int ldap_passwd_s( LDAP *ld, struct berval *userid, struct berval *oldpasswd, struct berval *newpasswd, struct berval *genpasswd, LDAPControl **serverctrls, LDAPControl **clientctrls ); Parameter Description ld Pointer to an LDAP structure containing information about the connection to the LDAP server. userid DN of the user whose password you want to modify. oldpasswd Old password used before expiration. If the password has not yet expired, this is the current password. newpasswd New password to use after modification genpasswd New password generated by the server when an expired password is reset, but no newpasswd value is provided. serverctrls Pointer to an array of LDAPControl structures representing LDAP server controls that apply to this LDAP operation. If you do not want to pass any server controls, specify NULL for this argument. clientctrls Pointer to an array of LDAPControl structures representing LDAP client controls that apply to this LDAP operation. If you do not want to pass any client controls, specify NULL for this argument. One of the following values: LDAP_SUCCESS if successful. LDAP_PARAM_ERROR if an invalid parameter was passed to the function. LDAP_NO_MEMORY if memory cannot be allocated. LDAP_ENCODING_ERROR if an error occurred when BER-encoding the control. LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost. LDAP_NOT_SUPPORTED if your LDAP client does not specify that it is using LDAP v3.Make sure that you set the version of your LDAP client to version 3 before calling this function. C SDK functions ldap_perror ldap_perror This function is deprecated and should not be used. It is included in ldap-deprecated.h for backward-compatibility. Use ldap_get_lderrno instead. The ldap_perror function prints, to standard output, the last LDAP error message. #include <ldap-deprecated.h> void ldap_perror( LDAP *ld, const char *s ); 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. Use the newer version of this function, ldap_get_lderrno . Example 21–43 prints out an error message if the search operation cannot complete successfully. ... if ( ldap_search_s( ld, my_searchbase, LDAP_SCOPE_SUBTREE, my_filter, get_attr, 0, &result ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldap_search_s" ); return( 1 ); ... ldap_get_lderrno, ldap_err2string, ldap_result2error , ldap_set_lderrno C SDK functions ldap_rename ldap_rename The ldap_rename function changes the DN of an entry in the directory asynchronously. ldap_rename is a new version of the ldap_modrdn2 function. If you are writing a new LDAP client, you should call ldap_rename. #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 ); 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. One of the following values: LDAP_SUCCESS if successful. LDAP_PARAM_ERROR if any of the arguments are invalid. LDAP_NO_MEMORY if memory cannot be allocated to decode the control returned by the server. LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request. LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost. LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function. 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. ldap_rename_s, ldap_result , ldap_parse_result C SDK functions ldap_rename_s ldap_rename_s The ldap_rename_s function changes the DN of an entry in the directory synchronously. 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. #include <ldap.h> int ldap_rename_s( LDAP *ld, const char *dn, const char *newrdn, const char *newparent, int deleteoldrdn, LDAPControl **serverctrls, LDAPControl **clientctrls ); 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. 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. &cnDirectoryServer; and other LDAP server products may send result codes in addition to those described. For example, the server may have loaded a plug-in that returns custom result codes. Check your LDAP server documentation for other result codes. 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. ldap_rename C SDK functions ldap_result 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. #include <ldap.h> int ldap_result( LDAP *ld, int msgid, int all, struct timeval *timeout, LDAPMessage **result ); Parameter Description ld Pointer to an LDAP structure containing information about the connection to the LDAP server. msgid Asynchronous functions return a unique message ID. This parameter takes message ID of the operation for which you want the results. To check any operation, pass LDAP_RES_ANY as the value of this parameter. all Specifies how the results of a search are returned. This parameter can have the following values: 0 specifies that the results are returned one entry at a time, using separate calls to ldap_result. A non-zero value specifies that all results are returned at the same time (after the final search result is obtained by the library). timeout Specifies a maximum interval to wait for the selection to complete. If timeout is a NULL pointer, the select blocks indefinitely. To effect a poll, the timeout parameter should be a non-NULL pointer, pointing to a zero-valued timeval structure. result Result of the operation. To interpret the results, pass this to the LDAP parsing routines, such as ldap_result2error, ldap_parse_result, and ldap_first_entry. One of the following values: LDAP_RES_BIND indicates that the LDAPMessage structure contains the result of an LDAP bind operation. LDAP_RES_SEARCH_ENTRY indicates that the LDAPMessage structure contains an entry found during an LDAP search operation. LDAP_RES_SEARCH_REFERENCE indicates that the LDAPMessage structure contains an LDAPv3 search reference (a referral to another LDAP server) found during an LDAP search operation. LDAP_RES_SEARCH_RESULT indicates that the LDAPMessage structure contains the result of an LDAP search operation. LDAP_RES_MODIFY indicates that the LDAPMessage structure contains the result of an LDAP modify operation. LDAP_RES_ADD indicates that the LDAPMessage structure contains the result of an LDAP add operation. LDAP_RES_DELETE indicates that the LDAPMessage structure contains the result of an LDAP delete operation. LDAP_RES_MODDN or LDAP_RES_RENAME indicates that the LDAPMessage structure contains the result of an LDAP modify DN operation. LDAP_RES_COMPARE indicates that the LDAPMessage structure contains the result of an LDAP compare operation. LDAP_RES_EXTENDED indicates that the LDAPMessage structure contains the result of an LDAP v3 extended operation. -1 indicates that an error occurred. The error code is set in the LDAP structure. To get the error code, call the ldap_get_lderrno function. 0 indicates that the operation has timed out. ldap_add_ext, ldap_compare_ext , ldap_delete_ext, ldap_modify_ext, ldap_rename, ldap_simple_bind, ldap_url_search C SDK functions ldap_result2error ldap_result2error This function is deprecated and should not be used. It is included in ldap-deprecated.h for backward-compatibility. 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. #include <ldap-deprecated.h> int ldap_result2error( LDAP *ld, LDAPMessage *r, int freeit ); Parameter Description ld Pointer to an LDAP structure containing information about the connection to the LDAP server. r Pointer to the LDAPMessage structure representing the results returned by the ldap_result or ldap_search function. freeit Specifies whether or not the result should be freed after the error code is extracted. The parameter can have the following possible values: 0 specifies that the result should not be freed. A non-zero value specifies that the result should be freed. One of the following values: If successful, sets the error code and other error information in the LDAP structure and returns the error code. If unsuccessful, returns LDAP_PARAM_ERROR. See ldap_result. ldap_parse_result, ldap_get_lderrno, ldap_err2string , ldap_result, ldap_set_lderrno C SDK functions ldap_sasl_bind ldap_sasl_bind The ldap_sasl_bind function authenticates your client to an LDAP server using an Simple Authentication and Security Layer (SASL) mechanism. The LDAP server must support authentication through SASL. &cnDirectoryServer; supports a server plug-in interface that you can use to add SASL support to the server. #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 ); 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. One of the following values: LDAP_SUCCESS if the SASL bind request was sent successfully. LDAP_PARAM_ERROR if an invalid parameter was passed to the function. LDAP_NOT_SUPPORTED if controls are included in your request—for example, as a session preference—and your LDAP client does not specify that it is using the LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function. LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request to send to the server. LDAP_NO_MEMORY if memory cannot be allocated. LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost. 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. ldap_result, ldap_parse_sasl_bind_result , ldap_get_lderrno, ldap_sasl_bind_s C SDK functions 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. The LDAP server must support authentication through SASL. &cnDirectoryServer; supports a server plug-in interface that you can use to add SASL support to the server. #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 ); 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. One of the following values: LDAP_SUCCESS if the SASL bind request was sent successfully. LDAP_PARAM_ERROR if an invalid parameter was passed to the function. LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAPv3. Make sure that you set the version of your LDAP client to version 3 before calling this function. LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request to send to the server. LDAP_DECODING_ERROR if an error occurred when the LDAP API library was decoding the BER-encoded results received from the server. LDAP_NO_MEMORY if memory cannot be allocated. LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost. LDAP_LOCAL_ERROR if an error occurred when receiving the results from the server. &cnDirectoryServer; and other LDAP server products may send result codes in addition to those described. For example, the server may have loaded a plug-in that returns custom result codes. Check your LDAP server documentation for other result codes. 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. ldap_sasl_bind C SDK functions ldap_search ldap_search The ldap_search function searches the directory asynchronously. 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. #include <ldap.h> int ldap_search( LDAP *ld, const char *base, int scope, const char* filter, char **attrs, int attrsonly ); Parameter Description ld Pointer to an LDAP structure containing information about the connection to the LDAP server. base DN of the entry that serves as the starting point for the search. For example, setting base to dc=example,dc=com restricts the search to entries at example.com. scope Scope of the search, which can be one of the following values: LDAP_SCOPE_BASE searches the entry specified by base. LDAP_SCOPE_ONELEVEL searches all entries one level beneath the entry specified by base. LDAP_SCOPE_SUBTREE searches the entry specified by base and all entries at all levels beneath the entry specified by base. filter String representation of the filter to apply in the search. You can specify simple filters with the following syntax: (attributetype= attributevalue) attrs A NULL terminated array of attribute types to return from entries that match filter. If you specify a NULL, all attributes will be returned. attrsonly Specifies whether or not attribute values are returned along with the attribute types. This parameter can have the following values: 0 specifies that both attribute types and attribute values are returned. 1 specifies that only attribute types are returned. Returns the message ID of the ldap_search operation. 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. Please use the newer version of this function, ldap_search_ext . Example 21–44 searches a directory. #include "examples.h" static void do_other_work(); unsigned long global_counter = 0; int main( int argc, char **argv ) { LDAP *ld; LDAPMessage *result, *e; BerElement *ber; char *a, *dn; char **vals; int i, rc, finished, msgid; int num_entries = 0; struct timeval zerotime; zerotime.tv_sec = zerotime.tv_usec = 0L; /* Get a handle to an LDAP connection. Use prldap_init() for IPv6. */ if ( (ld = ldap_init( MY_HOST, MY_PORT )) == NULL ) { perror( "ldap_init" ); return( 1 ); } /* authenticate to the directory as nobody */ if ( ldap_simple_bind_s( ld, NULL, NULL ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldap_simple_bind_s" ); return( 1 ); } /* search for all entries with surname of Jensen */ if (( msgid = ldap_search( ld, MY_SEARCHBASE, LDAP_SCOPE_SUBTREE, MY_FILTER, NULL, 0 )) == -1 ) { ldap_perror( ld, "ldap_search" ); return( 1 ); } /* Loop, polling for results until finished */ finished = 0; while ( !finished ) { /* * Poll for results. We call ldap_result with the "all" parameter * set to zero. This causes ldap_result() to return exactly one * entry if at least one entry is available. This allows us to * display the entries as they are received. */ result = NULL; rc = ldap_result( ld, msgid, 0, &zerotime, &result ); switch ( rc ) { case -1: /* some error occurred */ ldap_perror( ld, "ldap_result" ); return( 1 ); case 0: /* Timeout was exceeded. No entries are ready for retrieval. */ if ( result != NULL ) { ldap_msgfree( result ); } break; default: /* * Either an entry is ready for retrieval, or all entries have * been retrieved. */ if (( e = ldap_first_entry( ld, result )) == NULL ) { /* All done */ finished = 1; if ( result != NULL ) { ldap_msgfree( result ); } continue; } /* for each entry print out name + all attrs and values */ num_entries++; if (( dn = ldap_get_dn( ld, e )) != NULL ) { printf( "dn: %s\n", dn ); ldap_memfree( dn ); } for ( a = ldap_first_attribute( ld, e, &ber ); a != NULL; a = ldap_next_attribute( ld, e, ber ) ) { if (( vals = ldap_get_values( ld, e, a )) != NULL ) { for ( i = 0; vals[ i ] != NULL; i++ ) { printf( "%s: %s\n", a, vals[ i ] ); } ldap_value_free( vals ); } ldap_memfree( a ); } if ( ber != NULL ) { ldap_ber_free( ber, 0 ); } printf( "\n" ); ldap_msgfree( result ); } /* Do other work here while you are waiting... */ do_other_work(); } /* All done. Print a summary. */ printf( "%d entries retrieved. I counted to %ld " "while waiting.\n", num_entries, global_counter ); ldap_unbind( ld ); return( 0 ); } /* * Perform other work while polling for results. */ static void do_other_work() { global_counter++; } ldap_search_ext C SDK functions ldap_search_ext ldap_search_ext The ldap_search_ext function searches the directory asynchronously. 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. #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 ); Parameter Description ld Pointer to an LDAP structure containing information about the connection to the LDAP server. base DN of the entry that serves as the starting point for the search. For example, setting base to dc=example,dc=com restricts the search to entries at example.com. scope Scope of the search, which can be one of the following values: LDAP_SCOPE_BASE searches the entry specified by base. LDAP_SCOPE_ONELEVEL searches all entries one level beneath the entry specified by base. LDAP_SCOPE_SUBTREE searches the entry specified by base and all entries at all levels beneath the entry specified by base. filter String representation of the filter to apply in the search. You can specify simple filters with the following syntax: (attributetype= attributevalue) attrs A NULL terminated array of attribute types to return from entries that match filter. If you specify a NULL, all attributes will be returned. attrsonly Specifies whether or not attribute values are returned along with the attribute types. This parameter can have the following values: 0 specifies that both attribute types and attribute values are returned. 1 specifies that only attribute types are returned. serverctrls Pointer to an array of LDAPControl structures representing LDAP server controls that apply to this operation. If you do not want to pass any server controls, specify NULL for this argument. clientctrls Pointer to an array of LDAPControl structures representing LDAP client controls that apply to this operation. If you do not want to pass any client controls, specify NULL for this argument. timeoutp Pointer to a timeval structure specifying the maximum time to wait for the results of the search. Pass NULL to use the default time limit for the current connection. To specify an infinite time limit, set the tv_sec and tv_usec fields in the timeval structure to 0. sizelimit Maximum number of results to return in the search. Pass -1 to use the default size limit for the current connection. msgidp Pointer to an integer that will be set to the message ID of the LDAP operation. One of the following values: LDAP_SUCCESS if the SASL bind request was sent successfully. LDAP_PARAM_ERROR if an invalid parameter was passed to the function. LDAP_NOT_SUPPORTED if controls are included in your request—for example, as a session preference—and your LDAP client does not specify that it is using the LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function. LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request to send to the server. LDAP_NO_MEMORY if memory cannot be allocated. LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost. 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. ldap_search_ext_s, ldap_result, ldap_parse_result C SDK functions ldap_search_ext_s ldap_search_ext_s The ldap_search_ext_s function searches the directory synchronously. 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. #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 ); Parameter Description ld Pointer to an LDAP structure containing information about the connection to the LDAP server. base DN of the entry that serves as the starting point for the search. For example, setting base to dc=example,dc=com restricts the search to entries at example.com. scope Scope of the search, which can be one of the following values: LDAP_SCOPE_BASE searches the entry specified by base. LDAP_SCOPE_ONELEVEL searches all entries one level beneath the entry specified by base. LDAP_SCOPE_SUBTREE searches all entries at all levels beneath the entry specified by base. filter String representation of the filter to apply in the search. You can specify simple filters with the following syntax: (attributetype= attributevalue) attrs A NULL terminated array of attribute types to return from entries that match filter. If you specify a NULL, all attributes will be returned. attrsonly Specifies whether or not attribute values are returned along with the attribute types. This parameter can have the following values: 0 specifies that both attribute types and attribute values are returned. 1 specifies that only attribute types are returned. serverctrls Pointer to an array of LDAPControl structures representing LDAP server controls that apply to this operation. If you do not want to pass any server controls, specify NULL for this argument. clientctrls Pointer to an array of LDAPControl structures representing LDAP client controls that apply to this operation. If you do not want to pass any client controls, specify NULL for this argument. timeoutp Pointer to a timeval structure specifying the maximum time to wait for the results of the search. sizelimit Maximum number of results to return in the search. res Results of the search (when the call is completed). One of the following values: LDAP_SUCCESS if the SASL bind request was sent successfully. LDAP_PARAM_ERROR if an invalid parameter was passed to the function. LDAP_NOT_SUPPORTED if controls are included in your request—for example, as a session preference—and your LDAP client does not specify that it is using the LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function. LDAP_FILTER_ERROR if an error occurred when parsing and BER-encoding the search filter specified by the filter argument. LDAP_TIMEOUT if the search exceeded the time specified by the timeoutp argument. LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request to send to the server. LDAP_DECODING_ERROR if an error occurred when the LDAP API library was decoding the BER-encoded results received from the server. LDAP_NO_MEMORY if memory cannot be allocated. LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost. LDAP_LOCAL_ERROR if an error occurred when receiving the results from the server. &cnDirectoryServer; and other LDAP server products may send result codes in addition to those described. For example, the server may have loaded a plug-in that returns custom result codes. Check your LDAP server documentation for other result codes. 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.) ldap_search_ext C SDK functions ldap_search_s ldap_search_s The ldap_search_s function searches the directory synchronously. 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. #include <ldap.h> int ldap_search_s( LDAP *ld, const char *base, int scope, const char* filter, char **attrs, int attrsonly, LDAPMessage **res ); This function has the parameters listed in ldap_search_s . Parameter Description ld Pointer to an LDAP structure containing information about the connection to the LDAP server. base DN of the entry that serves as the starting point for the search. For example, setting base to dc=example,dc=com restricts the search to entries at example.com. scope Scope of the search, which can be one of the following values: LDAP_SCOPE_BASE searches the entry specified by base. LDAP_SCOPE_ONELEVEL searches all entries one level beneath the entry specified by base. LDAP_SCOPE_SUBTREE searches all entries at all levels beneath the entry specified by base. filter String representation of the filter to apply in the search. You can specify simple filters with the following syntax: (attributetype=attributevalue) attrs A NULL terminated array of attribute types to return from entries that match filter. If you specify a NULL, all attributes will be returned. attrsonly Specifies whether or not attribute values are returned along with the attribute types. This parameter can have the following values: 0 specifies that both attribute types and attribute values are returned. 1 specifies that only attribute types are returned. res Results of the search (when the call is completed). For a list of possible result codes for an LDAP search operation, see ldap_search_ext_s. Use the newer version of this function, ldap_search_ext_s . Example 21–45 searches the directory for all people whose surname (last name) is Jensen. #include "examples.h" int main( int argc, char **argv ) { LDAP *ld; LDAPMessage *result, *e; BerElement *ber; char *a, *dn; char **vals; int i; /* Get a handle to an LDAP connection. Use prldap_init() for IPv6. */ if ( (ld = ldap_init( MY_HOST, MY_PORT )) == NULL ) { perror( "ldap_init" ); return( 1 ); } /* authenticate to the directory as nobody */ if ( ldap_simple_bind_s( ld, NULL, NULL ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldap_simple_bind_s" ); return( 1 ); } /* search for all entries with surname of Jensen */ if ( ldap_search_s( ld, MY_SEARCHBASE, LDAP_SCOPE_SUBTREE, MY_FILTER, NULL, 0, &result ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldap_search_s" ); return( 1 ); } /* for each entry print out name + all attrs and values */ for ( e = ldap_first_entry( ld, result ); e != NULL; e = ldap_next_entry( ld, e ) ) { if ( (dn = ldap_get_dn( ld, e )) != NULL ) { printf( "dn: %s\n", dn ); ldap_memfree( dn ); } for ( a = ldap_first_attribute( ld, e, &ber ); a != NULL; a = ldap_next_attribute( ld, e, ber ) ) { if ((vals = ldap_get_values( ld, e, a)) != NULL ) { for ( i = 0; vals[i] != NULL; i++ ) { printf( "%s: %s\n", a, vals[i] ); } ldap_value_free( vals ); } ldap_memfree( a ); } if ( ber != NULL ) { ldap_ber_free( ber, 0 ); } printf( "\n" ); } ldap_msgfree( result ); ldap_unbind( ld ); return( 0 ); } ldap_search_ext_s C SDK functions ldap_search_st ldap_search_st The ldap_search_st function searches the directory synchronously within a specified time limit. 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. #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 ); Parameter Description ld Pointer to an LDAP structure containing information about the connection to the LDAP server. base DN of the entry that serves as the starting point for the search. For example, setting base to dc=example,dc=com restricts the search to entries at example.com. scope Scope of the search, which can be one of the following values: LDAP_SCOPE_BASE searches the entry specified by base. LDAP_SCOPE_ONELEVEL searches all entries one level beneath the entry specified by base. LDAP_SCOPE_SUBTREE searches all entries at all levels beneath the entry specified by base. filter String representation of the filter to apply in the search. You can specify simple filters with the following syntax: (attributetype=attributevalue) attrs A NULL terminated array of attribute types to return from entries that match filter. If you specify a NULL, all attributes will be returned. attrsonly Specifies whether or not attribute values are returned along with the attribute types. This parameter can have the following values: 0 specifies that both attribute types and attribute values are returned. 1 specifies that only attribute types are returned. timeout Maximum time to wait for the results of the search. res Results of the search (when the call is completed). For a list of possible result codes for an LDAP search operation, see ldap_search_ext_s. Please use the newer version of this function, ldap_search_ext_s . ldap_search_ext_s C SDK functions ldap_set_filter_additions 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. #include <ldap.h> int ldap_set_filter_additions( LDAPFiltDesc *lfdp, char *prefix, char *suffix ); 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. One of the following values: LDAP_SUCCESS if successful. If unsuccessful, returns an LDAP error code. Example 21–46 loads the filter configuration file named myfilters.conf into memory and adds the prefix "(&(objectClass=person)" and the suffix ")" to each filter retrieved. #include <ldap.h> ... LDAPFiltDesc *lfdp; char *filter_file = "myfilters.conf"; char *prefix = "(&(objectClass=person)"; char *suffix = ")"; int rc; ... lfdp = ldap_init_getfilter( filter_file ); rc = ldap_set_filter_additions( ldfp, prefix, suffix ); if ( rc != LDAP_SUCCESS ) { printf( "Error setting filter prefix and suffix\n"); return( rc ); } ... ldap_getfirstfilter, ldap_getnextfilter C SDK functions ldap_setfilteraffixes ldap_setfilteraffixes This function is deprecated and should not be used. It is included in ldap-deprecated.h for backward-compatibility. Use ldap_set_filter_additions instead. ldap_set_filter_additions C SDK functions ldap_set_lderrno ldap_set_lderrno The ldap_set_lderrno function sets an error code and information about an error in an LDAP structure. #include <ldap.h> int ldap_set_lderrno( LDAP *ld, int e, char *m, char *s ); Parameter Description ld Pointer to an LDAP structure containing information about the connection to the LDAP server. e The error code that you want to set. m In the event that an entry for a specified DN cannot be found, set this parameter to the portion of the DN that identifies an existing entry. s The text of the error message that you want associated with this error code. One of the following values: LDAP_SUCCESS if successful. If unsuccessful, returns an LDAP error code. The ldap_set_lderrno function sets an error code and information about an error in an LDAP structure. You can call this function to set error information that will be retrieved by subsequent ldap_get_lderrno function calls. Example 21–47 attempts to perform an operation. If the operation fails, the LDAP_PARAM_ERROR error code is placed in the LDAP structure. #include <ldap.h> int rc; char *errmsg = "Invalid parameter"; ... if ( ldap_my_function() != LDAP_SUCCESS ) { rc = ldap_set_lderrno( ld, LDAP_PARAM_ERROR, NULL, errmsg ); if ( rc != LDAP_SUCCESS ) { printf( "Error: %d\nError code could not be set.\n", rc ); } return( rc ); } ... ldap_err2string, ldap_perror, ldap_result2error C SDK functions ldap_set_option ldap_set_option The function ldap_set_option sets session preferences in the LDAP structure. #include <ldap.h> int ldap_set_option( LDAP *ld, int option, const void *optdata ); Parameter Description ld Pointer to an LDAP structure containing information about the connection to the LDAP server. If NULL, you are setting the default options that will apply to any new LDAP connection handles that are subsequently created. option Option that you want to set. See Table 21–182 for available options of this parameter. optdata Pointer to the value of the option that you want to set. Available data types are also listed in Table 21–182. The option parameter can have one of the values listed in Table 21–182. Option Description LDAP_OPT_API_FEATURE_INFO Retrieves information about the revision of a supported LDAP feature. This option is READ-ONLY and cannot be set. The data type for the optdata parameter is (LDAPAPIFeatureInfo *). LDAP_OPT_API_INFO Retrieves information about the API implementation at execution time (API version, protocol version, the names of supported API extensions with their vendor name version, etc.). For details on the structure returned, refer to the ldap.h header file. This option is READ-ONLY and cannot be set. The data type for the optdata parameter is (LDAPAPIInfo *). LDAP_OPT_CLIENT_CONTROLS Pointer to an array of LDAPControl structures representing the LDAP v3 client controls you want sent with every request by default. The data type for the optdata parameter is (LDAPControl ***). LDAP_OPT_DESC Socket descriptor underlying the main LDAP connection. The LBER_SOCKET data type depends on the platform that you are using: int in UNIX. SOCKET in Windows.The data type for the optdata parameter is (LBER_SOCKET *). LDAP_OPT_DEREF Determines how aliases work during a search. optdata can be one of the following values: LDAP_DEREF_NEVER specifies that aliases are never dereferenced. LDAP_DEREF_SEARCHING specifies that aliases are dereferenced when searching under the base object (but not when finding the base object). LDAP_DEREF_FINDING specifies that aliases are dereferenced when finding the base object (but not when searching under the base object). LDAP_DEREF_ALWAYS specifies that aliases are always dereferenced when finding and searching under the base object. The data type for the optdata parameter is (int *). LDAP_OPT_DNS_FN_PTRS DEPRECATED OPTION: Lets you use alternate DNS functions for getting the host entry of the LDAP server. The data type for the optdata parameter is (struct ldap_dns_fns *). LDAP_OPT_ERROR_NUMBER Retrieves the result code for the most recent LDAP error that occurred in this session. The data type for the optdata parameter is (int *). LDAP_OPT_ERROR_STRING Retrieves the error message returned with the result code for the most recent LDAP error that occurred in this session. The data type for the optdata parameter is (char **). LDAP_OPT_EXTRA_THREAD_FN_PTRS Lets you specify the locking and semaphore functions that you want called when getting results from the server. The data type for the optdata parameter is (struct ldap_extra_thread_fns *). LDAP_OPT_HOST_NAME Sets the host name (or list of hosts) for the primary LDAP server. The data type for the optdata parameter is (char **). LDAP_OPT_IO_FN_PTRS DEPRECATED OPTION: Lets you use alternate communication stacks. The data type for the optdata parameter is (struct ldap_io_fns *). LDAP_OPT_MATCHED_DN Gets the matched DN value returned with the most recent LDAP error that occurred for this session. The data type for the optdata parameter is (char **) LDAP_OPT_MEMALLOC_FN_PTRS Gets a pointer to the callback structure which you previously set. The data type for the optdata parameter is (struct ldap_memalloc_fnsldap_io_fns *). LDAP_OPT_PROTOCOL_VERSION Version of the protocol supported by your client. You can specify either LDAP_VERSION2 or LDAP_VERSION3. If no version is set, the default is LDAP_VERSION2. In order to use LDAP v3 features, you need to set the protocol version to LDAP_VERSION3. The data type for the optdata parameter is (int *). LDAP_OPT_REBIND_ARG Lets you set the last argument passed to the routine specified by LDAP_OPT_REBIND_FN. You can also set this option by calling the ldap_set_rebind_proc function. The data type for the optdata parameter is (void *). LDAP_OPT_REBIND_FN Lets you set the routine to be called when you need to authenticate a connection with another LDAP server (for example, during the course of following a referral). You can also set this option by calling the ldap_set_rebind_proc function. The data type for the optdata parameter is (LDAP_REBINDPROC_CALLBACK *). LDAP_OPT_RECONNECT If the connection to the server is lost, determines whether or not the same connection handle should be used to reconnect to the server. By default, this option is off. To handle failover use following values: LDAP_OPT_ON specifies that the same connection handle can be used to reconnect to the server. LDAP_OPT_OFF specifies that you want to create a new connection handle to connect to the server.The data type for the optdata parameter is (int *). LDAP_OPT_REFERRALS Determines whether or not the client should follow referrals. By default, the client follows referrals. optdata can be one of the following values: LDAP_OPT_ON specifies that the server should follow referrals. LDAP_OPT_OFF specifies that the server should not follow referrals.The data type for the optdata parameter is (int *). LDAP_OPT_REFERRAL_HOP_LIMIT Maximum number of referrals the client should follow in a sequence. In other words, the client can only be referred this number of times before it gives up. By default, the maximum number of referrals that the client can follow in a sequence is 5 for the initial connection. This limit does not apply to individual requests that generate multiple referrals in parallel. The data type for the optdata parameter is (int *). LDAP_OPT_RESTART Determines whether or not LDAP I/O operations should be restarted automatically if they are prematurely aborted. optdata can be one of the following values: LDAP_OPT_ON specifies that I/O operations should be restarted automatically. LDAP_OPT_OFF specifies that I/O operations should not be restarted automatically.The data type for the optdata parameter is (int *). LDAP_OPT_SERVER_CONTROLS Pointer to an array of LDAPControl structures representing the LDAP v3 server controls you want sent with every request by default. Typically, since controls are specific to the type of request, you may want to pass the controls using operation-specific functions (such as ldap_add_ext) instead. The data type for the optdata parameter is (LDAPControl ***). LDAP_OPT_SIZELIMIT Maximum number of entries that should be returned by the server in search results. The LDAP server may impose a smaller size limit than the limit you specify as the server administrator also has the ability to set this limit. The data type for the optdata parameter is (int *). LDAP_OPT_SSL Determines whether or not SSL is enabled. optdata can be one of the following values: LDAP_OPT_ON specifies that SSL is enabled. LDAP_OPT_OFF specifies that SSL is disabled. The data type for the optdata parameter is (int *). LDAP_OPT_THREAD_FN_PTRS Lets you specify the thread function pointers. The data type for the optdata parameter is (struct ldap_thread_fns *). LDAP_OPT_TIMELIMIT Maximum number of seconds that should be spent by the server when answering a search request. The LDAP server may impose a shorter time limit than the limit you specify as the server administrator also has the ability to set this limit. The data type for the optdata parameter is (int *). LDAP_X_OPT_EXTIO_FN_PTRS Extended I/O function callback option. LDAP_X_OPT_CONNECT_TIMEOUT Value of a time out (expressed in milliseconds) for non-blocking connect call. The data type for the optdata parameter is (int *). LDAP_X_OPT_SOCKBUF Socket buffer structure associated to the LDAP connection. See also ldap_set_option 3LDAP for details on LDAP_OPT_X_SASL* parameters. One of the following values: LDAP_SUCCESS if successful. -1 if unsuccessful. #include <stdio.h> #include <ldap.h> ... LDAP *ld; int max_ret = 100, max_tim = 30; char *host = "ldap.sun.com"; ... /* Initialize a session with the LDAP server ldap.sun.com:389 */ /* Use prldap_init() for IPv6 support. */ if ( ( ld = ldap_init( host, LDAP_PORT ) ) == NULL ) { perror( "ldap_init" ); return( 1 ); } /* Set the maximum number of entries returned */ if ( ldap_set_option( ld, LDAP_OPT_SIZELIMIT, &max_ret) ! LDAP_SUCCESS) { ldap_perror( ld, "ldap_set_option" ); return( 1 ); } ... ldap_init, prldap_init (IPv6), ldap_get_option C SDK functions ldap_set_rebind_proc 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. #include <ldap.h> void ldap_set_rebind_proc( LDAP *ld, LDAP_REBINDPROC_CALLBACK *rebindproc, void *arg ); 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. 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 ); 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 &DirectorySDKForC; 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: The dnp argument is set to point to the DN to be used to authenticate to the new LDAP server. The passwdp argument is set to point to the credentials for this DN. The authmethodp argument is set to point to the method of authentication used (for example, LDAP_AUTH_SIMPLE). If successful, the rebind function returns LDAP_SUCCESS , and referral processing continues. (If any other value is returned, referral processing stops, and that value is returned as the result code for the original LDAP request.) The client gets the DN, credentials, and authentication method from the arguments of the rebind function and uses this information to authenticate to the new LDAP server. The client calls the rebind function again, passing 1 as the freeit argument. The rebind function frees any memory allocated earlier to specify the DN and credentials.You need to write a rebind function that does the following: If freeit is 0, set the following pointers: Set dnp to point to the DN to be used for authentication. Set passwdp to point to the credentials to be used for authentication. Set authmethodp to point to the method of authentication used (for example, LDAP_AUTH_SIMPLE). You can also make use of the arg argument, which is a pointer to the argument specified in the ldap_set_rebind_proc function. If successful, returns LDAP_SUCCESS. Otherwise, returns the appropriate LDAP error code. If freeit is 1, free any memory that you allocated to create the DN and credentials.After you have defined this function, pass the function name to ldap_set_rebind_proc to register your rebind function. 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 21–49 demonstrates how to write and register a rebind function. #include "ldap.h" ... /* Declare your rebind function */ int rebindproc( LDAP *ld, char **dnp, char **passwdp, int *authmethodp, int freeit, void *arg ); ... int main( int argc, char **argv ) { LDAP *ld; /* Additional argument to be passed to the rebind function */ char *testarg = "cn=admin,cn=Administrators,cn=config"; /* Get a handle to an LDAP connection. Use prldap_init() for IPv6. */ if ( (ld = ldap_init( "directory.example.com", 389 )) == NULL ) { perror( "ldap_init" ); return( 1 ); } /* Specify the function used for reauthentication on referrals */ ldap_set_rebind_proc( ld, rebindproc, (void *)testarg ); /* Authenticate */ if ( ldap_simple_bind_s( ld, "uid=bjensen,ou=People,dc=example,dc=com", "hifalutin" ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldap_simple_bind_s" ); return( 1 ); } ... /* Your code to interact with the LDAP server */ ... } ... /* rebindproc is the rebind function responsible for providing the DN, credentials, and authentication method used for authenticating the client to other Directory Servers. The function should set the following arguments: - dnp should point to the DN that will be used for authentication. - passwdp should point to the credentials used for authentication. - authmethodp should point to the method of authentication to be used (for example, LDAP_AUTH_SIMPLE). The function should return LDAP_SUCCESS if successful or an LDAP error code if an error occurs. In order to demonstrate how the freeit argument works, this example uses strdup() to copy the DN and password. You can also just copy string pointers if the DN and password are already available as global variables. */ int LDAP_CALL LDAP_CALLBACK rebindproc( LDAP *ld, char **dnp, char **passwdp, int *authmethodp, int freeit, void *arg ) { printf( "Rebind function called.\n" ); switch ( freeit ) { /* Your client calls the rebind function with freeit==1 when it needs to free any memory you've allocated. */ case 1: printf( "\tFreeing memory.\n" ); if ( dnp && *dnp ) { free( *dnp ); } if ( passwdp && *passwdp ) { free( *passwdp ); } break; /* Your client calls the rebind function with freeit==0 when it needs to get the DN, credentials, and authentication method. */ case 0: printf( "\tGetting DN and credentials.\n" ); *dnp = strdup( "uid=username,o=OtherServerSuffix" ); *passwdp = strdup( "23skidoo" ); *authmethodp = LDAP_AUTH_SIMPLE; break; default: printf( "\tUnknown value of freeit argument: %d\n", freeit ); break; } /* If you successfully set the DN and credentials, you should return LDAP_SUCCESS. (Any other return code will stop the client from automatically following the referral. */ return LDAP_SUCCESS; } ldap_simple_bind, ldap_simple_bind_s C SDK functions ldap_simple_bind ldap_simple_bind The ldap_simple_bind function synchronously authenticates your client to the LDAP server using a DN and a password. #include <ldap.h> int ldap_simple_bind(LDAP *ld, const char *who, const char *passwd); 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 the message ID of the ldap_simple_bind operation. To check the result of this operation, call ldap_result and ldap_result2error. 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. 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. The use of this function may be a security threat if used on a non-secured connection as the password is transmitted in clear text. 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 21–50 calls ldap_simple_bind to authenticate the user Barbara Jensen to the directory. #include <stdio.h> #include <ldap.h> ... LDAP *ld; char *host = "ldap.sun.com"; char *dn = "uid=bjensen,ou=People,dc=example,dc=com"; char *pw = "hifalutin"; struct timeval zerotime; zerotime.tv_sec = zerotime.tv_usec = 0L; ... /* Initialize a session with the LDAP server ldap.example.com:389 */ /* Use prldap_init() for IPv6 support. */ if ( ( ld = ldap_init( host, LDAP_PORT ) ) == NULL ) { perror( "ldap_init" ); return( 1 ); } /* Attempt to bind with the LDAP server */ msgid = ldap_simple_bind( ld, dn, pw ); /* Initialize the value returned by ldap_result() */ rc = 0; /* While the operation is still running, do this: */ while ( rc == 0 ) { ... /* do other work while waiting */... /* Check the status of the LDAP operation */ rc = ldap_result( ld, msgid, NULL, &zerotime, &result ); switch( rc ) { /* If -1 was returned, an error occurred */ case -1: ldap_perror( ld, "Error in results: " ); return( 1 ); /* If 0 was returned, the operation is still in progress */ case 0: continue; /* If any other value is returned, assume we are done */ default: /* Check if the "bind" operation was successful */ if ( ldap_result2error( result ) != LDAP_SUCCESS ) { ldap_perror( ld, "Error binding to server: " ); return( 1 ); } } } ... ldap_simple_bind_s C SDK functions ldap_simple_bind_s ldap_simple_bind_s The ldap_simple_bind function synchronously authenticates your client to the LDAP server using a DN and a password. #include <ldap.h> int ldap_simple_bind_s( LDAP *ld, const char *who, const char *passwd ); 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. One of the following values: LDAP_SUCCESS if successful. LDAP_PARAM_ERROR if an invalid parameter was passed to the function. LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function. LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request to send to the server. LDAP_DECODING_ERROR if an error occurred when the LDAP API library was decoding the BER-encoded results received from the server. LDAP_NO_MEMORY if memory cannot be allocated. LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost. LDAP_LOCAL_ERROR if an error occurred when receiving the results from the server. &cnDirectoryServer; and other LDAP server products may send result codes in addition to those described. For example, the server may have loaded a plug-in that returns custom result codes. Check your LDAP server documentation for other result codes. 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. 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. The use of this function may be a security threat if used on a non-secured connection as the password is transmitted in clear text. 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 21–51 uses the synchronous ldap_simple_bind_s function to authenticate to the directory as the user Barbara Jensen. #include <stdio.h> #include <ldap.h> ... LDAP *ld; char *host = "ldap.sun.com"; char *dn = "uid=bjensen,ou=People,dc=example,dc=com"; char *pw = "hifalutin"; ... /* Initialize a session with the LDAP server ldap.sun.com:389 */ /* Use prldap_init() for IPv6 support. */ if ( ( ld = ldap_init( host, LDAP_PORT ) ) == NULL ) { perror( "ldap_init" ); return( 1 ); } /* Attempt to bind with the LDAP server */ if ( ldap_simple_bind_s( ld, dn, pw ) != LDAP_SUCCESS ) { ldap_perror( ld, "Authentication failed: " ); return( 1 ); } ... ldap_simple_bind C SDK functions ldap_sort_entries ldap_sort_entries The ldap_sort_entries function sorts a chain of entries retrieved from an LDAP search call. #include <ldap.h> int ldap_sort_entries( LDAP *ld, LDAPMessage *chain, char *attr, LDAP_CMP_CALLBACK *cmp ); 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. 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. The ldap_sort_entries function sorts a chain of entries retrieved from an LDAP search call (ldap_search_s or ldap_result) either by DN or a specified attribute in the entries. Example 21–52 sorts entries by the roomNumber attribute. #include <stdio.h> #include <string.h> #include <ldap.h> LDAP *ld; LDAPMessage *result; char *my_searchbase = "dc=example,dc=com"; char *my_filter = "(sn=Jensen)"; char *sortby = "roomNumber"; ... /* Search the directory */ if ( ldap_search_s( ld, my_searchbase, LDAP_SCOPE_SUBTREE, my_filter, NULL, 0, &result ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldap_search_s" ); return( 1 ); } /* Sort the results by room number, using strcasecmp */ if ( ldap_sort_entries( ld, &result, sortby, strcasecmp ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldap_sort_entries" ); return( 1 ); } ... ldap_multisort_entries, ldap_result, ldap_search_s, LDAP_CMP_CALLBACK C SDK functions ldap_start_tls_s ldap_start_tls_s The ldap_start_tls_s initiates a Start Transport Layer Security (TLS) operation as defined in RFC 4513. Before using this function, call ldapssl_client_init , ldapssl_clientauth_init, or ldapssl_advclientauth_init to initialize use of the certificate database. #include <ldap_ssl.h> int ldap_start_tls_s( LDAP *ld, LDAPControl **serverctrls, LDAPControl **clientctrls ); 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. One of the following values: LDAP_SUCCESS if successful. LDAP_OPERATIONS_ERROR if TLS has already been established. LDAP_PROTOCOL_ERROR if TLS is not supported. LDAP_REFERRAL if this server does not support TLS, but the server referred to may. LDAP_UNAVAILABLE if the server is shutting down, or supports TLS but cannot provide it at this time. C SDK functions ldap_sort_strcasecmp ldap_sort_strcasecmp The ldap_sort_strcasecmp routine compares two strings and ignores any differences in case when comparing uppercase and lowercase characters. #include <ldap.h> int ldap_sort_strcasecmp( const char **a, const char **b ); Parameter Description a Pointer to first string to compare b Pointer to second string to compare One of the following values: If a is greater than b, returns a value greater than 0. If a is equal to b, returns 0. If a is less than b, returns a value less than 0. 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. This function works with ASCII values only. For UTF-8 data, the comparison result is unspecified. ldap_sort_strcasecmp, LDAP_VALCMP_CALLBACK C SDK functions ldap_sort_values ldap_sort_values The ldap_sort_values function sorts an array of values retrieved from an ldap_get_values call. #include <ldap.h> int ldap_sort_values( LDAP *ld, char **vals, LDAP_VALCMP_CALLBACK cmp ); 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. One of the following values: LDAP_SUCCESS if successful. If unsuccessful, returns an LDAP error code. Example 21–53 sorts the values of attributes before printing them. #include <stdio.h> #include <string.h> #include <ldap.h> ... LDAP *ld; LDAPMessage *result, *e; BerElement *ber; char *a, *dn; char **vals; int i; char *my_searchbase = "dc=example,dc=com"; char *my_filter = "(sn=Jensen)"; ... if ( ( vals = ldap_get_values( ld, e, a ) ) != NULL ) { /* Sort the values of the attribute */ if ( ldap_sort_values( ld, vals, strcasecmp ) ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldap_sort_values" ); return( 1 ); } /* Print the values of the attribute */ for ( i = 0; vals[i] != NULL; i++ ) { printf( "%s: %s\n", a, vals[i] ); } /* Free the values from memory */ ldap_value_free( vals ); } ... ldap_get_values, ldap_sort_strcasecmp, LDAP_VALCMP_CALLBACK. C SDK functions ldap_ldapssl_* ldap_ldapssl_* 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. #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); Please see the description of the sslstrength value and note the potential problems that can be caused by passing in wrong host and port name values. Parameter Description certdbpath Specifies the path to the database containing certificates for your client. You can include the database filename in the path (for example, /usr/mozilla/ cert_file_name.db). certdbhandle Pass a NULL value for this. (This parameter is not currently used.) needkeydb Specifies whether or not the private key database needs to be opened for use. This parameter can have one of the following values: If it is a non-zero value, the function opens the private key database, which is identified by the keydbpath argument. If 0, the function does not open the private key database. keydbpath Specifies the path to the database containing the private key certified by your certificate. You can include the database filename in the path (for example, /usr/mozilla/key_file_name .db). needsecmoddb Specifies whether or not the security module database file needs to be opened for use. This parameter can have one of the following values: If it is a non-zero value, the function opens the security module database, which is identified by the keydbpath argument. If 0, the function does not open the security modules database. secmodpath Path to the database containing security modules. You can include the database filename in the path (for example, /usr/mozilla/ secmod_file_name .db). sslstrength Specifies how the server certificate is evaluated. It takes one of the following: LDAPSSL_AUTH_WEAK indicates that you accept the server’s certificate without checking the for certificate authority (CA) that issued the certificate. LDAPSSL_AUTH_CERT indicates that you accept the server’s certificate only if you trust the CA that issued the certificate. LDAPSSL_AUTH_CNCHECK indicates that you accept the server’s certificate only if you trust the CA that issued the certificate and if the value of the cn attribute is the DNS hostname of the server. If this option is selected, ensure that the defhost parameter passed to ldapssl_init consists of only one hostname and not a list of hosts. Furthermore, the port number must be passed via the defport parameter, and cannot be passed via a host: port option. One of the following values: 0 if successful. -1 if unsuccessful. 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. You must call ldapssl_advclientauth_init before calling ldapssl_init to connect to the server. Example 21–54 initializes a client before connecting with a secure LDAP server. #include <ldap.h> #include <ldap_ssl.h> #include <stdio.h> ... /* Initialize client, using mozilla’s certificate database */ if ( ldapssl_advclientauth_init( "/u/mozilla/.netscape/ cert_file_name.db", NULL, 1, "/u/mozilla/.netscape/ key_file_name.db", NULL , 1, "/u/mozilla/.netscape/ secmod_file_name.db", LDAPSSL_AUTH_CNCHECK) < 0 ) { perror( "ldap_advclientauth_init" ); return( 1 ); } } ... ldap_init, prldap_init (IPv6), ldapssl_clientauth_init, ldapssl_init, ldapssl_install_routines 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. #include <ldap_ssl.h> int ldapssl_client_init( const char *certdbpath, void *certdbhandle ); Parameter Description certdbpath Specifies the path to the database containing certificates for your client. certdbhandle Pass a NULL value for this. (This parameter is not used currently.) One of the following values: 0 if successful. -1 if unsuccessful. 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. You must call ldapssl_client_init before calling the ldapssl_init function to connect to the server, or the ldap_start_tls_s function to start transport layer security. Example 21–55 initializes a client before connecting with a secure LDAP server. #include <ldap.h> #include <ldap_ssl.h> #include <stdio.h> ... /* Initialize client using a certificate database copied from &cnDirectoryServer;. */ if ( ldapssl_client_init( "/local/client/alias/", NULL ) < 0) { printf( "Failed to initialize SSL client...\n" ); return( 1 ); } The certdbpath is a path to the file system directory containing the certificate database files. For example: $ ls /local/client/alias/*.db /local/client/alias/cert8.db /local/client/alias/key3.db /local/client/alias/secmod.db $ ldap_start_tls_s, ldap_init, prldap_init (IPv6), ldapssl_init, ldapssl_install_routines 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. #include <ldap_ssl.h> int ldapssl_clientauth_init( char *certdbpath, void *certdbhandle, int needkeydb, char *keydbpath, void *keydbhandle ); Parameter Description certdbpath Specifies the path to the database containing certificates for your client. You can include the database filename in the path (for example, /usr/mozilla/ cert_file_name.db). needkeydb Specifies whether or not the private key database needs to be opened for use. This parameter can have one of the following values: If it is a non-zero value, the function opens the private key database, which is identified by the keydbpath argument. If 0, the function does not open the private key database. keydbpath Specifies the path to the database containing the private key certified by your certificate. You can include the database filename in the path (for example, /usr/mozilla/ key_file_name.db). certdbhandle Pass a NULL value for this. (This parameter is not currently used.) One of the following values: 0 if successful. -1 if unsuccessful. 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. You must call ldapssl_clientauth_init before calling ldapssl_init to connect to the server. Example 21–56 initializes a client before connecting with a secure LDAP server. #include <ldap.h> #include <ldap_ssl.h> #include <stdio.h> ... /* Initialize client, using mozilla’s certificate database */ if ( ldapssl_clientauth_init( "/u/mozilla/.netscape/ cert_file_name.db", NULL, 1, "/u/mozilla/.netscape/ key_file_name.db", NULL ) < 0 ) { perror( "ldap_clientauth_init" ); return( 1 ); } } ... ldap_init, prldap_init (IPv6), ldapssl_init, ldapssl_install_routines The ldapssl_enable_clientauth function enables SSL client authentication on the given connection (passed using the ld parameter). #include <ldap_ssl.h> int ldapssl_enable_clientauth( LDAP *ld, char *keynickname, char *keypasswd, char *certnickname ); 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. One of the following values: 0 if successful. -1 if unsuccessful. ldapssl_clientauth_init The ldapssl_err2string function returns the corresponding error message for an SSL-specific error code. #include <ldap_ssl.h> const char * LDAP_CALL ldapssl_err2string ( const int prerrno ); Parameter Description prerrno The SSL error code that you want interpreted into an error message. One of the following values: If successful, returns the corresponding error message for the given error code. If unsuccessful (for example, if the error code is not a known SSL error code), returns a pointer to the string Unknown error. ldapssl_err2string provides support for SSL-specific error messages that are not covered by the regular message routine ldap_err2string. If any ldapssl_* function returns an error code that is unknown to ldap_err2string –it returns Unknown error– this function should be called to determine the SSL-specific error message. To check for SSL errors, call ldapssl_err2string after you call any of the following SSL initialization functions: ldapssl_client_init ldapssl_clientauth_init ldapssl_advclientauth_init ldapssl_pkcs_initThe errors returned by these functions are usually related to certificate database corruption, missing certificates in a certificate database, client authentication failures, and other general SSL errors. ldapssl_client_init, ldapssl_clientauth_init, ldapssl_advclientauth_init , ldapssl_pkcs_init, ldap_err2string The ldapssl_init function initializes the LDAP library for SSL and installs the I/O routines for SSL. #include <ldap_ssl.h> LDAP *ldapssl_init( const char *defhost, int defport, int defsecure ); 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. One of the following values: If successful, returns a pointer to an LDAP structure, which should be passed to subsequent calls to other LDAP API functions. If unsuccessful, returns -1. 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. Calling this function is equivalent to calling ldap_init or prldap_init (IPv6) followed by ldapssl_install_routines and ldap_set_option to set the LDAP_OPT_SSL option to LDAP_OPT_ON. Example 21–57 connects your client to a secure LDAP server. #include <ldap.h> #include <ldap_ssl.h> #include <stdio.h> ... /* Initialize client, using mozilla’s certificate database */ if ( ldapssl_client_init( "/u/mozilla/.netscape/ cert_file_name.db", NULL ) < 0) { printf( "Failed to initialize SSL client...\n" ); return( 1 ); } /* get a handle to an LDAP connection */ if ( (ld = ldapssl_init( "cert.example.com", LDAPS_PORT, 1 )) == NULL { perror( "ldapssl_init" ); return( 1 ); } ... /* Client can now perform LDAP operations on the secure LDAP server */ ... ldap_init, prldap_init (IPv6), ldapssl_client_init, ldapssl_install_routines The ldapssl_install_routines function installs the I/O routines that enable SSL over LDAP. #include <ldap_ssl.h> int ldapssl_install_routines( LDAP *ld ); Parameter Description ld Pointer to an LDAP structure containing information about the connection to the LDAP server. One of the following values: 0 if successful. -1 if unsuccessful. You need to call ldapssl_install_routines in combination with ldap_init or prldap_init (IPv6) and ldap_set_option. As an alternative, you can call ldapssl_init rather than these three functions. 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 21–58 connects your client to a secure LDAP server. #include <ldap.h> #include <ldap_ssl.h> #include <stdio.h> ... /* Initialize client, using mozilla’s certificate database */ if ( ldapssl_client_init( "/u/mozilla/.netscape/ cert_file_name.db", NULL ) < 0) { printf( "Failed to initialize SSL client...\n" ); return( 1 ); } /* Get the handle to an LDAP connection. Use prldap_init() for IPv6. */ if ( (ld = ldap_init( MY_HOST, 636 )) == NULL ) { perror( "ldap_init" ); return( 1 ); } /* Load SSL routines */ if ( ldapssl_install_routines( ld ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldapssl_install_routines" ); return( 1 ); } /* Set the option to use SSL with the default connection */ if (ldap_set_option( ld, LDAP_OPT_SSL, LDAP_OPT_ON ) != LDAP_SUCCESS) { ldap_perror( ld, "ldap_set_option" ); return( 1 ); } ... ldap_init, prldap_init (IPv6), ldapssl_init, ldapssl_client_init 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. int ldapssl_pkcs_init( const struct ldapssl_pkcs_fns *pfns); 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 . The &DirectorySDKForC; 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. Example 21–59 defines the ldapssl_pkcs_fns structure. typedef int (LDAP_PKCS_GET_TOKEN_CALLBACK) (void *context, char **tokenname); typedef int (LDAP_PKCS_GET_PIN_CALLBACK) (void *context, const char *tokenname, char **tokenpin); typedef int (LDAP_PKCS_GET_CERTPATH_CALLBACK) (void *context, char **certpath); typedef int (LDAP_PKCS_GET_KEYPATH_CALLBACK)(void *context, char **keypath); typedef int (LDAP_PKCS_GET_MODPATH_CALLBACK) (void *context, char **modulepath); typedef int (LDAP_PKCS_GET_CERTNAME_CALLBACK) (void *context, char **certname); typedef int (LDAP_PKCS_GET_DONGLEFILENAME_CALLBACK) (void *context, char **filename); #define PKCS_STRUCTURE_ID 1 struct ldapssl_pkcs_fns { int local_structure_id; void *local_data; LDAP_PKCS_GET_CERTPATH_CALLBACK *pkcs_getcertpath; LDAP_PKCS_GET_CERTNAME_CALLBACK *pkcs_getcertname; LDAP_PKCS_GET_KEYPATH_CALLBACK *pkcs_getkeypath; LDAP_PKCS_GET_MODPATH_CALLBACK *pkcs_getmodpath; LDAP_PKCS_GET_PIN_CALLBACK *pkcs_getpin; LDAP_PKCS_GET_TOKEN_CALLBACK *pkcs_gettokenname; LDAP_PKCS_GET_DONGLEFILENAME_CALLBACK *pkcs_getdonglefilename; }; Parameter Description pfns Specifies the ldap_pkcs_fns structure for initialization. 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. ldapssl_client_init, ldapssl_clientauth_init, ldapssl_advclientauth_init The ldapssl_serverauth_init function is a server-authentication only version of ldapssl_clientauth_init. #include <ldap_ssl.h> int ldapssl_serverauth_init( const char *certdbpath, void *certdbhandle, const int sslstrength ); Please see the description of the sslstrength value and note the potential problems that can be caused by passing in wrong host and port name values. 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. One of the following values: 0 if successful. -1 if unsuccessful. ldapssl_serverauth_init is a server-authentication only version of ldapssl_clientauth_init. This function allows the sslstrength parameter to be passed in. ldap_init, prldap_init (IPv6), ldapssl_init, ldapssl_install_routines, ldapssl_clientauth_init The ldapssl_set_strength sets the SSL strength for an existing SSL-enabled LDAP session handle. #include <ldap_ssl.h> int LDAP_CALL ldapssl_set_strength( LDAP *ld, int sslstrength ); See the description of the sslstrength value and note the potential problems that can be caused by passing in wrong host and port name values. 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. The ldapssl_tls_start_s function starts an SSL handshake on a previously established non-secure connection. #include <ldap_ssl.h> LDAP_API(int) LDAP_CALL ldapssl_tls_start_s( LDAP *ld, int defsecure, char *certdbpath, char *keydbpath, char ***referralsp ); 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. The ldapssl_tls_start_s function starts an SSL handshake on a previously established non-secure connection. C SDK functions ldap_str2charray ldap_str2charray This function is deprecated and should not be used. It is included in ldap-deprecated.h for backward-compatibility. C SDK functions ldap_tmplattrs ldap_tmplattrs The ldap_tmplattrs function obtains a pointer to the correct ldap_disptmpl structure. #include <disptmpl.h> char ** ldap_tmplattrs( struct ldap_disptmpl *tmpl, char **includeattrs, int exclude, unsigned long syntaxmask ); 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. A NULL terminated array that contains the names of attributes that need to be retrieved if the template, defined by tmpl , is to be used to display an entry. A NULL pointer on error. The attribute list should be freed using ldap_value_free . ldap_value_free C SDK functions ldap_tmplerr2string ldap_tmplerr2string The ldap_templerr2string function returns a string representation of the error passed in the parameter. #include <disptmpl.h> char * ldap_tmplerr2string( int err ); Parameter Description err Error returned. C SDK functions ldap_ufn_* ldap_ufn_* This function will be deprecated and should not be used. It is included in ldap-to-be-deprecated.h for backward-compatibility. This function will be deprecated and should not be used. It is included in ldap-to-be-deprecated.h for backward-compatibility. This function will be deprecated and should not be used. It is included in ldap-to-be-deprecated.h for backward-compatibility. This function will be deprecated and should not be used. It is included in ldap-to-be-deprecated.h for backward-compatibility. This function will be deprecated and should not be used. It is included in ldap-to-be-deprecated.h for backward-compatibility. This function will be deprecated and should not be used. It is included in ldap-to-be-deprecated.h for backward-compatibility. C SDK functions ldap_unbind ldap_unbind The ldap_unbind function unbinds from the directory, terminates the current association, and frees the resources contained in the LDAP structure. #include <ldap.h> int ldap_unbind( LDAP *ld ); Parameter Description ld Pointer to an LDAP structure containing information about the connection to the LDAP server. For a list of possible results for an LDAP unbind operation, see ldap_unbind_s. 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. There is no server response to an LDAP unbind operation. All three of the unbind functions return LDAP_SUCCESS (or another LDAP error code if the request cannot be sent to the LDAP server). After a call to one of the unbind functions, the session handle ld is invalid and it is illegal to make any further calls using it. Example 21–60 closes the current connection with the LDAP server. #include <ldap.h> ... LDAP *ld; ... /* After completing your LDAP operations with the server, close the connection. */ if ( ldap_unbind( ld ) != LDAP_SUCCESS ) { ldap_perror( ld, "Error while unbinding from the directory" ); return( 1 ); } ... ldap_unbind_s, ldap_unbind_ext C SDK functions ldap_unbind_s 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. #include <ldap.h> int ldap_unbind_s( LDAP *ld ); Parameter Description ld Pointer to an LDAP structure containing information about the connection to the LDAP server. 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. 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. There is no server response to an LDAP unbind operation. All three of the unbind functions return LDAP_SUCCESS (or another LDAP error code if the request cannot be sent to the LDAP server). After a call to one of the unbind functions, the session handle ld is invalid and it is illegal to make any further calls using it. Example 21–61 closes the current connection with the LDAP server. #include <ldap.h> ... LDAP *ld; ... /* After completing your LDAP operations with the server, close the connection. */ if ( ldap_unbind_s( ld ) != LDAP_SUCCESS ) { ldap_perror( ld, "Error while unbinding from the directory" ); return( 1 ); } ... ldap_unbind, ldap_unbind_ext C SDK functions 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. #include <ldap.h> int ldap_unbind_ext( LDAP *ld, LDAPControl **serverctrls, LDAPControl **clientctrls ); 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. One of the following values: LDAP_SUCCESS if successful. LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request. LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost. LDAP_NO_MEMORY if memory cannot be allocated. LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function. 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. 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. ldap_unbind, ldap_unbind_s C SDK functions ldap_url_parse ldap_url_parse The ldap_url_parse function parses an LDAP URL into its components. #include <ldap.h> int ldap_url_parse( const char *url, LDAPURLDesc **ludpp ); Parameter Description url The URL that you want to check. ludpp Pointer to a structure containing the components of the URL. One of the following values: LDAP_SUCCESS if successful. LDAP_URL_ERR_NOTLDAP if the URL does not begin with the ldap:// or ldaps:// prefix. LDAP_URL_ERR_NODN if the URL missing trailing slash after host or port. LDAP_URL_ERR_BADSCOPE if the scope within the URL is invalid. LDAP_URL_ERR_MEM if not enough free memory is available for this operation. LDAP_URL_ERR_PARAM if an invalid argument was passed to the function. Example 21–62 parses an LDAP URL and prints out each component of it. #include <stdio.h> #include <ldap.h> ... char *my_url = "ldap://ldap.example.com:1389/dc=example,dc=com? cn,mail,telephoneNumber?sub?(sn=Jensen)"; LDAPURLDesc *ludpp; int res, i; ... if ( ( res = ldap_url_parse( my_url, &ludpp ) ) != 0 ) { switch( res ){ case LDAP_URL_ERR_NOTLDAP: printf( "URL does not begin with \"ldap://\"\n" ); break; case LDAP_URL_ERR_NODN: printf( "URL missing trailing slash after host or port\n" ); break; case LDAP_URL_ERR_BADSCOPE: printf( "URL contains an invalid scope\n" ); break; case LDAP_URL_ERR_MEM: printf( "Not enough memory\n" ); break; default: printf( "Unknown error\n" ); } return( 1 ); } printf( "Components of the URL:\n" ); printf( "Host name: %s\n", ludpp->lud_host ); printf( "Port number: %d\n", ludpp->lud_port ); if ( ludpp->lud_dn != NULL ) { printf( "Base entry: %s\n", ludpp->lud_dn ); } else { printf( "Base entry: Root DN\n" ); } if ( ludpp->lud_attrs != NULL ) { printf( "Attributes returned: \n" ); for ( i=0; ludpp->lud_attrs[i] != NULL; i++ ) { printf( "\t%s\n", ludpp->lud_attrs[i] ); } } else { printf( "No attributes returned.\n" ); } printf( "Scope of the search: " ); switch( ludpp->lud_scope ) { case LDAP_SCOPE_BASE: printf( "base\n" ); break; case LDAP_SCOPE_ONELEVEL: printf( "one\n" ); break; case LDAP_SCOPE_SUBTREE: printf( "sub\n" ); break; default: printf( "Unknown scope\n" ); } printf( "Filter: %s\n", ludpp->lud_filter ); ... ldap_free_urldesc C SDK functions ldap_url_parse_no_defaults ldap_url_parse_no_defaults The ldap_url_parse_no_defaults function parses an LDAP URL into its components. #include <ldap.h> int ldap_url_parse_no_defaults( const char *url, LDAPURLDesc **ludpp, int dn_required ); 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. 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. 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). C SDK functions ldap_url_search ldap_url_search The ldap_url_search function searches the directory asynchronously for matching entries, based on the contents of the URL. #include <ldap.h> int ldap_url_search( LDAP *ld, const char *url, int attrsonly ); Parameter Description ld Pointer to an LDAP structure containing information about the connection to the LDAP server. url LDAP URL specifying a search of the directory. attrsonly Specifies whether or not attribute values are returned along with the attribute types. This parameter can have the following values: 0 specifies that both attribute types and attribute values are returned. 1 specifies that only attribute types are returned. Returns the message ID of the ldap_url_search operation. To check the result of this operation, call ldap_result and ldap_result2error. ldap_url_search searches the directory for matching entries, based on the contents of the URL. ldap_url_search is an asynchronous function; it does not directly return results. If you want the results to be returned directly by the function, call the synchronous function ldap_url_search_s. Example 21–63 returns the message ID. #include "examples.h" static void do_other_work(); unsigned long global_counter = 0; int main( int argc, char **argv ) { char *my_url = "ldap://ldap.example.com/dc=example,dc=com? cn,mail,telephoneNumber?sub?(sn=Jensen)"; LDAP *ld; LDAPMessage *result, *e; BerElement *ber; char *a, *dn; char **vals; int i, rc, finished, msgid; int num_entries = 0; struct timeval zerotime; zerotime.tv_sec = zerotime.tv_usec = 0L; /* Get a handle to an LDAP connection. Use prldap_init() for IPv6. */ if ( (ld = ldap_init( MY_HOST, MY_PORT )) == NULL ) { perror( "ldap_init" ); return( 1 ); } /* authenticate to the directory as nobody */ if ( ldap_simple_bind_s( ld, NULL, NULL ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldap_simple_bind_s" ); return( 1 ); } /* search for all entries with surname of Jensen */ if (( msgid = ldap_url_search( ld, my_url, 0 )) == -1 ) { ldap_perror( ld, "ldap_url_search" ); return( 1 ); } /* Loop, polling for results until finished */ finished = 0; while ( !finished ) { /* * Poll for results. We call ldap_result with the "all" parameter * set to zero. This causes ldap_result() to return exactly one * entry if at least one entry is available. This allows us to * display the entries as they are received. */ result = NULL; rc = ldap_result( ld, msgid, 0, &zerotime, &result ); switch ( rc ) { case -1: /* some error occurred */ ldap_perror( ld, "ldap_result" ); return( 1 ); case 0: /* Timeout was exceeded. No entries are ready for retrieval. */ if ( result != NULL ) { ldap_msgfree( result ); } break; default: /* * Either an entry is ready for retrieval, or all entries have * been retrieved. */ if (( e = ldap_first_entry( ld, result )) == NULL ) { /* All done */ finished = 1; if ( result != NULL ) { ldap_msgfree( result ); } continue; } /* for each entry print out name + all attrs and values */ num_entries++; if (( dn = ldap_get_dn( ld, e )) != NULL ) { printf( "dn: %s\n", dn ); ldap_memfree( dn ); } for ( a = ldap_first_attribute( ld, e, &ber ); a != NULL; a = ldap_next_attribute( ld, e, ber ) ) { if (( vals = ldap_get_values( ld, e, a )) != NULL ) { for ( i = 0; vals[ i ] != NULL; i++ ) { printf( "%s: %s\n", a, vals[ i ] ); } ldap_value_free( vals ); } ldap_memfree( a ); } if ( ber != NULL ) { ldap_ber_free( ber, 0 ); } printf( "\n" ); ldap_msgfree( result ); } /* Do other work here while you are waiting... */ do_other_work(); } /* All done. Print a summary. */ printf( "%d entries retrieved. I counted to %ld " "while I was waiting.\n", num_entries, global_counter ); ldap_unbind( ld ); return( 0 ); } /* * Perform other work while polling for results. */ static void do_other_work() { global_counter++; } ldap_url_search_s, ldap_result, ldap_result2error C SDK functions ldap_url_search_s ldap_url_search_s The ldap_url_search_s function searches the directory synchronously for matching entries, based on the contents of the URL. #include <ldap.h> int ldap_url_search_s( LDAP *ld, const char *url, int attrsonly, LDAPMessage **res ); Parameter Description ld Pointer to an LDAP structure containing information about the connection to the LDAP server. url LDAP URL specifying a search of the directory. attrsonly Specifies whether or not attribute values are returned along with the attribute types. This parameter can have the following values: 0 specifies that both attribute types and attribute values are returned. 1 specifies that only attribute types are returned. res Results of the search (when the call is completed). One of the following values: LDAP_SUCCESS if successful. If unsuccessful, returns the LDAP error code for the operation. The ldap_url_search_s function searches the directory for matching entries, based on the contents of the URL. ldap_url_search_s is a synchronous function, which directly returns the results of the operation. If you want to perform other operations while waiting for the results of this operation, call the asynchronous function ldap_url_search. Example 21–64 processes a search request from an LDAP URL. #include <stdio.h> #include <ldap.h> ... LDAP *ld; LDAPMessage *result; char *my_url = "ldap://ldap.example.com/dc=example,dc=com? cn,mail,telephoneNumber?sub?(sn=Jensen)"; ... /* Process the search request in the URL */ if ( ldap_url_search_s( ld, my_url, 0, &result ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldap_url_search_s" ); return( 1 ); } ... ldap_search, ldap_search_st C SDK functions ldap_url_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. #include <ldap.h> int ldap_url_search_st( LDAP *ld, const char *url, int attrsonly, struct timeval *timeout, LDAPMessage **res ); Parameter Description ld Pointer to an LDAP structure containing information about the connection to the LDAP server. url LDAP URL specifying a search of the directory. attrsonly Specifies whether or not attribute values are returned along with the attribute types. This parameter can have the following values: 0 specifies that both attribute types and attribute values are returned. 1 specifies that only attribute types are returned. timeout Maximum time to wait for the results of the search. res Results of the search (when the call is completed). One of the following values: LDAP_SUCCESS if successful. LDAP_PARAM_ERROR if any of the arguments are invalid. LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request. LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost. LDAP_NO_MEMORY if memory cannot be allocated. LDAP_LOCAL_ERROR if an error occurred when receiving the results from the server. LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded results from the server. LDAP_FILTER_ERROR if an error occurred when parsing and BER-encoding the search filter specified by the filter argument. LDAP_TIMEOUT if the search exceeded the time specified by the timeoutp argument. LDAP_NOT_SUPPORTED if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAP v3. Make sure that you set the version of your LDAP client to version 3 before calling this function. &cnDirectoryServer; and other LDAP server products may send result codes in addition to those described. For example, the server may have loaded a plug-in that returns custom result codes. Check your LDAP server documentation for other result codes. The ldap_url_search_st function searches the directory for matching entries, based on the contents of the URL. This function works like ldap_url_search_s and lets you specify a time out period for the search. ldap_search, ldap_search_s C SDK functions ldap_utf8characters ldap_utf8characters The ldap_utf8characters function accepts a Unicode string and returns the number of characters. #include <ldap.h> size_t ldap_utf8characters( const char* ); Parameter Description char Pointer to a UTF-8 string. Returns the number of UTF-8 characters in the 0 terminated array. C SDK functions ldap_utf8copy ldap_utf8copy The ldap_utf8copy function accepts a Unicode string and copies the characters to a destination. #include <ldap.h> int ldap_utf8copy( char* dst, const char* src ); Parameter Description dst Pointer to a destination for the copied characters. src Pointer to a UTF-8 string to copy. ldap_utf8copy copies a character from src to dst. This function handles any valid UTF-8 character (including \0 and ASCII). The number of characters copied. C SDK functions ldap_utf8getcc ldap_utf8getcc The ldap_utf8getcc function gets one UCS-4 character and moves the pointer to the next character. #include <ldap.h> unsigned long ldap_utf8getcc( const char** src ); Parameter Description src Pointer to a UCS-4 character. C SDK functions ldap_utf8isalnum ldap_utf8isalnum The ldap_utf8isalnum function determines whether the character is an alphanumeric one. #include <ldap.h> int ldap_utf8isalnum( char* s ); Parameter Description s Pointer to a UTF-8 character. C SDK functions ldap_utf8isalpha ldap_utf8isalpha The ldap_utf8isalpha function determines whether the character is a letter. #include <ldap.h> int ldap_utf8isalpha( char* s ); Parameter Description s Pointer to a UTF-8 character. C SDK functions ldap_utf8isdigit ldap_utf8isdigit The ldap_utf8isdigit function determines whether the character is a number. #include <ldap.h> int ldap_utf8isdigit( char* s ); Parameter Description s Pointer to a UTF-8 character. C SDK functions ldap_utf8isspace ldap_utf8isspace The ldap_utf8isspace function determines whether the character is a space, tab, newline, return or formfeed. #include <ldap.h> int ldap_utf8isspace( char* s ); Parameter Description s Pointer to a UTF-8 character. C SDK functions ldap_utf8len ldap_utf8len The ldap_utf8len function accepts a Unicode string and returns the number of bytes it contains. #include <ldap.h> int ldap_utf8len( const char* ); Parameter Description char Pointer to a UTF-8 string. C SDK functions ldap_utf8next ldap_utf8next The ldap_utf8next function accepts a character and returns a pointer to the character immediately following it. #include <ldap.h> char* ldap_utf8next( char* ); Parameter Description char Pointer to a UTF-8 character. C SDK functions ldap_utf8prev ldap_utf8prev The ldap_utf8prev function accepts a character and returns a pointer to the previous character. #include <ldap.h> char* ldap_utf8prev( char* ); Parameter Description char Pointer to a UTF-8 character. C SDK functions ldap_utf8strtok_r ldap_utf8strtok_r The ldap_utf8strtok_r function gets the next token from a string. #include <ldap.h> char* ldap_utf8strtok_r( char* src, const char* brk, char** next); 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 a pointer to the next token. If there are no remaining tokens, returns a NULL pointer. C SDK functions ldap_whoami ldap_whoami The ldap_whoami function sends an asynchronous Who am I? extended operation request to determine the authorization identity associated with a connection. LDAP_API(int) LDAP_CALL ldap_whoami( LDAP *ld, LDAPControl **serverctrls, LDAPControl **clientctrls, int *msgidp ); Parameter Description ld Pointer to an LDAP structure containing information about the connection to the LDAP server. serverctrls Pointer to an array of LDAPControl structures representing LDAP server controls that apply to this operation. If you do not want to pass any server controls, specify NULL for this argument. clientctrls Pointer to an array of LDAPControl structures representing LDAP client controls that apply to this operation. If you do not want to pass any client controls, specify NULL for this argument. msgidp Pointer to the message ID for this asynchronous call, for use with ldap_parse_whoami_result, or to retrieve the result for use with ldap_parse_whoami . 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. C SDK functions ldap_whoami_s ldap_whoami_s The ldap_whoami_s function sends a synchronous Who am I? extended operation request to determine the authorization identity associated with a connection. LDAP_API(int) LDAP_CALL ldap_whoami_s( LDAP *ld, LDAPControl **serverctrls, LDAPControl **clientctrls, char **authzid ); Parameter Description ld Pointer to an LDAP structure containing information about the connection to the LDAP server. serverctrls Pointer to an array of LDAPControl structures representing LDAP server controls that apply to this operation. If you do not want to pass any server controls, specify NULL for this argument. clientctrls Pointer to an array of LDAPControl structures representing LDAP client controls that apply to this operation. If you do not want to pass any client controls, specify NULL for this argument. authzid Pointer to the string to hold the authorization identity retrieved from the server. 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. C SDK functions ldap_vals2html ldap_vals2html The ldap_vals2html function writes the HTML representation of a set of values. #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 ); Parameter Description ld The LDAP pointer obtained by a previous call to ldap_open . buf vals A NULL terminated list of values, usually obtained by a call to ldap_get_values. label A string (usually a friendly form of an LDAP attribute name) shown next to the values. labelwidth Specifies the label margin (the number of blank spaces displayed to the left of the values). If zero is passed, a default label width is used. syntaxid Display template attribute syntax identifier for a list of predefined LDAP_SYN_... values. writeproc writeproc function should be declared as: int writeproc( writeparm, p, len ) void *writeparm; char *p; int len; where p is a pointer to text to be written and len is the length of the text. p is guaranteed to be zero terminated. writeparm A pointer to a structure that will be passed as the first parameter of the writeproc procedure. Typically, this is used to pass the file descriptor of the file to write to. eol Lines of text are terminated with this string. rdncount Limits the number of components that are displayed for DN attributes. urlprefix Starting text to use when constructing an LDAP URL. The default is the string ldap:// LDAP_SUCCESS if successful. An LDAP error code on error. ldap_vals2html produces HTML output of a single set of LDAP attribute values. ldap_vals2text C SDK functions ldap_vals2text ldap_vals2text The ldap_vals2text function writes the text representation of an LDAP entry. #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 ); Parameter Description ld The LDAP pointer obtained by a previous call to ldap_open . buf vals A NULL terminated list of values, usually obtained by a call to ldap_get_values. label A string (usually a friendly form of an LDAP attribute name) shown next to the values. labelwidth Specifies the label margin (the number of blank spaces displayed to the left of the values). If zero is passed, a default label width is used. syntaxid Display template attribute syntax identifier for a list of predefined LDAP_SYN_... values. writeproc writeproc function should be declared as: int writeproc( writeparm, p, len ) void *writeparm; char *p; int len; where p is a pointer to text to be written and len is the length of the text. p is guaranteed to be zero terminated. writeparm A pointer to a structure that will be passed as the first parameter of the writeproc procedure. Typically, this is used to pass the file descriptor of the file to write to. eol Lines of text are terminated with this string. rdncount Limits the number of components that are displayed for DN attributes. LDAP_SUCCESS if successful. An LDAP error code on error. ldap_vals2text produces a text representation of a single set of LDAP attribute values. ldap_vals2html C SDK functions ldap_value_free ldap_value_free The ldap_value_free function frees an array of values from memory. #include <ldap.h> void ldap_value_free( char **values ); Parameter Description values Array of values. Use the ldap_value_free_len function if the values are berval structures. See the example under ldap_get_values. ldap_get_values, ldap_value_free_len C SDK functions ldap_value_free_len ldap_value_free_len The ldap_value_free_len function frees an array of berval structures from memory. #include <ldap.h> void ldap_value_free_len( struct berval **values ); Parameter Description values Array of berval structures. Use the ldap_value_free function instead of this function if the values are string values. See the example under ldap_get_values_len. ldap_get_values, ldap_get_values_len C SDK functions ldap_version ldap_version 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 &DirectorySDKForC; libraries. #include <ldap.h> int ldap_version( LDAPVersion *ver ); Parameter Description ver LDAPVersion structure returning version information. If you only want the SDK version, you can pass NULL for this parameter. The version number of the &DirectorySDKForC;, multiplied by 100. For example, for version 1.0, the function returns 100. ldap_get_option C SDK functions ldap_x_* ldap_x_* The ldap_x_calloc function allocates space for an array of elements. #include <ldap-extension.h> void *ldap_x_calloc( size_t nelem, size_t elsize ); Parameter Description nelem Number of elements for which memory is to be allocated. elsize Size of each element. If successful, returns a pointer to the space. If there is no available memory, returns a NULL pointer. ldap_x_free, ldap_x_malloc , ldap_x_realloc The ldap_x_free function frees allocated memory. #include <ldap-extension.h> void ldap_x_free( void *ptr ); Parameter Description ptr Pointer to the block of memory to be freed. ldap_x_calloc, ldap_x_malloc , ldap_x_realloc The ldap_x_hostlist_first function returns the first host and port defined in a host list file. #include <ldap-extension.h> int ldap_x_hostlist_first( char *hostlist, int defport, char **hostp, int *portp, struct ldap_x_hostlist_status **statusp ); 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. LDAP_SUCCESS if successful. If unsuccessful returns a valid LDAP API error code. A NULL or zero-length hostlist causes the host 127.0.0.1 to be returned. ldap_x_hostlist_status, LDAP_X_EXTIOF_CONNECT_CALLBACK, The ldap_x_hostlist_next function returns the host and port defined in a host list file following the previous host and port returned. #include <ldap-extension.h> int ldap_x_hostlist_next( char **hostp, int *portp, struct ldap_x_hostlist_status **statusp ); 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. 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. A NULL or zero-length hostlist causes the host 127.0.0.1 to be returned. ldap_x_hostlist_status, LDAP_X_EXTIOF_CONNECT_CALLBACK, ldap_x_hostlist_first, ldap_x_hostlist_next, LDAP_X_EXTIOF_CONNECT_CALLBACK ldap_x_hostlist_first, ldap_x_hostlist_next, LDAP_X_EXTIOF_CONNECT_CALLBACK The ldap_x_malloc function allocates space for an object. #include <ldap-extension.h> void *ldap_x_malloc( size_t size ); Parameter Description size Specifies the size for the allocated block of memory. ldap_x_free, ldap_x_calloc , ldap_x_realloc The ldap_x_realloc function changes the size of a block of memory. #include <ldap-extension.h> void *ldap_x_realloc( void *ptr, size_t size ); Parameter Description ptr Pointer to a block of memory. size Specifies the new size of the block. ldap_x_free, ldap_x_calloc , ldap_x_malloc C SDK functions prldap_* prldap_* The prldap_get_default_socket_info function retrieves default socket information. #include <ldappr.h> int prldap_get_default_socket_info( LDAP *ld, PRLDAPSocketInfo *soip ); Parameter Description fd The session handle returned from prldap_init. soip Pointer to a structure containing socket specific information. LDAP_SUCCESS if successful. An LDAP API error code if an error occurs. LDAP_PARAM_ERROR is returned if ld is NULL. prldap_set_default_socket_info The prldap_get_session_info function retrieves application-specific data. #include <ldappr.h> int prldap_get_session_info( LDAP *ld, void *sessionarg, PRLDAPSessionInfo *seip ); 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. LDAP_SUCCESS if successful. An LDAP API error code if an error occurs. 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. prldap_set_session_info The prldap_get_session_option function retrieves an option specific to the prldap layer. #include <ldappr.h> int prldap_get_session_option( LDAP *ld, void *sessionarg, int option, ... ); LDAP_SUCCESS if successful. An LDAP API error code if an error occurs. 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. prldap_set_session_option The prldap_get_socket_info function retrieves socket-specific information based on parameters passed to the extended I/O callback functions. #include <ldappr.h> int prldap_get_socket_info( int fd, void *socketarg, PRLDAPSocketInfo *soip ); Parameter Description fd The session handle returned from prldap_init. soip Pointer to a structure containing socket information data. LDAP_SUCCESS if successful. An LDAP API error code if an error occurs. prldap_set_socket_info The prldap_init function creates a new session handle with Netscape Portable Runtime (NSPR) I/O, threading, support for IPv6, and DNS functions installed. #include <ldappr.h> LDAP * prldap_init( const char *defhost, int defport, int shared ); Parameter Description defhost Space-delimited list of one or more host names (or IP address in dotted notation, such as 192.168.0.99) of the LDAP servers that you want the LDAP client to connect to. The names can be in hostname : portnumber format (in which case, portnumber overrides the port number specified by the defport argument. defport Default port number of the LDAP server. To specify the standard LDAP port (port 389), use LDAP_PORT as the value for this parameter. shared Pass a non-zero value if you plan to use this LDAP handle for more than one thread. Pointer to LDAP session handle if successful. NULL if an error occurs. To be able to use LDAP over Internet Protocol, version 6, IPv6, this function should be used rather than ldap_init. 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. #include <ldappr.h> int prldap_install_routines( LDAP *ld, int shared ); 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. LDAP_SUCCESS if successful. An LDAP API error code if an error occurs. prldap_init The prldap_set_default_socket_info function sets default socket information. #include <ldappr.h> int prldap_set_default_socket_info( LDAP *ld, PRLDAPSocketInfo *soip ); Parameter Description fd The session handle returned from prldap_init. soip Pointer to a structure containing socket specific information. LDAP_SUCCESS if successful. LDAP_PARAM_ERROR is returned if ld is NULL. An LDAP API error code if an error occurs. prldap_get_socket_info The prldap_set_session_info function sets application-specific data. #include <ldappr.h> int prldap_set_session_info( LDAP *ld, void *sessionarg, PRLDAPSessionInfo *seip ); Parameter Description ld The session handle returned from prldap_init. seip Pointer to a structure containing session information data. LDAP_SUCCESS if successful. An LDAP API error code if an error occurs. 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. prldap_get_session_info The prldap_set_session_option function sets a session option specific to the prldap layer. #include <ldappr.h> int prldap_set_session_option( LDAP *ld, void *sessionarg, int option, ... ); Parameter Description ld The session handle returned from prldap_init. option LDAP_SUCCESS if successful. An LDAP API error code if an error occurs. 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. prldap_get_session_option The prldap_set_socket_info function sets socket information. #include <ldappr.h> int prldap_set_socket_info( int fd, void *socketarg, PRLDAPSocketInfo *soip ); Parameter Description fd The session handle returned from prldap_init. soip Pointer to a structure containing socket information data. LDAP_SUCCESS if successful. An LDAP API error code if an error occurs. 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. prldap_get_socket_info