Mozilla LDAP C SDK Programmer's Guide
Chapter 18 - Function Reference
This chapter contains a reference to the public functions of the LDAP C SDK. Along with a detailed description of each function, the function reference details the function header file and syntax, the function parameters, and what the function returns. In many cases an example program is included with the description.
The beginning of this chapter lists the functions in the following two formats:
Functions (in alphabetical order)
The LDAP C SDK includes the following functions (functions that require LDAPv3 support are noted):
ber_bvfree()
ber_free()
ldap_abandon()
-
ldap_abandon_ext()
- LDAPv3 function ldap_add()
-
ldap_add_ext()
- LDAPv3 function -
ldap_add_ext_s()
- LDAPv3 function ldap_add_s()
ldap_ber_free()
ldap_build_filter()
ldap_compare()
-
ldap_compare_ext()
- LDAPv3 function -
ldap_compare_ext_s()
- LDAPv3 function -
ldap_compare_s()
-
ldap_control_free()
- LDAPv3 function -
ldap_controls_free()
- LDAPv3 function ldap_count_entries()
-
ldap_count_messages()
- LDAPv3 function -
ldap_count_references()
- LDAPv3 function ldap_count_values()
ldap_count_values_len()
ldap_create_filter()
-
ldap_create_persistentsearch_control()
- LDAPv3 function -
ldap_create_proxyauth_control()
- LDAPv3 function -
ldap_create_sort_control()
- LDAPv3 function -
ldap_create_sort_keylist()
- LDAPv3 function -
ldap_create_virtuallist_control()
- LDAPv3 function ldap_delete()
-
ldap_delete_ext()
- LDAPv3 function -
ldap_delete_ext_s()
- LDAPv3 function ldap_delete_s()
ldap_dn2ufn()
ldap_err2string()
ldap_explode_dn()
ldap_explode_rdn()
-
ldap_extended_operation()
- LDAPv3 function -
ldap_extended_operation_s()
- LDAPv3 function ldap_first_attribute()
ldap_first_entry()
-
ldap_first_message()
- LDAPv3 function -
ldap_first_reference()
- LDAPv3 function ldap_free_friendlymap()
ldap_free_sort_keylist()
ldap_free_urldesc()
ldap_friendly_name()
ldap_get_dn()
-
ldap_get_entry_controls()
- LDAPv3 function ldap_getfilter_free()
ldap_getfirstfilter()
ldap_get_lang_values()
ldap_get_lang_values_len()
ldap_get_lderrno()
ldap_getnextfilter()
ldap_get_option()
ldap_get_values()
ldap_get_values_len()
ldap_init()
ldap_init_getfilter()
ldap_init_getfilter_buf()
ldap_is_ldap_url()
ldap_memcache_destroy()
ldap_memcache_flush()
ldap_memcache_get()
ldap_memcache_init()
ldap_memcache_set()
ldap_memcache_update()
ldap_memfree()
ldap_modify()
-
ldap_modify_ext()
- LDAPv3 function -
ldap_modify_ext_s()
- LDAPv3 function ldap_modify_s()
ldap_modrdn()
ldap_modrdn_s()
ldap_modrdn2()
ldap_modrdn2_s()
ldap_mods_free()
ldap_msgfree()
ldap_msgid()
ldap_msgtype()
ldap_multisort_entries()
ldap_next_attribute()
ldap_next_entry()
-
ldap_next_message()
- LDAPv3 function -
ldap_next_reference()
- LDAPv3 function -
ldap_parse_entrychange_control()
- LDAPv3 function -
ldap_parse_extended_result()
- LDAPv3 function -
ldap_parse_reference()
- LDAPv3 function -
ldap_parse_result()
- LDAPv3 function -
ldap_parse_sasl_bind_result()
- LDAPv3 function -
ldap_parse_sort_control()
- LDAPv3 function -
ldap_parse_virtuallist_control()
- LDAPv3 function ldap_perror()
-
ldap_rename()
- LDAPv3 function -
ldap_rename_s()
- LDAPv3 function ldap_result()
ldap_result2error()
-
ldap_sasl_bind()
- LDAPv3 function -
ldap_sasl_bind_s()
- LDAPv3 function ldap_search()
-
ldap_search_ext()
- LDAPv3 function -
ldap_search_ext_s()
- LDAPv3 function ldap_search_s()
ldap_search_st()
ldap_set_filter_additions()
ldap_setfilteraffixes()
ldap_set_lderrno()
ldap_set_option()
ldap_set_rebind_proc()
ldap_simple_bind()
ldap_simple_bind_s()
ldap_sort_entries()
ldap_sort_values()
ldap_sort_strcasecmp()
ldap_unbind()
ldap_unbind_s()
ldap_unbind_ext()
ldap_url_parse()
ldap_url_search()
ldap_url_search_s()
ldap_url_search_st()
ldap_value_free()
ldap_value_free_len()
ldap_version()
ldapssl_advclientauth_init()
ldapssl_client_init()
ldapssl_clientauth_init()
ldapssl_enable_clientauth()
ldapssl_err2string()
ldapssl_init()
ldapssl_install_routines()
ldapssl_pkcs_init()
Summary of Functions by Task
This section summarizes the functions in the LDAP C SDK into the following task categories:
- Initializing and Ending LDAP Sessions
- Authenticating to an LDAP Server
- Performing LDAP Operations
- Getting Search Results
- Sorting Search Results
- Working with Search Filters
- Working with Distinguished Names
- Working with LDAPv3 Controls
- Working with LDAP URLs
- Getting the Attribute Values for a Particular Language
- Handling Errors
- Freeing Memory
Initializing and Ending LDAP Sessions
Call the following functions to initialize a session, set session options, and end a session.
Table 18-1 - Functions to initialize and end an LDAP session
Function | Description |
---|---|
ldap_init() |
Initialize an LDAP session. |
ldapssl_init() |
Initialize an LDAP session over SSL. |
ldap_set_option() |
Set session preferences. |
ldap_get_option() |
Get session preferences. |
ldap_unbind(),
ldap_unbind_s(), or
ldap_unbind_ext()
|
End an LDAP session. |
ldapssl_client_init(),
ldapssl_clientauth_init(),
ldapssl_advclientauth_init(), or
ldapssl_pkcs_init().
|
Perform once-per-process initialization required in order to use SSL. |
Authenticating to an LDAP Server
Call the following functions to authenticate to an LDAP server.
Table 18-2 - Functions to authenticate to an LDAP server
Function | Description |
---|---|
ldap_simple_bind() or
ldap_simple_bind_s()
|
Authenticate to an LDAP server using a password. |
ldap_sasl_bind() and
ldap_parse_sasl_bind_result() ,
or ldap_sasl_bind_s() |
Authenticate to an LDAP server using a SASL mechanism. |
ldap_set_rebind_proc() |
Specify the function used to get authentication information when following referrals. |
Performing LDAP Operations
Call the following functions to perform LDAP operations on a server.
Table 18-3 - Functions to perform operations on an LDAP server
Function | Description |
---|---|
ldap_add_ext() or
ldap_add_ext_s()
|
Add a new entry to the directory. |
ldap_modify_ext() or
ldap_modify_ext_s()
|
Modify an entry in the directory. |
ldap_delete_ext() or
ldap_delete_ext_s()
|
Delete an entry from the directory. |
ldap_rename() or
ldap_rename_s()
|
Rename an entry in the directory. |
ldap_search_ext() or
ldap_search_ext_s()
|
Search the directory. |
ldap_compare_ext() or
ldap_compare_ext_s()
|
Compare entries in the directory. |
ldap_extended_operation() or
ldap_extended_operation_s()
|
Perform an LDAPv3 extended operation. |
ldap_result() |
Check the results of an asynchronous operation. |
ldap_parse_extended_result() |
Parse the results of an LDAPv3 extended operation. |
ldap_msgfree() |
Free the results from memory. |
ldap_abandon_ext() |
Cancel an asynchronous operation. |
Getting Search Results
Call the following functions to retrieve search results.
Table 18-4 - Functions to search entries on an LDAP server
Function | Description |
---|---|
ldap_first_message() |
Get the first message (an entry or search reference) in a chain of search results. |
ldap_next_message() |
Get the next message (an entry or search reference) in a chain of search results. |
ldap_count_messages() |
Count the number of messages (entries and search references) in a chain of search results. |
ldap_first_entry() |
Get the first entry in a chain of search results. |
ldap_next_entry() |
Get the next entry in a chain of search results. |
ldap_count_entries() |
Count the number of entries in a chain of search results. |
ldap_first_reference() |
Get the first search reference in a chain of search results. |
ldap_next_reference() |
Get the next search reference in a chain of search results. |
ldap_count_references() |
Count the number of search references in a chain of search results. |
ldap_get_dn() |
Get the distinguished name for an entry. |
ldap_first_attribute() |
Get the name of the first attribute in an entry. |
ldap_next_attribute() |
Get the name of the next attribute in an entry. |
ldap_get_values() |
Get the string values of an attribute. |
ldap_get_values_len() |
Get the binary values of an attribute. |
ldap_count_values() |
Count the string values of an attribute. |
ldap_count_values_len() |
Count the binary values of an attribute. |
ldap_get_lang_values() |
Get the string values of the specified language subtype of an attribute. |
ldap_get_lang_values_len() |
Get the binary values of the specified language subtype of an attribute. |
ldap_value_free() |
Free the memory allocated for the string values of an attribute. |
ldap_value_free_len() |
Free the memory allocated for the binary values of an attribute. |
Sorting Search Results
Call the following functions to sort search results.
Table 18-5 - Functions that sort search results
Function | Description |
---|---|
ldap_sort_entries() |
Have your client sort entries by distinguished name or by a single attribute. |
ldap_multisort_entries() |
Have your client sort entries by multiple attributes. |
ldap_create_sort_keylist(),
ldap_create_sort_control(),
ldap_parse_sort_control()
|
Request that the server sort the search results before sending them to your client. |
ldap_sort_values() |
Sort the values of an attribute |
ldap_sort_strcasecmp() |
A case-insensitive comparison function that you can pass to
ldap_sort_values() .
|
Working with Search Filters
Call the following functions to initialize, retrieve, and build filters.
Table 18-6 - Functions to initialize, retrieve, and build filters
Function | Description |
---|---|
ldap_init_getfilter() |
Read a filter configuration file into memory. |
ldap_init_getfilter_buf() |
Read a filter configuration from a buffer. |
ldap_set_filter_additions() |
Specify the prefix and suffix to be added to all filters retrieved from the filter configuration. |
ldap_getfirstfilter() |
Retrieve the first matching filter from the filter configuration. |
ldap_getnextfilter() |
Retrieve the next matching filter from the filter configuration. |
ldap_getfilter_free() |
Free the filter configuration from memory. |
ldap_create_filter() |
Build a filter. |
Working with Distinguished Names
Call the following functions to retrieve a distinguished name from an entry and to split a distinguished name into its component parts.
Table 18-7 - Functions to retrieve distinguished names
Function | Description |
---|---|
ldap_get_dn() |
Get the distinguished name for an entry. |
ldap_explode_dn() |
Split up a distinguished name into its components. |
ldap_explode_rdn() |
Split up a relative distinguished name into its components. |
Working with LDAPv3 Controls
Call the following functions to work with LDAPv3 controls.
Table 18-8 - Functions to work with LDAPv3 controls
Function | Description |
---|---|
ldap_create_persistentsearch_control() |
Create a "persistent search" control to track changes in directory entries. |
ldap_create_sort_keylist(),
ldap_create_sort_control()
|
Create a "sorting" control to return sorted search results from the LDAP server. |
ldap_create_proxyauth_control() |
Create a "proxy authorization" control to allow an entry to act as a proxy for an alternate entry. |
ldap_add_ext(),
ldap_add_ext_s(),
ldap_compare_ext(),
ldap_compare_ext_s(),
ldap_delete_ext(),
ldap_delete_ext_s(),
ldap_extended_operation(),
ldap_extended_operation_s(),
ldap_modify_ext(),
ldap_modify_ext_s(),
ldap_rename(),
ldap_rename_s(),
ldap_sasl_bind(),
ldap_sasl_bind_s(),
ldap_search_ext(),
ldap_search_ext_s(),
ldap_abandon_ext()
|
Pass LDAP controls to the server. |
ldap_parse_result() |
Parse LDAP server controls from results sent from the server. |
ldap_get_entry_controls(),
ldap_parse_entrychange_control()
|
Parse an "entry change notification" control from an entry and retrieve information from the control. |
ldap_parse_sort_control() |
Parse "sorting" controls from results sent from the server. |
ldap_control_free() |
Free the memory allocated for an
LDAPControl structure.
|
ldap_controls_free() |
Free the memory allocated for an array of
LDAPControl structures.
|
ldap_unbind_ext() |
Lets you specifically name a server or client control when unbinding from the server. |
Working with LDAP URLs
Call the following functions to interpret LDAP URLs.
Table 18-9 - Functions to interpret LDAP URLs
Function | Description |
---|---|
ldap_is_ldap_url() |
Determine if a URL is an LDAP URL. |
ldap_url_parse() |
Split up an LDAP URL into its components. |
ldap_url_search(),
ldap_url_search_s(), or
ldap_url_search_st()
|
Perform the search specified by an LDAP URL. |
ldap_free_urldesc() |
Free the memory allocated for a parsed URL. |
Getting the Attribute Values for a Particular Language
Call the following functions to get the values from a particular language subtype in an attribute.
Table 18-10 - Functions to get language subtypes
Function | Description |
---|---|
ldap_get_lang_values() or
ldap_get_lang_values_len()
|
Get an attribute's value in a particular language. |
Handling Errors
Call the following functions to handle errors returned by the LDAP API functions.
Table 18-11 - Functions for error handling
Function | Description |
---|---|
ldap_parse_result() |
Get the error code resulting from an asynchronous LDAP operation. |
ldap_get_lderrno() |
Get information about the last error that occurred. |
ldap_set_lderrno() |
Set information about an error. |
ldap_err2string() |
Get the error message for a specific error code. |
ldapssl_err2string() |
Get the error message for a specific SSL error code. |
Freeing Memory
Call the following functions to free memory allocated by the LDAP API functions.
Table 18-12 - Functions to free memory
Function | Description |
---|---|
ldap_memfree() |
Free memory allocated by an LDAP API function call. |
ldap_mods_free() |
Free the structures allocated for adding or modifying entries in the directory. |
ldap_msgfree() |
Free the memory allocated for search results or other LDAP operation results. |
ldap_value_free() |
Free the memory allocated for the string values of an attribute. |
ldap_value_free_len() |
Free the memory allocated for the binary values of an attribute
(an array of berval
structures).
|
ber_bvfree() |
Free the memory allocated for a
berval structures.
|
ldap_getfilter_free() |
Free the filter configuration from memory. |
ldap_free_urldesc() |
Free the memory allocated for a parsed URL. |
ber_free() |
Free the memory allocated for a
BerElement structure.
|
ldap_control_free() |
Free the memory allocated for an
LDAPControl
structure
|
ldap_controls_free() |
Free the memory allocated for an array of
LDAPControl
structures.
|
ldap_free_sort_keylist() |
Free the memory allocated for an array of
LDAPsortkey
structures.
|
ber_bvfree()
Frees a berval structure from memory.
Syntax
#include <lber.h> void ber_bvfree( struct berval *bv );
Parameters
This function has the following parameters:
Table 18-13 - ber_bvfree() function parameters
bv |
Pointer to the berval
structure that you want to free from memory.
|
Description
The ber_bvfree()
function frees a
berval structure from memory. Call
this function to free berval
arguments passed back from the
ldap_extended_operation_s()
,
ldap_parse_extended_result()
,
ldap_sasl_bind_s()
, and
ldap_parse_sasl_bind_result()
functions.
See Also:
ldap_extended_operation_s(),
ldap_parse_extended_result(),
ldap_sasl_bind_s(),
ldap_parse_sasl_bind_result().
ber_free()
The ber_free()
function frees a
BerElement
structure
from memory. Call this function to free any
BerElement
structures
that you have allocated.
Syntax
#include <ldap.h> void ber_free( BerElement *ber, int freebuf );
Parameters
This function has the following parameters:
Table 18-14 - ber_free() function parameters
ber |
Pointer to the
BerElement
structure that you want to free.
|
freebuf |
Specifies whether or not to free the buffer in the
BerElement structure.
|
Description
You can call this function to free
BerElement
structures
allocated by
ldap_first_attribute()
function calls and by
ldap_next_attribute()
function calls.
When freeing structures allocated by these functions, you should
specify 0
for the freebuf
argument. (These
functions do not allocate the extra buffer in the
BerElement
structure.)
For example, to retrieve attributes from a search result entry,
you need to call the
ldap_first_attribute()
function. Calling this function allocates a
BerElement
structure,
which is used to keep track of the current attribute. When you are
done working with the attributes, you should free this structure
from memory if the structure still exists.
Example
The following example frees the
BerElement
structure
allocated by the
ldap_first_attribute()
function.
Code Example 18-1 - ber_free() code example
LDAPMessage *a, *e; BerElement *ber; ... for ( a = ldap_first_attribute( ld, e, &ber ); a != NULL; a =ldap_next_attribute( ld, e, ber ) { ... /* Retrieve the value of each attribute */ ... } /* Free the BerElement when done */ if ( ber != NULL ) { ber_free( ber, 0 ); } ...
See Also:
ldap_first_attribute(),
ldap_next_attribute().
ldap_abandon()
Cancels ("abandons") an asynchronous LDAP operation that is in progress.
Note that this is an older function that is included in the LDAP
API for backward-compatibility. If you are writing a new LDAP client,
use ldap_abandon_ext()
instead.
Syntax
#include <ldap.h> int ldap_abandon( LDAP *ld, int msgid );
Parameters
This function has the following parameters:
Table 18-15 - ldap_abandon() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
msgid |
Message ID of an LDAP operation. |
Returns
One of the following values:
LDAP_SUCCESS
if successful.-
-1 if unsuccessful. The appropriate LDAP error code is also set in
the
LDAP
structure. You can retrieve the error code by calling theldap_get_lderrno()
function. Some of the possible LDAP result codes for this function include:-
LDAP_PARAM_ERROR
(if any of the arguments are invalid). -
LDAP_ENCODING_ERROR
(if an error occurred when BER-encoding the request). -
LDAP_SERVER_DOWN
(if the LDAP server did not receive the request or if the connection to the server was lost). LDAP_NO_MEMORY
(if memory cannot be allocated).
-
Description
The ldap_abandon()
function cancels ("abandons") an
asynchronous LDAP operation that is in progress.
A newer version of this function,
ldap_abandon_ext()
, is
available in this release of the LDAP API.
ldap_abandon()
(the older version of the function) is
included only for backward-compatibility. If you are writing a new
LDAP client, use
ldap_abandon_ext()
instead of ldap_abandon()
.
If you want more information on ldap_abandon()
,
refer to the LDAP C SDK 1.0 Programmer's Guide.
Example
The following example cancels an
ldap_url_search()
operation, abandoning the results of the operation.
Code Example 18-2 - Canceling an ldap_url_search() operation
LDAP *ld; char *url = "ldap://ldap.itd.umich.edu/c=US?o,description? one?o=umich"; int msgid; ... /* Initiate a search operation */ msgid = ldap_url_search( ld, url, 0 ); ... /* Abandon the search operation */ if ( ldap_abandon( ld, msgid ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldap_abandon" ); return( 1 ); } ...
See Also:
ldap_abandon_ext()
.
ldap_abandon_ext()
Cancels ("abandons") an asynchronous LDAP operation that is in
progress. For example, you can cancel an LDAP search operation that
you started with
ldap_search_ext()
.
Syntax
#include <ldap.h> int ldap_abandon_ext( LDAP *ld, int msgid, LDAPControl **serverctrls, LDAPControl **clientctrls );
Parameters
This function has the following parameters:
Table 18-16 - ldap_abandon_ext() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
msgid |
Message ID of the LDAP operation that you want to cancel. |
serverctrls |
Pointer to an array of
LDAPControl
structures representing LDAP server controls that apply to this
LDAP operation. If you do not want to pass any server controls,
specify NULL for this argument.
|
clientctrls |
Pointer to an array of
LDAPControl
structures representing LDAP client controls that apply to this
LDAP operation. If you do not want to pass any client controls,
specify NULL for this argument.
|
Returns
One of the following values:
LDAP_SUCCESS
if successful.LDAP_PARAM_ERROR
if any of the arguments are invalid.-
LDAP_ENCODING_ERROR
if an error occurred when BER-encoding the request. -
LDAP_SERVER_DOWN
if the LDAP server did not receive the request or if the connection to the server was lost. LDAP_NO_MEMORY
if memory cannot be allocated.
Description
The ldap_abandon()
function cancels ("abandons") an
asynchronous LDAP operation that is in progress. For example, if you
called ldap_search_ext()
to initiate an LDAP search operation on the server, you can call
ldap_abandon_ext()
to cancel the LDAP search operation.
This function is a new version of the
ldap_abandon()
function. If you are writing a new LDAP client, you should call this
function instead of
ldap_abandon()
.
When you call this function, your LDAP client sends a request to
cancel an operation being processed by the LDAP server. To identify
the operation to be cancelled, specify the message ID of the
operation in the msgid
argument.
(When you call an asynchronous function such as
ldap_search_ext()
and
ldap_modify_ext()
, the
msgidp
argument of the function returns a pointer to a
message ID that identifies the operation. For example, when you call
ldap_search_ext()
to
start an LDAP search operation on the server, the msgidp
argument returns a pointer to a message ID identifying that LDAP
search operation.)
When you call ldap_abandon_ext()
, the function
checks to see if the results of the operation have already been
returned. If so, ldap_abandon_ext()
deletes the message
ID from the queue of pending messages. If the results have not been
returned, ldap_abandon_ext()
sends a request to abandon
the operation on the LDAP server.
Once you cancel an operation, results of the operation will not
be returned, even if you subsequently call
ldap_result()
to try
to get the results.
For more information, see "Canceling an Operation in Progress."
Example
The following example cancels an
ldap_url_search()
operation, abandoning the results of the operation.
Code Example 18-3 - ldap_abandon_ext() code example
char *url = "ldap://ldap.itd.umich.edu/c=US?o,description?one?o=umich"; int msgid; LDAPControl **srvrctrls, **clntctrls; ... /* Initiate a search operation */ msgid = ldap_url_search( ld, url, 0 ); ... /* Abandon the search operation */ if ( ldap_abandon_ext( ld, msgid, srvrctrls, clntctrls ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldap_abandon" ); return( 1 ); } ...
See Also:
ldap_add_ext(),
ldap_compare_ext(),
ldap_delete_ext(),
ldap_extended_operation(),
ldap_modify_ext(),
ldap_rename(),
ldap_sasl_bind(),
ldap_search_ext(),
ldap_simple_bind(),
ldap_url_search().
ldap_add()
Adds a new entry to the directory asynchronously.
Note that this is an older function that is included in the LDAP
API for backward-compatibility. If you are writing a new LDAP
client, use
ldap_add_ext()
instead.
Syntax
#include <ldap.h> int ldap_add( LDAP *ld, const char *dn, LDAPMod **attrs );
Parameters
This function has the following parameters:
Table 18-17 - ldap_add() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
dn |
Distinguished name (DN) of the entry to add. With the exception
of the leftmost component, all components of the distinguished
name (for example, o=organization or c=country ) must
already exist.
|
attrs |
Pointer to a NULL -terminated array of pointers to
LDAPMod structures
representing the attributes of the new entry.
|
Returns
The message ID of the ldap_add()
operation. To check
the result of this operation, call
ldap_result()
and
ldap_result2error()
.
See the result code documentation for the
ldap_add_ext_s()
function for a list of possible result codes for the LDAP add
operation.
Description
The ldap_add()
function adds a new entry to the
directory asynchronously.
A newer version of this function,
ldap_add_ext()
, is
available in this release of the LDAP API. ldap_add()
(the older version of the function) is included only for
backward-compatibility. If you are writing a new LDAP client, use
ldap_add_ext()
instead
of ldap_add()
.
If you want more information on ldap_add()
, refer to
the LDAP C SDK 1.0 Programmer's Guide.
Example
The following example adds a new entry to the directory.
Code Example 18-4 - ldap_add() code example
... LDAP *ld; LDAPMod *list_of_attrs[4]; LDAPMod attribute1, attribute2, attribute3; LDAPMessage *result; int msgid, rc; struct timeval tv; /* Distinguished name of the new entry. Note that "dc=example,dc=com" and "ou=People, dc=example,dc=com" must already exist in the directory. */ char *dn = "uid=bjensen, ou=People, dc=example,dc=com"; /* To add a "person" entry, you must specify values for the sn, cn, and objectClass attributes. (These are required attributes.) */ char *sn_values[] = { "Jensen", NULL }; /* To specify multiple values for an attribute, add the different values to the array. */ char *cn_values[] = { "Barbara Jensen", "Babs Jensen", NULL }; /* The object class for a "person" entry is "inetOrgPerson", which is a subclass of "top", "person", and "organizationalPerson". You should add all of these classes as values of the objectClass attribute. */ char *objectClass_values[] = { "top", "person", "organizationalPerson", "inetOrgPerson", NULL }; ... /* Specify the value and type of each attribute in separate LDAPMod structures */ attribute1.mod_type = "sn"; attribute1.mod_values = sn_values; attribute2.mod_type = "cn"; attribute2.mod_values = cn_values; attribute3.mod_type = "objectClass"; attribute3.mod_values = objectClass_values; /* Add the pointers to these LDAPMod structures to an array */ list_of_attrs[0] = &attribute1; list_of_attrs[1] = &attribute2; list_of_attrs[2] = &attribute3; list_of_attrs[3] = NULL; ... /* Set up the timeout period for adding the new entry */ tv.tv_sec = tv.tv_usec = 0; /* Add the user "Barbara Jensen" */ if ( ( msgid = ldap_add( ld, dn, list_of_attrs ) ) == -1 ) { ldap_perror( ld, "ldap_add" ); return( 1 ); } /* Check to see if the operation has completed */ while ( ( rc = ldap_result( ld, msgid, 0, &tv, &result ) ) == 0 ) { ... /* do other work while waiting for the operation to complete */ ... } /* Check the result to see if any errors occurred */ if (( rc = ldap_result2error( ld, result, 1 )) != LDAP_SUCCESS ) { printf( "Error while adding entry: %s\n", ldap_err2string( rc )); } ...
See Also:
ldap_add_ext().
ldap_add_ext()
Adds a new entry to the directory asynchronously.
Syntax
#include <ldap.h> int ldap_add_ext( LDAP *ld, const char *dn, LDAPMod **attrs, LDAPControl **serverctrls, LDAPControl **clientctrls, int *msgidp );
Parameters
This function has the following parameters:
Table 18-18 - ldap_add_ext() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
dn |
Distinguished name (DN) of the entry to add. With the exception
of the leftmost component, all components of the distinguished
name (for example, o=organization or c=country ) must
already exist.
|
attrs |
Pointer to a NULL -terminated array of pointers to
LDAPMod structures
representing the attributes of the new entry.
|
serverctrls |
Pointer to an array of
LDAPControl
structures representing LDAP server controls that apply to this
LDAP operation. If you do not want to pass any server controls,
specify NULL for this argument.
|
clientctrls |
Pointer to an array of
LDAPControl
structures representing LDAP client controls that apply to this
LDAP operation. If you do not want to pass any client controls,
specify NULL for this argument.
|
msgidp |
Pointer to an integer that will be set to the message ID of the
LDAP operation. To check the result of this operation, call
ldap_result() and
ldap_parse_result()
functions.
|
Returns
One of the following values:
LDAP_SUCCESS
if successful.LDAP_PARAM_ERROR
if any of the arguments are invalid.-
LDAP_ENCODING_ERROR
if an error occurred when BER-encoding the request. -
LDAP_SERVER_DOWN
if the LDAP server did not receive the request or if the connection to the server was lost. LDAP_NO_MEMORY
if memory cannot be allocated.-
LDAP_NOT_SUPPORTED
if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAPv3 protocol. Make sure that you set the version of your LDAP client to version 3 before calling this function. (For details, see "Specifying the LDAP Version of Your Client.")
Description
The ldap_add_ext()
adds a new entry to the directory
asynchronously.
This function is a new version of the
ldap_add()
function.
If you are writing a new LDAP client, you should call this function
instead of ldap_add()
.
To add a new entry to the directory, you need to specify the following information:
-
A unique DN identifying the new entry.
Use the
dn
argument to specify the DN of the new entry. Note that the parents of the entry should already exist. For example, if you are adding the entryuid=bjensen, ou=People, dc=example,dc=com
, the entriesou=People, dc=example,dc=com
anddc=example,dc=com
should already exist in the directory. -
A set of attributes for the new entry.
Create an
LDAPMod
structure for each attribute. Set themod_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 themod_op
field toLDAP_MOD_BVALUES
. Create an array of theseLDAPMod
structures and pass the array as theattrs
argument.
ldap_add_ext()
is an asynchronous function; it does
not directly return results. If you want the results to be returned
directly by the function, call the synchronous function
ldap_add_ext_s()
instead. (For more information on asynchronous and synchronous
functions, see "Calling Synchronous and
Asynchronous Functions.")
In order to get the results of the LDAP add operation, you need
to call the
ldap_result()
function
and the
ldap_parse_result()
function. (See "Calling Asynchronous
Functions" for details.) For a list of possible result codes for
an LDAP add operation, see the result code documentation for the
ldap_add_ext_s()
function.
For additional information on adding new entries to the directory, see "Adding a New Entry."
Example
See the example under "Example: Adding an Entry to the Directory (Asynchronous)."
See Also:
ldap_add_ext_s(),
ldap_result(),
ldap_parse_result(),
LDAPMod.
ldap_add_ext_s()
Adds a new entry to the directory synchronously.
Syntax
#include <ldap.h> int ldap_add_ext_s( LDAP *ld, const char *dn, LDAPMod **attrs, LDAPControl **serverctrls, LDAPControl **clientctrls );
Parameters
This function has the following parameters:
Table 18-19 - ldap_add_ext_s() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
dn |
Distinguished name (DN) of the entry to add. With the exception
of the leftmost component, all components of the distinguished
name (for example, o= or c=country ) must already
exist.
|
attrs |
Pointer to a NULL-terminated array of pointers to
LDAPMod structures
representing the attributes of the new entry.
|
serverctrls |
Pointer to an array of
LDAPControl
structures representing LDAP server controls that apply to this
LDAP operation. If you do not want to pass any server controls,
specify NULL for this argument.
|
clientctrls |
Pointer to an array of
LDAPControl
structures representing LDAP client controls that apply to this
LDAP operation. If you do not want to pass any client controls,
specify NULL for this argument.
|
Returns
One of the following values:
LDAP_SUCCESS
if successful.LDAP_PARAM_ERROR
if any of the arguments are invalid.-
LDAP_ENCODING_ERROR
if an error occurred when BER-encoding the request. -
LDAP_SERVER_DOWN
if the LDAP server did not receive the request or if the connection to the server was lost. LDAP_NO_MEMORY
if memory cannot be allocated.-
LDAP_LOCAL_ERROR
if an error occurred when receiving the results from the server. -
LDAP_DECODING_ERROR
if an error occurred when decoding the BER-encoded results from the server. -
LDAP_NOT_SUPPORTED
if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAPv3 protocol. Make sure that you set the version of your LDAP client to version 3 before calling this function. (For details, see "Specifying the LDAP Version of Your Client.")
The following result codes can be returned by the Netscape Directory Server when processing an LDAP add request. Other LDAP servers may send these result codes under different circumstances or may send different result codes back to your LDAP client.
-
LDAP_OPERATIONS_ERROR
may be sent by the Netscape Directory Server for general errors encountered by the server when processing the request. -
LDAP_PROTOCOL_ERROR
if the add request sent by this function did not comply with the LDAP protocol (for example, if the server encountered an error when decoding your client's BER-encoded request). -
LDAP_CONSTRAINT_VIOLATION
may be sent by the Netscape Directory Server if the server is configured to require a minimum password length and the new entry includes a value for theuserpassword
attribute that is shorter than the minimum length. The server may also send this result code if the value of theuserpassword
attribute is the same as the value of theuid
,cn
,sn
,givenname
,ou
, ormail
attributes. (Using a password that is the same as your user id or email address would make the password trivial and easy to crack.) -
LDAP_TYPE_OR_VALUE_EXISTS
may be sent by the Netscape Directory Server if the set of attributes specified by theattrs
argument includes duplicate attribute values. -
LDAP_INVALID_DN_SYNTAX
may be sent by the Netscape Directory Server if the DN specified by thedn
argument is not a valid DN. -
LDAP_ALREADY_EXISTS
may be sent by the Netscape Directory Server if the DN specified by thedn
argument identifies an entry already in the directory. -
LDAP_OBJECT_CLASS_VIOLATION
may be sent by the Netscape Directory Server if the new entry does not comply with the Directory Server schema (for example, if one or more required attributes are not specified). -
LDAP_NO_SUCH_OBJECT
may be sent by the Netscape Directory Server if the parent of the entry does not exist and if you are not authenticated as the root DN (for example, if you attempt to adduid=bjensen, ou=People, dc=example,dc=com
and ifou=People, dc=example,dc=com
does not exist). This result code may also be sent if the DN of the new entry has a suffix that is not handled by the current server and no referral URLs are available. -
LDAP_REFERRAL
may be sent by the Netscape Directory Server if the DN specified by thedn
argument identifies an entry not handled by the current server and if referral URLs identify a different server to handle the entry. (For example, if the DN isuid=bjensen, ou=European Sales, dc=example,dc=com
, all entries underou=European Sales
might be handled by a different Directory Server.) -
LDAP_UNWILLING_TO_PERFORM
may be sent by the Netscape Directory Server if the server's database is set up to not allow write operations to the database (the database is read-only). -
LDAP_INVALID_SYNTAX
may be sent by the Netscape Directory Server if the entry or the entry's parent has an invalid ACL. -
LDAP_INSUFFICIENT_ACCESS
may be sent by the Netscape Directory Server in the following situations:- The ACL for the entry's parent does not allow you to add the entry.
- The entry's parent has no ACL.
- The entry has no parent and your client is not authenticated as the root DN.
Note that the Directory Server may send other result codes in addition to the codes described here (for example, the server may have loaded a custom plug-in that returns other result codes).
Description
The ldap_add_ext_s()
function adds a new entry to
the directory synchronously.
This function is a new version of the
ldap_add_s()
function.
If you are writing a new LDAP client, you should call this function
instead of ldap_add_s()
.
To add a new entry to the directory, you need to specify the following information:
-
A unique DN identifying the new entry.
Use the
dn
argument to specify the DN of the new entry. Note that the parents of the entry should already exist. For example, if you are adding the entryuid=bjensen, ou=People, dc=example,dc=com
, the entriesou=People, dc=example,dc=com
anddc=example,dc=com
should already exist in the directory. -
A set of attributes for the new entry.
Create an
LDAPMod
structure for each attribute. Set themod_op
field to0
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 themod_op
field toLDAP_MOD_BVALUES
. Create an array of theseLDAPMod
structures and pass the array as theattrs
argument.
ldap_add_ext_s()
is a synchronous function, which
directly returns the results of the operation. If you want to
perform other operations while waiting for the results of this
operation, call the asynchronous function
ldap_add_ext()
instead. (For more information on asynchronous and synchronous
functions, see "Calling Synchronous and
Asynchronous Functions.")
For additional information on adding new entries to the directory, see "Adding a New Entry."
Example
See the example under "Example: Adding an Entry to the Directory (Synchronous)."
See Also:
ldap_add_ext(),
LDAPMod.
ldap_add_s()
Adds a new entry to the directory synchronously.
Note that this is an older function that is included in the LDAP
API for backward-compatibility. If you are writing a new LDAP client,
use ldap_add_ext_s()
instead.
Syntax
#include <ldap.h> int ldap_add_s( LDAP *ld, const char *dn, LDAPMod **attrs );
Parameters
This function has the following parameters:
Table 18-20 - ldap_add_s() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
dn |
Distinguished name (DN) of the entry to add. With the exception
of the leftmost component, all components of the distinguished
name (for example, o=organization or c=>country )
must already exist.
|
attrs |
Pointer to a NULL -terminated array of pointers to
LDAPMod structures
representing the attributes of the new entry.
|
Returns
See the result code documentation for the
ldap_add_ext_s()
function for a list of possible return codes for the LDAP add
operation.
Description
The ldap_add_s()
function adds a new entry to the
directory synchronously.
A newer version of this function,
ldap_add_ext_s()
, is
available in this release of the LDAP API. ldap_add_s()
(the older version of the function) is included only for
backward-compatibility. If you are writing a new LDAP client, use
ldap_add_ext_s()
instead of ldap_add_s()
.
If you want more information on ldap_add_s()
, refer
to the LDAP C SDK 1.0 Programmer's Guide.
Example
The following example adds a new entry to the directory.
Code Example 18-5 - ldap_add_s code example
... LDAP *ld; LDAPMod *list_of_attrs[4]; LDAPMod attribute1, attribute2, attribute3; /* Distinguished name of the new entry. Note that "dc=example,dc=com" and "ou=People, dc=example,dc=com" must already exist in the directory. */ char *dn = "uid=bjensen, ou=People, dc=example,dc=com"; /* To add a "person" entry, you must specify values for the sn, cn, and objectClass attributes. (These are required attributes.) */ char *sn_values[] = { "Jensen", NULL }; /* To specify multiple values for an attribute, add the different values to the array. */ char *cn_values[] = { "Barbara Jensen", "Babs Jensen", NULL }; /* The object class for a "person" entry is "inetOrgPerson", which is a subclass of "top", "person", and "organizationalPerson". You should add all of these classes as values of the objectClass attribute. */ char *objectClass_values[] = { "top", "person", "organizationalPerson", "inetOrgPerson", NULL }; ... /* Specify the value and type of each attribute in separate LDAPMod structures */ attribute1.mod_type = "sn"; attribute1.mod_values = sn_values; attribute2.mod_type = "cn"; attribute2.mod_values = cn_values; attribute3.mod_type = "objectClass"; attribute3.mod_values = objectClass_values; /* Add the pointers to these LDAPMod structures to an array */ list_of_attrs[0] = &attribute1; list_of_attrs[1] = &attribute2; list_of_attrs[2] = &attribute3; list_of_attrs[3] = NULL; ... /* Add the user "Barbara Jensen" */ if ( ldap_add_s( ld, dn, list_of_attrs ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldap_add_s" ); return( 1 ); } ...
See Also:
ldap_add_ext_s().
ldap_ber_free()
This function is documented here only for backward compatibility;
you should use the
ber_free()
function
in its place since this function will be phased out over time.
Except in name, the function ldap_ber_free()
is
idendical to ber_free()
.
Syntax
#include <ldap.h> void ldap_ber_free( BerElement *ber, int freebuf );
Parameters
This function has the following parameters:
Table 18-21 - ldap_ber_free() function parameters
ber |
Pointer to the
BerElement structure
that you want to free.
|
freebuf |
Specifies whether or not to free the buffer in the
BerElement structure.
|
ldap_build_filter()
The ldap_build_filter()
function is a deprecated
function. Use the
ldap_create_filter()
function instead.
ldap_compare()
Asynchronously determines if an attribute of an entry contains a specified value.
Note that this is an older function that is included in the LDAP
API for backward-compatibility. If you are writing a new LDAP
client, use
ldap_compare_ext()
instead.
Syntax
#include <ldap.h> int ldap_compare( LDAP *ld, const char *dn, const char *attr, const char *value );
Parameters
This function has the following parameters:
Table 18-22 - ldap_compare() function parameters
ld |
Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server. |
dn |
Distinguished name (DN) of the entry used in the comparison. |
attr |
Attribute type that you want to check the value against. |
value |
Value that you want to compare against the attribute values. |
Returns
Returns the message ID of the ldap_compare()
operation. To check the result of this operation, call
ldap_result()
and
ldap_result2error()
.
For a list of possible return codes for the LDAP compare operation,
see the result code documentation for the
ldap_compare_ext_s()
function.
Description
The ldap_compare()
function compares a value with
the value of an attribute in an entry.
A newer version of this function,
ldap_compare_ext()
, is
available in this release of the LDAP API. ldap_compare()
(the older version of the function) is included only for
backward-compatibility. If you are writing a new LDAP client, use
ldap_compare_ext()
instead of ldap_compare()
.
If you want more information on ldap_compare()
,
refer to the LDAP C SDK 1.0 Programmer's Guide.
Example
The following section of code checks to see if Barbara Jensen has
the e-mail address "bjensen@example.com
".
Code Example 18-6 - Using ldap_compare()
>#include <stdio.h> #include <ldap.h> ... LDAP *ld; char *dn = "uid=bjensen, ou=People, dc=example,dc=com"; int msgid; ... msg_id = ldap_compare( ld, dn, "mail", "bjensen@example.com" ); ...
See Also:
ldap_compare_ext()
ldap_compare_ext()
Asynchronously determines if an attribute of an entry contains a specified value.
Syntax
#include <ldap.h> int ldap_compare_ext( LDAP *ld, const char *dn, const char *attr, struct berval *bvalue, LDAPControl **serverctrls, LDAPControl **clientctrls, int *msgidp );
Parameters
This function has the following parameters:
Table 18-23 - ldap_compare_ext() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
dn |
Distinguished name (DN) of the entry used in the comparison. |
attr |
Attribute type that you want to check the value against. |
value |
Value that you want to compare against the attribute values. |
serverctrls |
Pointer to an array of
LDAPControl
structures representing LDAP server controls that apply to this
LDAP operation. If you do not want to pass any server controls,
specify NULL for this argument.
|
clientctrls |
Pointer to an array of
LDAPControl
structures representing LDAP client controls that apply to this
LDAP operation. If you do not want to pass any client controls,
specify NULL for this argument.
|
msgidp |
Pointer to an integer that will be set to the message ID of the
LDAP operation. To check the result of this operation, call the
ldap_result() and
ldap_parse_result()
functions.
|
Returns
One of the following values:
LDAP_SUCCESS
if successful.LDAP_PARAM_ERROR
if any of the arguments are invalid.-
LDAP_ENCODING_ERROR
if an error occurred when BER-encoding the request. -
LDAP_SERVER_DOWN
if the LDAP server did not receive the request or if the connection to the server was lost. LDAP_NO_MEMORY
if memory cannot be allocated.-
LDAP_NOT_SUPPORTED
if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAPv3 protocol. Make sure that you set the version of your LDAP client to version 3 before calling this function. (For details, see "Specifying the LDAP Version of Your Client.")
Description
The ldap_compare_ext()
function asynchronously
compares the value of an attribute in an entry against a specified
value.
This function is a new version of the
ldap_compare()
function. If you are writing a new LDAP client, you should call this
function instead of
ldap_compare()
.
ldap_compare_ext()
is an asynchronous function; it
does not directly return results. If you want the results to be
returned directly by the function, call the synchronous function
ldap_compare_ext_s()
instead. (For more information on asynchronous and synchronous
functions, see "Calling Synchronous and
Asynchronous Functions.")
In order to get the results of the LDAP compare operation, you
need to call the
ldap_result()
function
and the ldap_parse_result()
function. (See "Calling Asynchronous
Functions" for details.) For a list of possible result codes for
an LDAP compare operation, see the result code documentation for the
ldap_compare_ext_s()
function.
For additional information on comparing attribute values in an entry, see "Comparing the Value of an Attribute."
Example
See the example under "Example: Comparing a Value in an Entry (Asynchronous)."
See Also:
ldap_compare_ext_s(),
ldap_result(),
ldap_parse_result().
ldap_compare_ext_s()
Synchronously determines if an attribute of an entry contains a specified value.
Syntax
#include <ldap.h> int ldap_compare_ext_s( LDAP *ld, const char *dn, const char *attr, struct berval *bvalue, LDAPControl **serverctrls, LDAPControl **clientctrls );
Parameters
This function has the following parameters:
Table 18-24 - ldap_compare_ext_s() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
dn |
Distinguished name (DN) of the entry used in the comparison. |
attr |
Attribute type that you want to check the value against. |
value |
Value that you want to compare against the attribute values. |
serverctrls |
Pointer to an array of
LDAPControl
structures representing LDAP server controls that apply to this
LDAP operation. If you do not want to pass any server controls,
specify NULL for this argument.
|
clientctrls |
Pointer to an array of
LDAPControl
structures representing LDAP client controls that apply to this
LDAP operation. If you do not want to pass any client controls,
specify NULL for this argument.
|
Returns
One of the following values:
-
LDAP_COMPARE_TRUE
if the entry contains the attribute value. -
LDAP_COMPARE_FALSE
if the entry does not contain the attribute value. LDAP_PARAM_ERROR
if any of the arguments are invalid.-
LDAP_ENCODING_ERROR
if an error occurred when BER-encoding the request. -
LDAP_SERVER_DOWN
if the LDAP server did not receive the request or if the connection to the server was lost. LDAP_NO_MEMORY
if memory cannot be allocated.-
LDAP_LOCAL_ERROR
if an error occurred when receiving the results from the server. -
LDAP_DECODING_ERROR
if an error occurred when decoding the BER-encoded results from the server. -
LDAP_NOT_SUPPORTED
if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAPv3 protocol. Make sure that you set the version of your LDAP client to version 3 before calling this function. (For details, see "Specifying the LDAP Version of Your Client.")
The following result codes can be returned by the Netscape Directory Server when processing an LDAP compare request. Other LDAP servers may send these result codes under different circumstances or may send different result codes back to your LDAP client.
-
LDAP_OPERATIONS_ERROR
may be sent by the Netscape Directory Server for general errors encountered by the server when processing the request. -
LDAP_PROTOCOL_ERROR
if the compare request sent by this function did not comply with the LDAP protocol (for example, if the server encountered an error when decoding your client's BER-encoded request). -
LDAP_NO_SUCH_OBJECT
may be sent by the Netscape Directory Server if the specified entry has a suffix that is not handled by the current server and no referral URLs are available. -
LDAP_REFERRAL
may be sent by the Netscape Directory Server if the DN specified by thedn
argument identifies an entry not handled by the current server and if referral URLs identify a different server to handle the entry. (For example, if the DN isuid=bjensen, ou=European Sales, dc=example,dc=com
, all entries underou=European Sales
might be handled by a different Directory Server.) -
LDAP_INSUFFICIENT_ACCESS
may be sent by the Netscape Directory Server if your client does not have the access right to compare this entry. -
LDAP_INVALID_SYNTAX
may be sent by the Netscape Directory Server if the entry or the entry's parent has an invalid ACL. -
LDAP_NO_SUCH_ATTRIBUTE
may be sent by the Netscape Directory Server if the entry does not contain the attribute specified by theattr
argument.
Note that the Netscape Directory Server may send other result codes in addition to the codes described here (for example, the server may have loaded a custom plug-in that returns other result codes).
Description
The ldap_compare_ext_s()
function synchronously
compares the value of an attribute in an entry against a specified
value.
This function is a new version of the
ldap_compare_s()
function. If you are writing a new LDAP client, you should call this
function instead of
ldap_compare_s()
.
ldap_compare_ext_s()
is a synchronous function,
which directly returns the results of the operation. If you want to
perform other operations while waiting for the results of this
operation, call the asynchronous function
ldap_compare_ext()
instead. (For more information on asynchronous and synchronous
functions, see "Calling Synchronous and
Asynchronous Functions.")
For additional information on comparing attribute values in an entry, see "Comparing the Value of an Attribute."
Example
See the example under "Example: Comparing a Value in an Entry (Synchronous)."
See Also:
ldap_compare_ext()
.
ldap_compare_s()
Synchronously determines if an attribute of an entry contains a specified value.
Note that this is an older function that is included in the LDAP
API for backward-compatibility. If you are writing a new LDAP client,
use ldap_compare_ext_s()
instead.
Syntax
#include <ldap.h> int ldap_compare_s( LDAP *ld, const char *dn, const char *attr, const char *value );
Parameters
This function has the following parameters:
Table 18-25 - ldap_compare_s() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
dn |
Distinguished name (DN) of the entry used in the comparison. |
attr |
Attribute type that you want to check the value against. |
value |
Value that you want to compare against the attribute values. |
Returns
For a list of the possible result codes for an LDAP compare
operation, see the result code documentation for the
ldap_compare_ext_s()
function.
Description
The ldap_compare_s()
function compares a value with
the value of an attribute in an entry.
A newer version of this function,
ldap_compare_ext_s()
,
is available in this release of the LDAP API.
ldap_compare_s()
(the older version of the function) is
included only for backward-compatibility. If you are writing a new
LDAP client, use
ldap_compare_ext_s()
instead of ldap_compare_s()
.
If you want more information on ldap_compare_s()
,
refer to the LDAP C SDK 1.0 Programmer's Guide.
Example
The following section of code checks to see if Barbara Jensen has
the e-mail address "bjensen@example.com
".
Code Example 18-7 - ldap_compare_s() code example
#include <ldap.h> LDAP *ld; char *dn = "uid=bjensen, ou=People, dc=example,dc=com"; int has_value; ... has_value = ldap_compare_s( ld, dn, "mail", "bjensen@example.com" ); switch ( has_value ) { case LDAP_COMPARE_TRUE: printf( "The mail attribute contains bjensen@example.com.\n"); break; case LDAP_COMPARE_FALSE: printf( "The mail attribute does not contain bjensen@example.com.\n"); break; default: ldap_perror( ld, "ldap_compare_s" ); return( 1 ); } ...
See Also:
ldap_compare_ext_s().
ldap_control_free()
Frees an LDAPControl
structure from memory.
Syntax
#include <ldap.h> void ldap_control_free( LDAPControl *ctrl );
Parameters
This function has the following parameters:
Table 18-26 - ldap_control_free() function parameters
ctrl |
Pointer to an
LDAPControl
structure that you want to free from memory.
|
Description
The ldap_control_free()
function frees an
LDAPControl
structure
from memory.
You should call this function to free controls that you create
(for example, if you call the
ldap_create_sort_control()
function).
See Also:
ldap_controls_free().
ldap_controls_free()
Frees an array of
LDAPControl
structures
from memory.
Syntax
#include <ldap.h> void ldap_controls_free( LDAPControl **ctrls );
Parameters
This function has the following parameters:
Table 18-27 - ldap_controls_free() function parameters
ctrls |
Pointer to an array of
LDAPControl
structures that you want to free from memory.
|
Description
The ldap_controls_free()
function frees an array of
LDAPControl
structures
from memory.
You should call this function to free arrays of controls that you
create or any arrays returned by
ldap_parse_result()
.
See Also:
ldap_control_free().
ldap_count_entries()
Returns the number of
LDAPMessage
structures
representing directory entries in a chain of search results.
Syntax
#include <ldap.h> int ldap_count_entries( LDAP *ld, LDAPMessage *result );
Parameters
This function has the following parameters:
Table 18-28 - ldap_count_entries() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
result |
Chain of search results, represented by the pointer to an
LDAPMessage
structure.
|
Returns
One of the following values:
-
The number of
LDAPMessage
structures of the typeLDAP_RES_SEARCH_ENTRY
in a chain of search results, if successful. (If there are no structures of this type, returns0
.) - -1 if
ld
is not a valid connection handle.
Description
The ldap_count_entries()
function returns the number
of LDAPMessage
structures representing directory entries in a chain of search
results. These messages have the type
LDAP_RES_SEARCH_ENTRY
.
Note that if you pass in a pointer to an
LDAPMessage
structure
in the middle of the chain of results, the function counts only the
entries between that structure and the last structure in the chain.
In this type of situation, the function does not return the count of
all entries in the chain.
For more information on using this function, see "Iterating Through a Chain of Results."
Example
See the examples under
ldap_search_ext()
and
ldap_search_ext_s()
.
See Also:
ldap_result(),
ldap_search_ext(),
ldap_search_ext_s(),
ldap_first_entry(),
ldap_next_entry(),
ldap_first_message(),
ldap_next_message().
ldap_count_messages()
Returns the number of
LDAPMessage
structures
in a chain of search results.
Syntax
#include <ldap.h> int ldap_count_messages( LDAP *ld, LDAPMessage *res );
Parameters
This function has the following parameters:
Table 18-29 - ldap_count_messages() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
result |
Chain of search results, represented by the pointer to an
LDAPMessage structure.
|
Returns
One of the following values:
-
The number of
LDAPMessage
structures in a chain of search results, if successful. (If there are no structures, returns0
.) -1
ifld
is not a valid connection handle.
Description
The ldap_count_messages()
function returns the
number of LDAPMessage
structures in a chain of search results.
Note that if you pass in a pointer to an
LDAPMessage
structure
in the middle of the chain of results, the function counts only
between that structure and the last structure in the chain. In this
type of situation, the function does not return the count of all
structures in the chain.
For more information on using this function, see "Iterating Through a Chain of Results."
Example
See the examples under
ldap_search_ext()
and
ldap_search_ext_s()
.
See Also:
ldap_result(),
ldap_search_ext(),
ldap_search_ext_s(),
ldap_first_message(),
ldap_next_message().
ldap_count_references()
Returns the number of
LDAPMessage
structures
representing search references in a chain of search results.
Syntax
#include <ldap.h> int ldap_count_references( LDAP *ld, LDAPMessage *res );
Parameters
This function has the following parameters:
Table 18-30 - ldap_count_references() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
result |
Chain of search results, represented by the pointer to an
LDAPMessage
structure.
|
Returns
One of the following values:
-
The number of
LDAPMessage
structures of the typeLDAP_RES_SEARCH_REFERENCE
in a chain of search results, if successful. (If there are no structures of this type, returns0
.) -1
ifld
is not a valid connection handle.
Description
The ldap_count_references()
function returns the
number of LDAPMessage
structures representing search references in a chain of search
results. These messages have the type
LDAP_RES_SEARCH_REFERENCE
.
Note that if you pass in a pointer to an
LDAPMessage
structure
in the middle of the chain of results, the function counts only the
references between that structure and the last structure in the
chain. In this type of situation, the function does not return the
count of all references in the chain.
For more information on using this function, see "Iterating Through a Chain of Results."
Example
See the examples under
ldap_search_ext()
and
ldap_search_ext_s()
.
See Also:
ldap_result(),
ldap_search_ext(),
ldap_search_ext_s(),
ldap_first_reference(),
ldap_next_reference().
ldap_count_values()
The ldap_count_values()
function returns the number
of values in an array of strings. Use the
ldap_count_values_len()
function instead of this function if the array contains
berval
structures.
For additional information, see "Getting the Values of an Attribute."
Syntax
#include <ldap.h> int ldap_count_values( char **values );
Parameters
This function has the following parameters:
Table 18-31 - ldap_count_values() function parameters
values |
Array of values. |
Returns
One of the following values:
- The number of values in the array, if successful.
-
-1
if unsuccessful. (See Chapter 19 - Result Codes for a complete listing.)
Example
The following section of code counts the number of values assigned to an attribute.
Code Example 18-8 - ldap_count_values() code example
#include <ldap.h> ... LDAP *ld; LDAPMessage *e; char *a="cn"; char **vals; int count; ... /* Get the values of the cn attribute */ vals = ldap_get_values( ld, e, a ); /* Count the values of the attribute */ count = ldap_count_values( vals ); ...
See Also:
ldap_count_values_len(),
ldap_get_values().
ldap_count_values_len()
The ldap_count_values_len()
function returns the
number of values in an array of
berval
structures. Use
the ldap_count_values()
function instead of this function if the array contains strings.
For additional information, see "Getting the Values of an Attribute."
Syntax
#include <ldap.h> int ldap_count_values_len( struct berval **vals );
Parameters
This function has the following parameters:
Table 18-32 - ldap_count_values_len() function parameters
values |
Array of berval structures. |
Returns
One of the following values:
- The number of values in the array, if successful.
-
-1
if unsuccessful. (See Chapter 19 - Result Codes for a complete listing.)
Example
The following section of code counts the number of values assigned to an attribute.
Code Example 18-9 - ldap_count_values_len() code example
#include <ldap.h> LDAP *ld; LDAPMessage *e; char *a="jpegPhoto"; struct berval **bvals; int count; ... /* Get the values of the jpegPhoto attribute */ bvals = ldap_get_values_len( ld, e, a ); /* Count the values of the attribute */ count = ldap_count_values_len( vals ); ...
See Also:
ldap_count_values(),
ldap_get_values_len().
ldap_create_filter()
The ldap_create_filter()
routine constructs an LDAP
search filter. For more information about filters, see
"Creating Filters Programmatically."
Syntax
#include <ldap.h> int ldap_create_filter( char *buf, unsigned long buflen, char *pattern, char *prefix, char *suffix, char *attr, char *value, char **valwords );
Parameters
This function has the following parameters:
Table 18-33 - ldap_create_filter() function parameters
buf |
Buffer to contain the constructed filter. |
buflen |
Size of the buffer. |
pattern |
Pattern for the filter. |
prefix |
Prefix to prepend to the filter (NULL if not used). |
suffix |
Suffix to append to the filter (NULL if not used). |
attr |
Replaces %a in the pattern. |
value |
Replaces %v in the pattern. |
valwords |
Replaces %vM through %vN in the pattern. |
Returns
One of the following values:
LDAP_SUCCESS
if successful.-
LDAP_SIZELIMIT_EXCEEDED
if the created filter exceeds the size of the buffer. -
LDAP_PARAM_ERROR
if an invalid parameter was passed to the function.
Example
The following section of code builds the filter
(mail=bjensen@example.com)
.
Code Example 18-10 - Creating a filter with ldap_create_filter()
char buf[LDAP_FILT_MAXSIZ]; char *pattern = "(%a=%v)"; char *attr = "mail"; char *value = "bjensen@example.com"; ... ldap_create_filter( buf, LDAP_FILT_MAXSIZ, pattern, NULL, NULL, attr, value, NULL ); ...
See Also:
ldap_init_getfilter(),
ldap_init_getfilter_buf(),
ldap_getfirstfilter(),
ldap_getnextfilter(),
ldap_set_filter_additions().
ldap_create_persistentsearch_control()
Creates a control that allows your client to perform a persistent search of an LDAP v3 server, which allows the search operation to continue without termination until your client abandons the search.
This function implements an extension to the LDAPv3 protocol. Persistent search is an optional LDAP server feature; it may not be supported on all LDAP servers. Call this function when interacting with LDAP servers that support this LDAPv3 extension.
Syntax
#include <ldap.h> int ldap_create_persistentsearch_control( LDAP *ld, int changetypes, int changesonly, int return_echg_ctls, char ctl_iscritical, LDAPControl **ctrlp );
Parameters
This function has the following parameters:
Table 18-34 - ldap_create_persistentsearch_control() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
changetypes |
Specifies the types of changes that you want to keep track of.
This field can have one or more of the following values (you can
OR the values together to specify multiple types):
|
changesonly |
Specifies whether or not you want skip the initial search and
only get the latest changes as they occur:
|
return_echg_ctls |
Specifies whether or not entry change notification controls are
included with each entry returned to your client:
|
ctl_iscritical |
Specifies whether or not the persistent search control is
critical to the search operation:
|
ctrlp |
Pointer to a pointer to an
LDAPControl
structure that will be created by this function. When you are
done using this control, you should free it by calling the
ldap_control_free()
function.
|
Returns
One of the following values:
LDAP_SUCCESS
if successful.-
LDAP_PARAM_ERROR
if an invalid parameter was passed to the function. LDAP_NO_MEMORY
if memory cannot be allocated.-
LDAP_ENCODING_ERROR
if an error occurred when BER-encoding the control.
Description
The ldap_create_persistentsearch_control()
function
allows you to perform persistent searches. A persistent search
provides the means to track changes to a set of entries that match
the search criteria. After the initial search is performed, the
server keeps track of the search criteria and sends back information
when any entry that matches the criteria is added, deleted,
modified, or renamed.
Calling this function creates an LDAP server control that you can
pass to the
ldap_search_ext()
function.
In order for the control to work, the LDAP server that you are
connecting to must support the server control for persistent searches
(OID 2.16.840.1.113730.3.4.3, or
LDAP_CONTROL_PERSISTENTSEARCH
, as defined in the
ldap.h
header file). See
"Determining the Controls Supported By
the Server" for information on determining the controls
supported by a server.
After you create the control, you can pass it to the LDAP server
during a search operation. (Pass the server control when calling the
ldap_search_ext()
function.) If you specify that you want "entry change notification"
controls sent back (that is, if you specify a non-zero value for the
return_echg_ctls
argument), the server includes
controls with each changed entry it sends back.
To retrieve the "entry change notification control" from each
entry, call the
ldap_get_entry_controls()
function. To get data about the changes made to the entry from the
control, call the
ldap_parse_entrychange_control()
function.
When you are done with the search, you can cancel the persistent
search by calling the
ldap_abandon_ext()
function. You should also free the control from memory by calling
the ldap_control_free()
function.
See Also:
ldap_search_ext(),
ldap_abandon_ext(),
ldap_get_entry_controls(),
ldap_parse_entrychange_control(),
ldap_control_free().
ldap_create_proxyauth_control()
You use ldap_create_proxyauth_control()
to create an
LDAPv3 control that allows a bound entity to assume the identity of
another directory entry.
This function implements the proxy authorization extension of the LDAPv3 protocol. Proxy authorization is an optional LDAP server feature and it may not be supported on all LDAP servers.
Syntax
#include <ldap.h> int ldap_create_proxyauth_control( LDAP *ld, char *DN, char ctl_iscritical, LDAPControl **ctrlp);
Parameters
This function has the following parameters:
Table 18-35 - ldap_create_proxyauth_control() function parameters
ld |
Connection handle, which is a pointer to an LDAP
structure containing information about the connection to the LDAP
server. |
---|---|
DN |
String representing the distinguished name of the entry who's identity the client will be assuming. |
ctl_iscritical |
Specifies whether the persistent search control is critical to
the search operation. For proxy authorization controls, this
should be set to a non-zero value.
If non-zero, the control is critical to the directory operation.
If the server does not support proxy authentication, the server
will return an LDAP_UNAVAILABLE_CRITICAL_EXTENSION
error.
If 0 , the control is not critical to the
directory operation. Even if the server does not support proxied
authorization, the operation is still attempted and the proxied
authorization control is ignored.
|
ctrlp |
Pointer to a pointer to an LDAPControl structure
that is created by this function. When you are done using this
control, you should free it by calling the
ldap_control_free() function.
|
Returns
One of the following values:
LDAP_SUCCESS
if successful.-
LDAP_PARAM_ERROR
if an invalid parameter was passed to the function. LDAP_NO_MEMORY
if memory cannot be allocated.-
LDAP_ENCODING_ERROR
if an error occurred when BER-encoding the control. -
LDAP_UNAVAILABLE_CRITICAL_EXTENSION
if the server does not support proxied authorization and ctl_iscritical is set to a non-zero value.
See Also:
ldap_control_free()
ldap_create_sort_control()
Creates a control that specifies the order in which you want search results returned.
This function implements an extension to the LDAPv3 protocol. Server-side sorting is an optional LDAP server feature; it may not be supported on all LDAP servers. Call this function when interacting with LDAP servers that support this LDAPv3 extension.
Syntax
#include <ldap.h> int ldap_create_sort_control( LDAP *ld, LDAPsortkey **sortKeyList, const char ctl_iscritical, LDAPControl **ctrlp );
Parameters
This function has the following parameters:
Table 18-36 - ldap_create_sort_control() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
sortKeyList |
Pointer to an array of
LDAPsortkey
structures that specify the attribute types or matching rules
used for sorting and the order (ascending or descending) in which
to sort the results.
|
ctl_iscritical |
Specifies whether or not the control is critical to the search
operation. This field can have one of the following values:
|
ctrlp |
Pointer to a pointer to an
LDAPControl
structure that will be created by this function. When you are
done using this control, you should free it by calling the
ldap_control_free()
function.
|
Returns
One of the following values:
LDAP_SUCCESS
if successful.-
LDAP_PARAM_ERROR
if an invalid parameter was passed to the function. LDAP_NO_MEMORY
if memory cannot be allocated.-
LDAP_ENCODING_ERROR
if an error occurred when BER-encoding the control.
Description
The ldap_create_sort_control()
function allows you
to specify the order in which you want to receive data from the
server. Calling this function creates an LDAP control that you can
pass to the
ldap_search_ext()
and
ldap_search_ext_s()
functions.
In order for the control to work, the LDAP server that you are
connecting to must support the server control for sorting search
results (OID 1.2.840.113556.1.4.473, or
LDAP_CONTROL_SORTREQUEST
as defined in
ldap.h
). See "Determining
the Controls Supported By the Server" for information on
determining the controls supported by a server.
To specify the attributes to use for sorting the results, you can
call ldap_create_sort_keylist()
to create an array of
LDAPsortkey
structures
and pass the array as the sortKeyList
argument.
When you are done with the search, you should free the control
and the array of LDAPsortkey
structures by calling the
ldap_control_free()
function and the
ldap_free_sort_keylist()
function.
See Also:
ldap_create_sort_keylist(),
ldap_search_ext(),
ldap_search_ext_s(),
ldap_control_free().
ldap_create_sort_keylist()
Creates an array of
LDAPsortkey
structures
from a string representation of a set of sort keys.
Syntax
#include <ldap.h> int ldap_create_sort_keylist(LDAPsortkey ***sortKeyList, const char *string_rep);
Parameters
This function has the following parameters:
Table 18-37 - ldap_create_sort_keylist() function parameters
sortKeyList |
Pointer to an array of
LDAPsortkey
structures that specify the attribute types or matching rules
used for sorting and the order (ascending or descending) in which
to sort the results.
|
string_rep |
String representation of a set of sort keys. |
Returns
One of the following values:
LDAP_SUCCESS
if successful.-
LDAP_PARAM_ERROR
if an invalid parameter was passed to the function. LDAP_NO_MEMORY
if memory cannot be allocated.-1
if an error occurred
Description
The ldap_create_sort_keylist()
function allows you
to create an array of
LDAPsortkey
structures
from a string representation of a set of sort keys. Calling this
function creates an array of
LDAPsortkey
structures
that you can pass to the
ldap_create_sort_control()
function.
The string representation specified by the string_rep
argument should specify the name of the attribute that you want to
sort by.
- To sort in reverse order, precede the attribute name with a hyphen ("-").
- To use a matching rule for sorting, append a colon to the attribute name and specify the object identifier (OID) of a matching rule after the colon.
For example:
cn
(sort by the cn attribute)-cn
(sort by the cn attribute in reverse order)-
-cn:1.2.3.4
(sort by the cn attribute in reverse order and use the matching rule identified by the OID 1.2.3.4)
When you are done sorting the results, you should free the array
of LDAPsortkey
structures by calling the
ldap_free_sort_keylist()
function.
See Also:
ldap_create_sort_control(),
ldap_free_sort_keylist().
ldap_create_virtuallist_control()
Creates a control that requests a subset of search results for use in a virtual list box.
This function implements an extension to the LDAPv3 protocol. This control is supported by the Netscape Directory Server, version 4.0 and later. For information on determining if a server supports this or other LDAPv3 controls, see "Determining If the Server Supports LDAPv3".
Syntax
#include <ldap.h> int ldap_create_virtuallist_control( LDAP *ld, LDAPVirtualList *ldvlistp, LDAPControl **ctrlp );
Parameters
This function has the following parameters:
Table 18-38 - ldap_create_virtuallist_control() function parameters
ld |
Connection handle, which is a 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 a pointer to an
LDAPControl
structure that will be created by this function. When you are
done using this control, you should free it by calling the
ldap_control_free()
function.
|
Returns
One of the following values:
LDAP_SUCCESS
if successful.-
LDAP_PARAM_ERROR
if an invalid parameter was passed to the function. LDAP_NO_MEMORY
if memory cannot be allocated.-
LDAP_ENCODING_ERROR
if an error occurred when BER-encoding the control
Description
The ldap_create_virtuallist_control()
function
allows you to retrieve a subset of entries from the server for use
in a virtual list box. Calling this function creates an LDAP control
that you can pass to the
ldap_search_ext()
and
ldap_search_ext_s()
functions.
Note that you also need to pass a server-side sorting control to
the search functions. You can call the
ldap_create_sort_keylist()
and ldap_create_sort_control()
functions to create a server-side sorting control.
In order for the virtual list view 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 ldap.h
).
Netscape Directory Server 4.0 and later supports this control. For information on determining if a server supports this or other LDAPv3 controls, see "Determining If the Server Supports LDAPv3".
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.
When you are done with the search, you should free the control by
calling the
ldap_control_free()
function.
For more information about this control, see "Using the Virtual List View Control."
See Also:
LDAPVirtualList,
ldap_parse_virtuallist_control(),
ldap_search_ext(),
ldap_search_ext_s(),
ldap_control_free().
ldap_delete()
Deletes an entry from the directory asynchronously.
Note that this is an older function that is included in the LDAP
API for backward-compatibility. If you are writing a new LDAP client,
use ldap_delete_ext()
instead.
Syntax
#include <ldap.h> int ldap_delete( LDAP *ld, const char *dn );
Parameters
This function has the following parameters:
Table 18-39 - ldap_delete() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
dn |
Distinguished name (DN) of the entry to remove. |
Returns
Returns the message ID of the ldap_delete()
operation. To check the result of this operation, call
ldap_result()
and
ldap_result2error()
.
For a list of the possible result codes for an LDAP delete
operation, see the result code documentation for the
ldap_delete_ext_s()
function.
Description
The ldap_delete()
function removes an entry from the
directory.
A newer version of this function,
ldap_delete_ext()
, is
available in this release of the LDAP API. ldap_delete()
(the older version of the function) is included only for
backward-compatibility. If you are writing a new LDAP client, use
ldap_delete_ext()
instead of ldap_delete()
.
If you want more information on ldap_delete()
,
refer to the LDAP C SDK 1.0 Programmer's Guide.
Example
The following section of code uses the asynchronous
ldap_delete()
function to remove the entry for
"Barbara Jensen
" from the directory.
Code Example 18-11 - ldap_delete() code example
#include <ldap.h> ... LDAP *ld; LDAPMessage *result; int msgid, rc; struct timeval tv; /* Distinguished name of the entry that you want to delete. */ char *dn = "uid=bjensen, ou=People, dc=example,dc=com"; ... /* Set up the timeout period to wait for the "modify" operation */ tv.tv_sec = tv.tv_usec = 0; /* Delete the entry */ if ( ( msgid = ldap_delete( ld, dn ) ) == -1 ) { ldap_perror( ld, "ldap_delete" ); return( 1 ); } /* Check to see if the operation has completed */ while ( ( rc = ldap_result( ld, msgid, 0, &tv, &result ) ) == 0 ) { ... /* do other work while waiting for the operation to complete */ ... } /* Check the result to see if any errors occurred */ ldap_result2error( ld, result, 1 ); ldap_perror( ld, "ldap_delete" ); ...
See Also:
ldap_delete_ext().
ldap_delete_ext()
Deletes an entry from the directory asynchronously.
Syntax
#include <ldap.h> int ldap_delete_ext( LDAP *ld, const char *dn, LDAPControl **serverctrls, LDAPControl **clientctrls, int *msgidp );
Parameters
This function has the following parameters:
Table 18-40 - ldap_delete_ext() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
dn |
Distinguished name (DN) of the entry to remove. |
serverctrls |
Pointer to an array of
LDAPControl
structures representing LDAP server controls that apply to this
LDAP operation. If you do not want to pass any server controls,
specify NULL for this argument.
|
clientctrls |
Pointer to an array of
LDAPControl
structures representing LDAP client controls that apply to this
LDAP operation. If you do not want to pass any client controls,
specify NULL for this argument.
|
msgidp |
Pointer to an integer that will be set to the message ID of the
LDAP operation. To check the result of this operation, call the
ldap_result() and
ldap_parse_result()
functions.
|
Returns
One of the following values:
LDAP_SUCCESS
if successful.LDAP_PARAM_ERROR
if any of the arguments are invalid.-
LDAP_ENCODING_ERROR
if an error occurred when BER-encoding the request. -
LDAP_SERVER_DOWN
if the LDAP server did not receive the request or if the connection to the server was lost. LDAP_NO_MEMORY
if memory cannot be allocated.-
LDAP_NOT_SUPPORTED
if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAPv3 protocol. Make sure that you set the version of your LDAP client to version 3 before calling this function. (For details, see "Specifying the LDAP Version of Your Client.")
Description
The ldap_delete_ext()
function deletes an entry from
the directory asynchronously. Use the dn
argument to
specify the entry that you want to delete.
This function is a new version of the
ldap_delete()
function. If you are writing a new LDAP client, you should call
this function instead of
ldap_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()
instead. (For more information on asynchronous and synchronous
functions, see "Calling Synchronous and
Asynchronous Functions.")
In order to get the results of the LDAP delete operation, you
need to call the
ldap_result()
function
and the
ldap_parse_result()
function. (See "Calling Asynchronous
Functions" for details.) For a list of possible result codes for
an LDAP delete operation, see the result code documentation for the
ldap_delete_ext_s()
function.
For additional information on deleting entries from the directory, see "Deleting an Entry."
Example
See the example under "Example: Deleting an Entry from the Directory (Asynchronous)."
See Also:
ldap_delete_ext_s(),
ldap_result(),
ldap_parse_result().
ldap_delete_ext_s()
Deletes an entry from the directory synchronously.
Syntax
#include <ldap.h> int ldap_delete_ext_s( LDAP *ld, const char *dn, LDAPControl **serverctrls, LDAPControl **clientctrls );
Parameters
This function has the following parameters:
Table 18-41 - ldap_delete_ext_s() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
dn |
Distinguished name (DN) of the entry to remove. |
serverctrls |
Pointer to an array of
LDAPControl
structures representing LDAP server controls that apply to this
LDAP operation. If you do not want to pass any server controls,
specify NULL for this argument.
|
clientctrls |
Pointer to an array of
LDAPControl
structures representing LDAP client controls that apply to this
LDAP operation. If you do not want to pass any client controls,
specify NULL for this argument.
|
Returns
One of the following values:
LDAP_SUCCESS
if successful.LDAP_PARAM_ERROR
if any of the arguments are invalid.-
LDAP_ENCODING_ERROR
if an error occurred when BER-encoding the request. -
LDAP_SERVER_DOWN
if the LDAP server did not receive the request or if the connection to the server was lost. LDAP_NO_MEMORY
if memory cannot be allocated.-
LDAP_LOCAL_ERROR
if an error occurred when receiving the results from the server. -
LDAP_DECODING_ERROR
if an error occurred when decoding the BER-encoded results from the server. -
LDAP_NOT_SUPPORTED
if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAPv3 protocol. Make sure that you set the version of your LDAP client to version 3 before calling this function. (For details, see "Specifying the LDAP Version of Your Client.")
The following result codes can be returned by the Directory Server when processing an LDAP delete request. Other LDAP servers may send these result codes under different circumstances or may send different result codes back to your LDAP client.
-
LDAP_OPERATIONS_ERROR
may be sent by the Directory Server for general errors encountered by the server when processing the request. -
LDAP_PROTOCOL_ERROR
if the delete request did not comply with the LDAP protocol. The Directory Server may set this error code in the results for a variety of reasons. Some of these reasons include:- The server encountered an error when decoding your client's BER-encoded request.
-
LDAP_UNWILLING_TO_PERFORM
may be sent by the Directory Server in the following situations:- The entry to be deleted is a DSE (DSA-specific entry, where DSA is the Directory Server Agent).
- The server's database is read-only.
-
LDAP_NO_SUCH_OBJECT
may be sent by the Directory Server if the entry that you want deleted does not exist and if no referral URLs are available. -
LDAP_REFERRAL
may be sent by the Directory Server if the DN specified by thedn
argument identifies an entry not handled by the current server and if referral URLs identify a different server to handle the entry. (For example, if the DN isuid=bjensen, ou=European Sales, dc=example,dc=com
, all entries underou=European Sales
might be handled by a different Directory Server.) -
LDAP_NOT_ALLOWED_ON_NONLEAF
may be sent by the Directory Server if the entry that you want deleted has entries beneath it in the directory tree (in other words, if this entry is a parent entry to other entries). -
LDAP_INSUFFICIENT_ACCESS
may be sent by the Directory Server if the DN that your client is authenticated as does not have the access rights to write to the entry.
Note that the Directory Server may send other result codes in addition to the codes described here (for example, the server may have loaded a custom plug-in that returns other result codes).
Description
The ldap_delete_ext_s()
function deletes an entry
from the directory synchronously. Use the dn
argument
to specify the entry that you want to delete.
This function is a new version of the
ldap_delete_s()
function. If you are writing a new LDAP client, you should call this
function instead of
ldap_delete_s()
.
ldap_delete_ext_s()
is a synchronous function, which
directly returns the results of the operation. If you want to
perform other operations while waiting for the results of this
operation, call the asynchronous function
ldap_delete_ext()
instead. (For more information on asynchronous and synchronous
functions, see "Calling Synchronous and
Asynchronous Functions.")
For additional information on deleting entries from the directory, see "Deleting an Entry."
Example
See the example under "Example: Deleting an Entry from the Directory (Synchronous)."
See Also:
ldap_delete_ext()
.
ldap_delete_s()
Deletes an entry from the directory synchronously.
Note that this is an older function that is included in the LDAP
API for backward-compatibility. If you are writing a new LDAP
client, use
ldap_delete_ext_s()
instead.
Syntax
#include <ldap.h> int ldap_delete_s(LDAP *ld, const char *dn);
Parameters
This function has the following parameters:
Table 18-42 - ldap_delete_s() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
dn |
Distinguished name (DN) of the entry to remove. |
Returns
For a list of possible result codes for an LDAP delete operation,
see the result code documentation for the
ldap_delete_ext_s()
function.
Description
The ldap_delete_s()
function removes an entry from
the directory.
A newer version of this function,
ldap_delete_ext_s()
,
is available in this release of the LDAP API.
ldap_delete_s()
(the older version of the function) is
included only for backward-compatibility. If you are writing a new
LDAP client, use
ldap_delete_ext_s()
instead of ldap_delete_s()
.
If you want more information on ldap_delete_s()
,
refer to the LDAP C SDK 1.0 Programmer's Guide.
Example
The following section of code uses the synchronous
ldap_delete_s()
function to delete the entry for
Barbara Jensen from the directory.
Code Example 18-12 - ldap_delete_s() code example
LDAP *ld; /* Distinguished name of the entry that you want to delete. */ char *dn = "uid=bjensen, ou=People, dc=example,dc=com"; ... /* Delete the entry */ if ( ldap_delete_s( ld, dn ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldap_delete_s" ); return( 1 ); } ...
See Also:
ldap_delete_ext_s().
ldap_dn2ufn()
The ldap_dn2ufn()
function converts a distinguished
name (DN) into a "friendlier" form by stripping off the cryptic
type names.
Syntax
#include <ldap.h> char * ldap_dn2ufn( const char *dn );
Parameters
This function has the following parameters:
Table 18-43 - ldap_dn2ufn() function parameters
dn |
Distinguished name (DN) that you want converted to a friendlier form. |
Returns
One of the following values:
- If successful, returns the DN in its friendlier form.
- If unsuccessful, returns
NULL
.
ldap_err2string()
The ldap_err2string()
function returns the
corresponding error message for an error code. For more information,
see "Getting the Error Message."
Syntax
#include <ldap.h> char * ldap_err2string( int err );
Parameters
This function has the following parameters:
Table 18-44 - ldap_err2string() function parameters
err |
Error code that you want interpreted into an error message. |
Returns
One of the following values:
- If successful, returns the corresponding error message for the error code.
-
If unsuccessful (for example, if the error code is not a valid
LDAP API error code), returns "
Unknown error
".
Example
The following section of code sets the variable
err_msg
to the error message corresponding to the error
code returned by the ldap_simple_bind_s()
function.
Code Example 18-13 - ldap_err2string() code example
... LDAP *ld; char *dn = "uid=bjensen, ou=People, dc=example,dc=com"; char *pw = "hifalutin"; char *err_msg; ... err_msg = ldap_err2string( ldap_simple_bind_s( ld, dn, pw ) ); ...
See Also:
ldap_get_lderrno(),
ldap_perror(),
ldap_result2error(),
ldap_set_lderrno(),
ldapssl_err2string().
ldap_explode_dn()
The ldap_explode_dn()
function converts a
distinguished name (DN) into its component parts. For more
information, see "Getting the Components
of a Distinguished Name."
Syntax
#include <ldap.h> char ** ldap_explode_dn( const char *dn, int notypes );
Parameters
This function has the following parameters:
Table 18-45 - ldap_explode_dn() function parameters
dn |
Distinguished name (DN) that you want separated into components. |
notypes |
Specifies whether or not type names in the distinguished name are
returned. This parameter can have the following possible values:
|
Returns
One of the following values:
- If successful, returns a NULL-terminated array containing the components of the distinguished name (DN).
- If unsuccessful, returns a
NULL
.
Example
The following function call:
ldap_explode_dn( "uid=bjensen, ou=People, dc=example,dc=com", 0 )
returns this array:
{ "uid=bjensen", "ou=People", "dc=example", "dc=com", NULL }
If you change the notypes
parameter from
0
to 1
:
ldap_explode_dn( "uid=bjensen, ou=People, dc=example,dc=com", 1 )
the component names are not returned in the array:
{ "bjensen", "People", "dc=example, "dc=com", NULL }
See Also:
ldap_explode_rdn(),
ldap_get_dn().
ldap_explode_rdn()
The ldap_explode_rdn()
function converts a relative
distinguished name (RDN) into its component parts. For more
information, see "Getting the Components
of a Distinguished Name."
Syntax
#include <ldap.h> char ** ldap_explode_rdn( const char *dn, int notypes );
Parameters
This function has the following parameters:
Table 18-46 - ldap_explode_rdn() function parameters
dn |
Relative distinguished name (RDN) that you want separated into components. |
notypes |
Specifies whether or not type names in the relative distinguished
name are returned. This parameter can have the following possible
values:
|
Returns
One of the following values:
-
If successful, returns a
NULL
-terminated array containing the components of the relative distinguished name (RDN). - If unsuccessful, returns a
NULL
.
Example
The following function call:
ldap_explode_rdn( "ou=Sales + cn=Barbara Jensen", 0 );
returns this array:
{ "ou=Sales", "cn=Barbara Jensen", NULL }
See Also:
ldap_explode_dn(),
ldap_get_dn().
ldap_extended_operation()
Sends a request to the server to perform an extended operation asynchronously.
Syntax
#include <ldap.h> int ldap_extended_operation( LDAP *ld, const char *requestoid, struct berval *requestdata, LDAPControl **serverctrls, LDAPControl **clientctrls, int *msgidp );
Parameters
This function has the following parameters:
Table 18-47 - ldap_extended_operation() function parameters
ld |
Connection handle, which is a 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.
|
serverctrls |
Pointer to an array of
LDAPControl
structures representing LDAP server controls that apply to this
LDAP operation. If you do not want to pass any server controls,
specify NULL for this argument.
|
clientctrls |
Pointer to an array of
LDAPControl
structures representing LDAP client controls that apply to this
LDAP operation. If you do not want to pass any client controls,
specify NULL for this argument.
|
msgidp |
Pointer to an integer that will be set to the message ID of the
LDAP operation. To check the result of this operation, call the
ldap_result() and
ldap_parse_result()
functions.
|
Returns
One of the following values:
LDAP_SUCCESS
if successful.LDAP_PARAM_ERROR
if any of the arguments are invalid.-
LDAP_ENCODING_ERROR
if an error occurred when BER-encoding the request. -
LDAP_SERVER_DOWN
if the LDAP server did not receive the request or if the connection to the server was lost. LDAP_NO_MEMORY
if memory cannot be allocated.-
LDAP_NOT_SUPPORTED
if your LDAP client does not specify that it is using the LDAPv3 protocol. Make sure that you set the version of your LDAP client to version 3 before calling this function. (For details, see "Specifying the LDAP Version of Your Client.")
Description
The ldap_extended_operation()
function sends a
request to the server to perform an LDAPv3 extended operation
synchronously.
The LDAP server must support the extended operation. The Netscape Directory Server supports a server plug-in interface that you can use to add support for extended operations to the server. For details, see the Netscape Directory Server Programmer's Guide.
For information on determining the extended operations supported by a server, see "Determining the Extended Operations Supported."
After processing an LDAPv3 extended operation, an LDAP server can
return an object identifier and data in the result. To parse the OID
and data from the result, call the
ldap_parse_extended_result()
function.
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()
instead. (For more information on asynchronous and synchronous
functions, see "Calling Synchronous and
Asynchronous Functions.")
In order to get the results of the LDAP extended operation, you
need to call the
ldap_result()
function, the
ldap_parse_extended_result()
function, and the
ldap_get_lderrno()
function. (See "Performing
an Asynchronous Extended Operation" for details.) For a list of
possible result codes for an LDAP extended operation, see the result
code documentation for the
ldap_extended_operation_s()
function.
See Also:
ldap_extended_operation_s(),
ldap_result(),
ldap_parse_extended_result(),
ldap_get_lderrno().
ldap_extended_operation_s()
Sends a request to the server to perform an extended operation synchronously.
Syntax
#include <ldap.h> int ldap_extended_operation_s( LDAP *ld, const char *requestoid, struct berval *requestdata, LDAPControl **serverctrls, LDAPControl **clientctrls, char **retoidp, struct berval **retdatap );
Parameters
This function has the following parameters:
Table 18-48 - ldap_extended_operation_s() function parameters
ld |
Connection handle, which is a 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.
|
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.
|
retoidp |
Pointer to the object identifier (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.
|
Returns
One of the following values:
LDAP_SUCCESS
if successful.LDAP_PARAM_ERROR
if any of the arguments are invalid.-
LDAP_ENCODING_ERROR
if an error occurred when BER-encoding the request. -
LDAP_SERVER_DOWN
if the LDAP server did not receive the request or if the connection to the server was lost. LDAP_NO_MEMORY
if memory cannot be allocated.-
LDAP_LOCAL_ERROR
if an error occurred when receiving the results from the server. -
LDAP_DECODING_ERROR
if an error occurred when decoding the BER-encoded results from the server. -
LDAP_NOT_SUPPORTED
if your LDAP client does not specify that it is using the LDAPv3 protocol. Make sure that you set the version of your LDAP client to version 3 before calling this function. (For details, see "Specifying the LDAP Version of Your Client.")
The following result codes can be returned by the Netscape Directory Server when processing an LDAP extended operation request. Other LDAP servers may send these result codes under different circumstances or may send different result codes back to your LDAP client.
-
LDAP_OPERATIONS_ERROR
may be sent by the Netscape Directory Server for general errors encountered by the server when processing the request. -
LDAP_PROTOCOL_ERROR
if the extended operation request did not comply with the LDAP protocol. The Netscape Directory Server may set this error code in the results for a variety of reasons. Some of these reasons include:- The server encountered an error when decoding your client's BER-encoded request.
-
The extended operation specified by the
requestoid
argument is not supported by the server.
Depending on the extended operation requested, the Netscape Directory Server may send other result codes in addition to the codes described here. In the Netscape Directory Server, the people deploying the server are responsible for implementing the mechanisms for handling extended operations. Check with your server administrator for additional result codes returned to the client.
Description
The ldap_extended_operation_s()
function sends a
request to the server to perform an LDAPv3 extended operation
synchronously.
The LDAP server must support the extended operation. The Netscape Directory Server supports a server plug-in interface that you can use to add support for extended operations to the server. For details, see the Netscape Directory Server Programmer's Guide.
For information on determining the extended operations supported by a server, see "Determining the Extended Operations Supported."
After processing an LDAPv3 extended operation, an LDAP server can
return an object identifier and data in the results. The
retoidp
and retdatap
arguments point to
these values.
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()
instead. (For more information on asynchronous and synchronous
functions, see "Calling Synchronous and
Asynchronous Functions.")
See Also:
ldap_extended_operation().
ldap_first_attribute()
The ldap_first_attribute()
function returns the name
of the first attribute in a entry returned by the
ldap_first_entry()
function, the
ldap_next_entry()
function, or the
ldap_result()
function.
For more information, see "Getting Attributes from an Entry."
Syntax
#include <ldap.h> char * ldap_first_attribute( LDAP *ld, LDAPMessage *entry, BerElement **ber );
Parameters
This function has the following parameters:
Table 18-49 - ldap_first_attribute() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
entry |
Pointer to the LDAPMessage
structure representing the entry returned by the
ldap_first_entry()
or ldap_next_entry()
function.
|
ber |
A pointer to a
BerElement
allocated to keep track of its current position. Pass this
pointer to subsequent calls to
ldap_next_attribute()
to step through the entry's attributes.
|
Returns
One of the following values:
-
If successful, returns the 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 theLDAP
structure. To get the error code, call theldap_get_lderrno()
function. (See Chapter 19 "Result Codes for a complete listing of error codes.)
Example
The following section of code retrieves each attribute for an entry.
Code Example 18-14 - ldap_first_attribute() code example
#include <ldap.h> ... LDAP *ld; LDAPMessage *result, *e; BerElement *ber; char *a; char *my_searchbase = "dc=example,dc=com"; char *my_filter = "(sn=Jensen)" ... /* Search the directory */ if ( ldap_search_s( ld, my_searchbase, LDAP_SCOPE_SUBTREE, \ my_filter, NULL, 0, &result ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldap_search_s" ); return( 1 ); } /* Get the first matching entry.*/ e = ldap_first_entry( ld, result ); /* Retrieve the attributes the entry */ for ( a = ldap_first_attribute( ld, e, &ber ); a != NULL; a = ldap_next_attribute( ld, e, ber ) ) { ... /* Code to get and manipulate attribute values */ ... } ldap_memfree( a ); } /* Free the BerElement from memory when done */ if ( ber != NULL ) { ldap_ber_free( ber, 0 ); } ...
See Also:
ldap_first_entry(),
ldap_next_entry(),
ldap_next_attribute().
ldap_first_entry()
Returns a pointer to the
LDAPMessage
structure
representing the first directory entry in a chain of search results.
Syntax
#include <ldap.h> LDAPMessage * ldap_first_entry( LDAP *ld, LDAPMessage *result );
Parameters
This function has the following parameters:
Table 18-50 - ldap_first_entry() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
result |
Chain of search results, which are represented by a pointer to
the LDAPMessage
structure.
|
Returns
One of the following values:
-
If successful, returns the pointer to the first
LDAPMessage
structure of the typeLDAP_RES_SEARCH_ENTRY
in the chain of search results. -
If no
LDAPMessage
structures of the typeLDAP_RES_SEARCH_ENTRY
are in the chain of the search results or if the function is unsuccessful, returns aNULLMSG
.
Description
The ldap_first_entry()
function returns a pointer to
the LDAPMessage
structure representing the first directory entry in a chain of
search results. Search result entries are in messages of the type
LDAP_RES_SEARCH_ENTRY
.
You can use this function in conjunction with the
ldap_next_entry()
function to iterate through the directory entries in a chain of
search results. These functions skip over any messages in the chain
that do not have the type LDAP_RES_SEARCH_ENTRY
.
Do not free the
LDAPMessage
structure
returned by this function. Because this is a structure within a
chain of search results, freeing this structure will free part of
the chain of search results. When you are done working with the
search results, you can free the chain itself, rather than
individual structures within the chain.
For more information, see "Iterating Through a Chain of Results."
See Also:
ldap_result(),
ldap_search_ext(),
ldap_search_ext_s(),
ldap_next_entry().
ldap_first_message()
Returns a pointer to the first
LDAPMessage
structure
in a chain of search results.
Syntax
#include <ldap.h> LDAPMessage * ldap_first_message( LDAP *ld, LDAPMessage *res );
Parameters
This function has the following parameters:
Table 18-51 - ldap_first_message() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
res |
Chain of search results, represented by a pointer to the
LDAPMessage structure.
|
Returns
One of the following values:
-
If successful, returns the pointer to the first
LDAPMessage
structure in the chain of search results. -
If no
LDAPMessage
structures are in the chain or if the function is unsuccessful, returns aNULLMSG
.
Description
The ldap_first_message()
function returns a pointer
to the first
LDAPMessage
structure
in a chain of search results.
You can use this function in conjunction with the
ldap_next_message()
function to iterate through the chain of search results. You can
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 the first structure
within a chain of search results, freeing this structure will free
the chain of search results. When you are done working with the
search results, you can free the chain itself, rather than
individual structures within the chain.
For more information, see "Iterating Through a Chain of Results."
Example
See the examples under "Example: Searching the Directory (Asynchronous)" and "Example: Searching the Directory (Synchronous)."
See Also:
ldap_result(),
ldap_search_ext(),
ldap_search_ext_s(),
ldap_next_message().
ldap_first_reference()
Returns a pointer to the
LDAPMessage
structure
representing the first search reference in a chain of search results.
Syntax
#include <ldap.h> LDAPMessage * ldap_first_reference(LDAP *ld, LDAPMessage *res );
Parameters
This function has the following parameters:
Table 18-52 - ldap_first_reference() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
res |
Chain of search results, which are represented by a pointer to
the LDAPMessage
structure.
|
Returns
One of the following values:
-
If successful, returns the pointer to the first
LDAPMessage
structure of the typeLDAP_RES_SEARCH_REFERENCE
in the chain of search results. -
If no
LDAPMessage
structures of the typeLDAP_RES_SEARCH_REFERENCE
are in the chain of the search results or if the function is unsuccessful, returns aNULLMSG
.
Description
The ldap_first_reference()
function returns a
pointer to the
LDAPMessage
structure
representing the first search reference in a chain of search
results. Search references are in messages of the type
LDAP_RES_SEARCH_REFERENCE
.
You can use this function in conjunction with the
ldap_next_reference()
function to iterate through the search references in a chain of
search results. These functions skip over any messages in the chain
that do not have the type LDAP_RES_SEARCH_REFERENCE
.
Do not free the
LDAPMessage
structure
returned by this function. Because this is a structure within a
chain of search results, freeing this structure will free part of
the chain of search results. When you are done working with the
search results, you can free the chain itself, rather than
individual structures within the chain.
For more information, see "Iterating Through a Chain of Results."
See Also:
ldap_result(),
ldap_search_ext(),
ldap_search_ext_s(),
ldap_next_reference().
ldap_free_friendlymap()
The ldap_free_friendlymap()
function frees the
structures allocated by the
ldap_friendly_name()
function.
Syntax
#include <ldap.h> void ldap_free_friendlymap( FriendlyMap *map );
Parameters
This function has the following parameters:
Table 18-53 - ldap_free_friendlymap() function parameters
map |
Pointer to the mapping structure in memory. |
Example
The following section of code frees memory allocated by the
ldap_friendly_name()
function.
Code Example 18-15 - ldap_free_friendlymap() code example
... FriendlyMap *map; ... ldap_free_friendlymap( map ); ...
See Also:
ldap_friendly_name().
ldap_free_sort_keylist()
Frees the structures allocated by the
ldap_create_sort_keylist()
function.
Syntax
#include <ldap.h> void ldap_free_sort_keylist (LDAPsortkey **sortKeyList);
Parameters
This function has the following parameters:
Table 18-54 - ldap_free_sort_keylist() function parameters
sortKeyList |
Array of LDAPsortkey
structures that you want to free from memory.
|
Description
The ldap_free_sort_keylist()
function frees the
array of LDAPsortkey
structures allocated by the
ldap_create_sort_keylist()
function.
When you are done sorting results, you can call this function to free the memory that you have allocated.
See Also:
ldap_create_sort_keylist().
ldap_free_urldesc()
The ldap_free_urldesc()
function frees memory
allocated by the
ldap_url_parse()
function. For more information, see
"Freeing the Components of an LDAP URL."
Syntax
#include <ldap.h> void ldap_free_urldesc( LDAPURLDesc *ludp );
Parameters
This function has the following parameters:
Table 18-55 - ldap_free_urldesc() function parameters
ludp |
Pointer to a LDAPURLDesc structure. |
Example
The following section of code parses an LDAP URL and then frees
the LDAPURLDesc
structure from memory after verifying that the LDAP URL is valid.
Code Example 18-16 - ldap_free_urldesc() code example
>#include <stdio.h> #include <ldap.h> ... char *my_url = "ldap://ldap.example.com:5000/dc=example,dc=com?cn,mail,telephoneNumber?sub? \ (sn=Jensen)"; LDAPURLDesc *ludpp; int res, i; ... if ( ( res = ldap_url_parse( my_url, &ludpp ) ) != 0 ) { switch( res ){ case LDAP_URL_ERR_NOTLDAP: printf( "URL does not begin with \"ldap://\"\n" ); break; case LDAP_URL_ERR_NODN: printf( "URL does not contain a distinguished name\n" ); break; case LDAP_URL_ERR_BADSCOPE: printf( "URL contains an invalid scope\n" ); break; case LDAP_URL_ERR_MEM: printf( "Not enough memory\n" ); break; default: printf( "Unknown error\n" ); } return( 1 ); } printf( "URL is a valid LDAP URL\n" ); ldap_free_urldesc( ludpp ); ...
See Also:
ldap_url_parse().
ldap_friendly_name()
The ldap_friendly_name()
function maps a set of
"unfriendly names" (for example, a two-letter country code such as
"IS
") to "friendly names" (for example, the full names
of countries, such as "Iceland
").
This function relies on the existence of a file mapping "unfriendly names" to "friendly names". The names in the file are tab-delimited, as shown in the example file below:
unfriendly_name> <friendly_name> AD Andorra AE United Arab Emirates AF Afghanistan AG Antigua and Barbuda AI Anguilla
Syntax
#include <ldap.h> char * ldap_friendly_name( char *filename, char *uname, FriendlyMap *map );
Parameters
This function has the following parameters:
Table 18-56 - ldap_friendly_name() function parameters
filename |
Name of the map file listing the "unfriendly names" and "friendly names." |
uname |
"Unfriendly name" for which you want to find the "friendly name." |
map |
Pointer to the mapping in memory. Initialize this pointer to
NULL on the first call, then use the pointer during
subsequent calls so that the mapping file does not need to be
read again.
|
Returns
One of the following values:
- If successful, returns the "friendly name" for the specified "unfriendly name".
-
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 name (the name you passed as theuname
parameter).
Example
The following section of code reads in a map of friendly names and prints the name corresponding to the unfriendly name "IS".
Code Example 18-17 - ldap_friendly_name() code example
#include <stdio.h> ... FriendlyMap map = NULL; char *map_file = "/home/bjensen/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 the file is in memory now, no need to reference it in subsequent calls */ friendly_name = ldap_friendly_name( NULL, "VI", &map ); printf( "Friendly Name for VI: %s\n", friendly_name ); ...
See Also:
ldap_free_friendlymap().
ldap_get_dn()
The ldap_get_dn()
routine returns the distinguished
name (DN) for an entry in a chain of search results. You can get an
entry from a chain of search results by calling the
ldap_first_entry()
and
ldap_next_entry()
functions. For more information, see
"Getting
Distinguished Names for Each Entry."
Syntax
#include <ldap.h> char * ldap_get_dn( LDAP *ld, LDAPMessage *entry );
Parameters
This function has the following parameters:
Table 18-57 - ldap_get_dn() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
entry |
Pointer to an entry in a chain of search results, as returned by
the ldap_first_entry()
and ldap_next_entry()
functions.
|
Returns
One of the following values:
- If successful, returns the distinguished name (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 theldap_get_lderrno()
function. (See Chapter 19 - Result Codes for a complete listing of error codes.)
Example
The following section of code prints the distinguished name for each entry found in a search.
Code Example 18-18 - ldap_get_dn() code example
#include <stdio.h> #include <ldap.h> ... LDAP *ld; LDAPMessage *result, *e; char *dn; char *my_searchbase = "dc=example,dc=com"; char *my_filter = "(sn=Jensen)"; ... /* Search the directory */ if ( ldap_search_s( ld, my_searchbase, LDAP_SCOPE_SUBTREE, my_filter, NULL, 0, &result ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldap_search_s" ); return( 1 ); } /* For each matching entry found, print out the name of the entry.*/ for ( e = ldap_first_entry( ld, result ); e != NULL; e = ldap_next_entry( ld, e ) ) { if ( ( dn = ldap_get_dn( ld, e ) ) != NULL ) { printf( "dn: %s\n", dn ); /* Free the memory used for the DN when done */ ldap_memfree( dn ); } } /* Free the result from memory when done. */ ldap_msgfree( result ); ...
See Also:
ldap_first_entry(),
ldap_next_entry().
ldap_get_entry_controls()
Gets the LDAP controls included with a directory entry in a set of search results.
Syntax
#include <ldap.h> int ldap_get_entry_controls( LDAP *ld, LDAPMessage *entry, LDAPControl ***serverctrlsp );
Parameters
This function has the following parameters:
Table 18-58 - ldap_get_entry_controls() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
entry |
Pointer to an
LDAPMessage
structure representing an entry in a chain of search results.
|
serverctrlsp |
Pointer to an array of
LDAPControl
structures, which represent the LDAPv3 server controls returned
by the server.
|
Returns
One of the following values:
-
LDAP_SUCCESS
if the LDAP controls were successfully retrieved. -
LDAP_DECODING_ERROR
if an error occurred when decoding the BER-encoded message. -
LDAP_PARAM_ERROR
if an invalid parameter was passed to the function. LDAP_NO_MEMORY
if memory cannot be allocated.
Description
The ldap_get_entry_controls()
function retrieves the
LDAPv3 controls included in a directory entry in a chain of search
results.
The LDAP controls are specified in an array of
LDAPControl
structures.
(Each LDAPControl
structure represents an LDAP control.)
At this point in time, the entry notification controls (which are
used with persistent search controls) are the only controls that are
returned with individual entries. Other controls are returned with
results sent from the server. You can call
ldap_parse_result()
to
retrieve those controls.
ldap_getfilter_free()
The ldap_getfilter_free()
function frees the memory
used by a filter set. Once you call this routine, the
LDAPFiltDesc
structure
is no longer valid and cannot be used again. For more information,
see "Freeing Filters from Memory."
Syntax
#include <ldap.h> void ldap_getfilter_free( LDAPFiltDesc *lfdp );
Parameters
This function has the following parameters:
Table 18-59 - ldap_getfilter_free() function parameters
lfdp |
Pointer to a
LDAPFiltDesc
structure.
|
Example
The following section of code frees the
LDAPFiltDesc
structure
from memory after all searches are completed.
Code Example 18-19 - ldap_getfilter_free code example
>#include <ldap.h> ... LDAPFiltDesc *lfdp; char *filter_file = "myfilters.conf"; ... /* Read the filter configuration file into an LDAPFiltDesc structure */ lfdp = ldap_init_getfilter( filter_file ); ... /* Retrieve filters and perform searches */ ... /* Free the configuration file (the LDAPFiltDesc structure) */ ldap_getfilter_free( lfdp ); ...
See Also:
ldap_init_getfilter(),
ldap_init_getfilter_buf().
ldap_getfirstfilter()
The ldap_getfirstfilter()
function retrieves the
first filter that is appropriate for a given value. For more
information, see "Retrieving Filters."
Syntax
#include <ldap.h> LDAPFiltInfo * ldap_getfirstfilter( LDAPFiltDesc *lfdp, char *tagpat, char *value );
Parameters
This function has the following parameters:
Table 18-60 - ldap_getfirstfilter() function parameters
lfdp |
Pointer to an
LDAPFiltDesc structure.
|
tagpat |
Regular expression for a tag in the filter configuration. |
value |
Value for which to find the first appropriate filter. |
Returns
One of the following values:
-
If successful, returns a pointer to an
LDAPFiltInfo
structure. - If no more filters can be returned, returns a
NULL
. - If unsuccessful, returns a
NULL
.
Example
The following section of code is based on the getfilt
command-line program example provided with the LDAP C SDK. The
program prompts the user to enter search criteria. Based on the
criteria entered, the program retrieves filters that match the search
criteria. The example uses the filter configuration file shown in
"Understanding the Configuration File
Syntax."
Code Example 18-20 - ldap_getfirstfilter() code example
#include <stdio.h> #include <ldap.h> ... LDAP *ld; LDAPMessage *result, *e; BerElement *ber; char *a, *dn; char **vals; int i; LDAPFiltDesc *ldfp; LDAPFiltInfo *ldfi; char buf[ 80 ]; /* Contains the search criteria */ int found; ... /* Load the filter configuration file into an LDAPFiltDesc structure */ if ( ( ldfp = ldap_init_getfilter( "myfilters.conf" ) ) == NULL ) { perror( "Cannot open filter configuration file" ); return( 1 ); } /* Read a string to search for */ printf( "Enter a string to search for: " ); gets( buf ); if ( strlen( buf ) == 0 ) { fprintf( stderr, "usage: %s search-string\n", argv[ 0 ]); return( 1 ); } /* Select a filter to use when searching for the value in buf */ found = 0; for ( ldfi = ldap_getfirstfilter( ldfp, "people", buf ); ldfi != NULL; ldfi = ldap_getnextfilter( ldfp ) ) { /* Use the selected filter to search the directory */ if ( ldap_search_s( ld, "dc=example,dc=com, ldfi->lfi_scope, ldfi->lfi_filter, NULL, 0, &result ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldap_search_s" ); return( 1 ); } else { /* Once a filter gets results back, stop iterating through the different filters */ if ( ( found = ldap_count_entries( ld, result ) > 0 ) ) { break; } else { ldap_msgfree( result ); } } } if ( found == 0 ) { printf( "No matching entries found.\n" ); } else { printf( "Found %d %s match%s for \"%s\"\n\n", found, ldfi->lfi_desc, found == 1 ? "" : "es", buf ); } ldap_msgfree( result ); ldap_getfilter_free( ldfp ); ...
See Also:
ldap_init_getfilter(),
ldap_init_getfilter_buf(),
ldap_getnextfilter().
ldap_get_lang_values()
The ldap_get_lang_values()
function returns a
NULL
-terminated array of an attribute's string values
that match a specified language subtype.
If you want to retrieve binary data from an attribute, call the
ldap_get_lang_values_len()
function instead.
Syntax
#include <ldap.h> char ** ldap_get_lang_values( LDAP *ld, LDAPMessage *entry, const char *target, char **type );
Parameters
This function has the following parameters:
Table 18-61 - ldap_get_lang_values() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
entry |
Entry retrieved from the directory. |
target |
Attribute type (including an optional language subtype) that you want to retrieve the values of. |
type |
Pointer to a buffer that returns the attribute type retrieved by this function. |
Returns
One of the following values:
-
If successful, returns a
NULL
-terminated array of the attribute's values. -
If unsuccessful or if no such attribute exists in the entry,
returns a NULL and sets the appropriate error code in the
LDAP structure. To get the error
code, call the
ldap_get_lderrno()
function. (See Chapter 19 "Result Codes" for a complete listing of error codes.)
Description
Unlike the
ldap_get_values()
function, if a language subtype is specified, this function first
attempts to find and return values that match that subtype (for
example, cn;lang-en
).
See Also:
ldap_first_entry(),
ldap_next_entry(),
ldap_first_attribute(),
ldap_next_attribute(),
ldap_get_lang_values_len(),
ldap_get_values().
ldap_get_lang_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. Use the
ldap_get_lang_values()
routine instead of this routine if the attribute values are string
values.
For more information, see "Getting the Values of an Attribute."
Syntax
#include <ldap.h> struct berval ** ldap_get_lang_values_len( LDAP *ld, LDAPMessage *entry, const char *target, char **type );
Parameters
This function has the following parameters:
Table 18-62 - ldap_get_lang_values_len() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
entry |
Result returned by the
ldap_result() or
ldap_search_s()
function.
|
target |
Attribute returned by
ldap_first_attribute()
or ldap_next_attribute() ,
or the attribute as a literal string, such as
"jpegPhoto " or "audio ".
|
type |
Pointer to a buffer that returns the attribute type retrieved by this function. |
Returns
One of the following values:
-
If successful, returns a NULL-terminated array of pointers to
berval
structures, which in turn contain pointers to the attribute's binary values. -
If unsuccessful or if no such attribute exists in the entry,
returns a NULL and sets the appropriate error code in the
LDAP structure. To get the error
code, call the
ldap_get_lderrno()
function. (See Chapter 19 "Result Codes" for a complete listing of error codes.)
See Also:
ldap_first_entry(),
ldap_next_entry(),
ldap_first_attribute(),
ldap_next_attribute(),
ldap_get_lang_values(),
ldap_get_values_len().
ldap_get_lderrno()
The ldap_get_lderrno()
function gets information
about the last error that occurred for an LDAP operation. You can
also call this function to get error codes for functions that do not
return errors (such as
ldap_next_attribute()
).
For more information, see "Getting Information About the Error."
Syntax
#include <ldap.h> int ldap_get_lderrno( LDAP *ld, char **m, char **s );
Parameters
This function has the following parameters:
Table 18-63 - ldap_get_lderrno() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
m |
In the event of an LDAP_NO_SUCH_OBJECT error return,
this parameter contains the portion of the DN that identifies an
existing entry. (See "Receiving the
Portion of the DN Matching an Entry.")
|
s |
The text of the error message. |
Returns
The LDAP error code for the last operation. (See Chapter 19 - Result Codes for a complete listing of error codes.)
Example
The following section of code attempts to add a new user to the
directory. If the entry identified by a DN does not exist, the
server sends the client a portion of the DN that find an existing
entry. This DN is returned to the client as the variable
matched
. (See "Receiving the
Portion of the DN Matching an Entry" for details.)
Code Example 18-21 - ldap_get_lderrno() code example
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 the example above, if no organizational unit named New
Department exists, the matched
variable is set to:
dc=example,dc=com
See Also:
ldap_err2string(),
ldap_perror(),
ldap_result2error(),
ldap_set_lderrno().
ldap_getnextfilter()
The ldap_getnextfilter()
function retrieves the next
filter that is appropriate for a given value. Call this function to
get subsequent filters after calling
ldap_getfirstfilter()
.
For more information, see "Retrieving
Filters."
Syntax
#include <ldap.h> LDAPFiltInfo * ldap_getnextfilter( LDAPFiltDesc *lfdp );
Parameters
This function has the following parameters:
Table 18-64 - ldap_getnextfilter() function parameters
lfdp |
Pointer to an
LDAPFiltDesc
structure.
|
Returns
One of the following values:
-
If successful, returns a pointer to an
LDAPFiltInfo
structure. - If no more filters can be returned, returns a
NULL
. - If unsuccessful, returns a
NULL
.
Example
See the example under
ldap_getfirstfilter()
.
See Also:
ldap_getfirstfilter().
ldap_get_option()
The function ldap_get_option()
gets session
preferences from an
LDAP
structure. For
information on the options you can retrieve with this function, see
ldap_set_option()
.
Syntax
#include <ldap.h> int ldap_get_option( LDAP *ld, int option, void *optdata );
Parameters
This function has the following parameters:
Table 18-65 - ldap_get_option() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
option |
Option that you want to retrieve.
The option parameter must be set to one of the option values, as
detailed in Table
18-117, which describes the function parameters for
ldap_set_option() .
|
optdata |
Pointer to the buffer in which the value of the option will be put. |
The following table describes the options that you can retrieve
with ldap_get_option()
.
Table 18-66 - Options for the ldap_get_options() function
LDAP_OPT_API_FEATURE_INFO |
Retrieves information about the revision of a supported LDAP feature. |
LDAP_OPT_API_INFO |
Retrieves information the API and the extensions supported,
including the supported API version, protocol version, the names
of the supported API extensions with their vendor name version.
For details on the structure returned, refer to the
ldap.h header file.
|
LDAP_OPT_CLIENT_CONTROLS |
Pointer to an array of
LDAPControl
structures representing the LDAPv3 client controls you want sent
with every request by default.
The data type for the optdata parameter is
(LDAPControl ***) .
|
LDAP_OPT_DESC |
Socket descriptor underlying the main LDAP connection.
The data type for the optdata parameter is
(LBER_SOCKET *) . The LBER_SOCKET data
type depends on the platform that you are using:
|
LDAP_OPT_DEREF |
Determines how aliases work during a search.
The data type for the optdata parameter is
(int *) .
optdata can be one of the following values:
|
LDAP_OPT_DNS_FN_PTRS |
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 |
Result code for the most recent LDAP error that occurred for
this session.
The data type for the optdata parameter is
(int *) .
|
LDAP_OPT_ERROR_STRING |
Error message returned with the result code for the most recent
LDAP error that occurred for this session.
The data type for the optdata parameter is
(char **) .
|
LDAP_OPT_EXTRA_THREAD_FN_PTRS |
Lets you specify the locking and semaphore functions that you
want called when getting results from the server. (See
Chapter 16 - Writing Multithreaded
Clients for details.)
The data type for the optdata parameter is
(struct ldap_extra_thread_fns *) .
|
LDAP_OPT_IO_FN_PTRS |
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. |
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.
The data type for the optdata parameter is
(int *) .
You can specify either LDAP_VERSION2 or
LDAP_VERSION3 . If no version is set, the default is
LDAP_VERSION2 .
In order to use LDAPv3 features, you need to set the protocol
version to LDAP_VERSION3 .
|
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.
The data type for the optdata parameter is
(int *) .
optdata can be one of the following values:
|
LDAP_OPT_REFERRALS |
Determines whether or not the client should follow referrals.
The data type for the optdata parameter is
(int *) .
optdata can be one of the following values:
|
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).
The data type for the optdata parameter is
(int *) .
By default, the maximum number of referrals that the client can
follow in a sequence is 5 for the initial connection.
Note that this limit does not apply to individual requests that
generate multiple referrals in parallel.
|
LDAP_OPT_RESTART |
Determines whether or not LDAP I/O operations should be restarted
automatically if they are prematurely aborted.
The data type for the optdata parameter is
(int *) .
optdata can be one of the following values:
|
LDAP_OPT_SERVER_CONTROLS |
Pointer to an array of
LDAPControl
structures representing the LDAPv3 server controls you want sent
with every request by default.
Typically, since controls are specific to the type of request,
you may want to pass the controls using operation-specific
functions (such as
ldap_add_ext() )
instead.
The data type for the optdata parameter is
(LDAPControl ***) .
|
LDAP_OPT_SIZELIMIT |
Maximum number of entries that should be returned by the server
in search results.
The data type for the optdata parameter is
(int *) .
Note that the LDAP server may impose a smaller size limit than
the limit you specify. (The server administrator has the ability
to set this limit.)
|
LDAP_OPT_SSL |
Determines whether or not SSL is enabled.
The data type for the optdata parameter is
(int *) .
optdata can be one of the following values:
|
LDAP_OPT_THREAD_FN_PTRS |
Lets you specify the thread function pointers. (See
Chapter 16 - Writing Multithreaded
Clients for details.)
The data type for the optdata parameter is
(struct ldap_thread_fns *) .
|
LDAP_OPT_TIMELIMIT |
Maximum number of seconds that should be spent by the server when
answering a search request.
The data type for the optdata parameter is
(int *) .
Note that the LDAP server may impose a shorter time limit than
the limit you specify. (The server administrator has the ability
to set this limit.)
|
Returns
One of the following values:
LDAP_SUCCESS
if successful.-1
if unsuccessful.
Examples
The following example gets the session preference for the maximum number of entries to be returned from search operations.
Code Example 18-22 - ldap_get_option() code example
... 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 ); }
Here are two small sections of code that show how to use the
LDAP_OPT_API_FEATURE_INFO
and the
LDAP_OPT_API_INFO
options, respectively:
ldfi.ldapaif_info_version = LDAP_FEATURE_INFO_VERSION; ldfi.ldapaif_name = "VIRTUAL_LIST_VIEW"; if (ldap_get_option(NULL, LDAP_OPT_API_FEATURE_INFO, &ldfi)==0) { /* use the info here */ } LDAPIInfo ldai; ldai.ldapiai_info_version = LDAP_API_INFO_VERSION; if (ldap_get_option( NULL, LDAP_OPT_API_INFO, &ldia ) == 0) { /* use the ldai info here */ }
See Also:
ldap_init(),
ldap_set_option().
ldap_get_values()
The ldap_get_values()
function returns a
NULL
-terminated array of an attribute's string values
for a given entry. Use the
ldap_get_values_len()
function instead of this function if the attribute values are binary.
For more information, see "Getting the Values of an Attribute."
Syntax
#include <ldap.h> char ** ldap_get_values( LDAP *ld, LDAPMessage *entry, const char *target );
Parameters
This function has the following parameters:
Table 18-67 - ldap_get_values() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
entry |
Result returned by the
ldap_result() or
ldap_search_s()
function.
|
target |
Attribute returned by
ldap_first_attribute()
or ldap_next_attribute() ,
or the attribute as a literal string, such as
"jpegPhoto " or "audio ".
|
Returns
One of the following values:
-
If successful, returns a
NULL
-terminated array of the attribute's values. -
If unsuccessful or if no such attribute exists in the entry,
returns a NULL and sets the appropriate error code in the
LDAP structure. To get the error
code, call the
ldap_get_lderrno()
function. (See Chapter 19 - Result Codes for a complete listing of error codes.)
Example
The following section of code gets and prints the values of an attribute in an entry. This example assumes that all attributes have string values.
Code Example 18-23 - ldap_get_values() code example
#include <ldap.h> ... LDAP *ld; LDAPMessage *result, *e; BerElement *ber; char *a; char **vals; char *my_searchbase = "dc=example,dc=com"; char *my_filter = "(sn=Jensen)"; int i; ... /* Search the directory */ if ( ldap_search_s( ld, my_searchbase, LDAP_SCOPE_SUBTREE, my_filter, NULL, 0, &result ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldap_search_s" ); return( 1 ); } /* Get the first matching entry.*/ e = ldap_first_entry( ld, result ); /* Get the first matching attribute */ a = ldap_first_attribute( ld, e, &ber ); /* Get the values of the attribute */ if ( ( vals = ldap_get_values( ld, e, a ) ) != NULL ) { for ( i = 0; vals[i] != NULL; i++ ) { /* Print the name of the attribute and each value */ printf( "%s: %s\n", a, vals[i] ); } /* Free the attribute values from memory when done. */ ldap_value_free( vals ); } ...
See Also:
ldap_first_entry(),
ldap_next_entry(),
ldap_first_attribute(),
ldap_next_attribute(),
ldap_get_lang_values(),
ldap_get_values_len().
ldap_get_values_len()
The ldap_get_values_len()
function returns a
NULL
-terminated array of pointers to
berval
structures,
each containing the length and pointer to a binary value of an
attribute for a given entry. Use the
ldap_get_values()
routine instead of this routine if the attribute values are string
values.
For more information, see "Getting the Values of an Attribute."
Syntax
#include <ldap.h> struct berval ** ldap_get_values_len( LDAP *ld, LDAPMessage *entry, const char *target );
Parameters
This function has the following parameters:
Table 18-68 - ldap_get_values_len() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
entry |
Result returned by the
ldap_result() or
ldap_search_s()
function.
|
target |
Attribute returned by
ldap_first_attribute()
or ldap_next_attribute() ,
or the attribute as a literal string, such as
"jpegPhoto " or "audio ".
|
Returns
One of the following values:
-
If successful, returns a
NULL
-terminated array of pointers toberval
structures, which in turn contain pointers to the attribute's binary values. -
If unsuccessful or if no such attribute exists in the entry,
returns a NULL and sets the appropriate error code in the
LDAP structure. To get the error
code, call the
ldap_get_lderrno()
function. (See Chapter 19 - Result Codes for a complete listing of error codes.)
Example
The following section of code gets the first value of the
jpegPhoto
attribute and saves the JPEG data to a file.
Code Example 18-24 - ldap_get_values_len() code example
#include <ldap.h> ... LDAP *ld; LDAPMessage *result, *e; BerElement *ber; struct berval photo_data; struct berval **list_of_photos; FILE *out; char *my_searchbase = "dc=example,dc=com"; char *my_filter = "(sn=Jensen)"; ... /* Search the directory */ if ( ldap_search_s( ld, my_searchbase, LDAP_SCOPE_SUBTREE, my_filter, NULL, 0, &result ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldap_search_s" ); return( 1 ); } /* Get the first matching entry.*/ e = ldap_first_entry( ld, result ); /* Get the value of the jpegPhoto attribute */ if ( ( list_of_photos = ldap_get_values_len( ld, e, "jpegPhoto" ) ) != NULL ) { /* Prepare to write the JPEG data to a file */ if ( ( out = fopen( "photo.jpg", "wb" ) ) == NULL ) { perror( "fopen" ); return( 1 ); } /* Get the first JPEG */ photo_data = *list_of_photos[0]; /* Write the JPEG data to a file */ fwrite( photo_data.bv_val, photo_data.bv_len, 1, out ); fclose( out ); /* Free the attribute values from memory when done. */ ldap_value_free_len( list_of_photos ); } ...
See Also:
ldap_first_entry(),
ldap_next_entry(),
ldap_first_attribute(),
ldap_next_attribute(),
ldap_get_lang_values_len(),
ldap_get_values().
ldap_init()
Initializes a session with an LDAP server and returns an LDAP structure that represents the context of the connection to that server.
Syntax
#include <ldap.h> LDAP * ldap_init( const char *defhost, int defport );
Parameters
This function has the following parameters:
Table 18-69 - ldap_init() function parameters
defhost |
Space-delimited list of one or more host names (or IP address in
dotted notation, such as "141.211.83.36") of the LDAP servers
that you want the LDAP client to connect to.
The names can be in hostname:portnumber format (in
which case, portnumber overrides the port number
specified by the defport argument.
|
defport |
Default port number of the LDAP server. To specify the standard
LDAP port (port 389), use LDAP_PORT as the value for
this parameter.
|
Returns
One of the following values:
- If successful, returns a pointer to an LDAP structure.
- If unsuccessful, returns a
NULL
.
Description
The ldap_init()
function initializes a session with
an LDAP server. ldap_init()
allocates 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.
You can specify a list of LDAP servers that you want to attempt to connect to. 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.
You can specify the list of LDAP servers by passing a space-delimited list of the host names as the host argument. For example:
... LDAP *ld ... ld = ldap_init( "ld1.example.com ld2.example.com \ ld3.example.com", LDAP_PORT );
In the example above, the LDAP client will attempt to connect to
the LDAP server on ld1.example.com
, port 389. If that
server does not respond, the client will attempt to connect to the
LDAP server on ld2.example.com
, port 389. If that
server does not respond, the client will use the server on
ld3.example.com
, port 389.
If any of the servers do not use the default port specified by
the defport
argument, use the
host:port
format to specify the server name.
For example:
...
LDAP *ld ... ld = ldap_init( "ld1.example.com ld2.example.com:38900", \ LDAP_PORT );
In the example above, the LDAP client will attempt to connect to
the LDAP server on ld1.example.com
, port 389. If that
server does not respond, the client will attempt to connect to the
LDAP server on ld2.example.com
, port 38900.
Once you initialize a session, you need to call the
ldap_simple_bind()
or
ldap_simple_bind_s()
function to connect and authenticate to the LDAP server.
For more information, see "Initializing an LDAP Session."
Note that if you are connecting to a secure LDAP server over SSL,
you should be calling the
ldapssl_init()
function instead. For details, see
Chapter 12 "Connecting Over SSL."
Example
The following section of code initializes a session with the LDAP
server at ldap.example.com:389
.
Code Example 18-25 - ldap_init() code example
#include <ldap.h> ... LDAP *ld; /* Specify the host name of the LDAP server. */ char *ldap_host = "ldap.example.com"; /* Because the LDAP server is running on the standard LDAP port (port 389), you can use LDAP_PORT to identify the port number. */ int ldap_port = LDAP_PORT; ... /* Initialize the session with ldap.example.com:389 */ if ( ( ld = ldap_init( ldap_host, ldap_port ) ) == NULL ) { perror( "ldap_init" ); return( 1 ); } ... /* Subsequent calls that authenticate to the LDAP server. */ ...
See Also:
ldap_unbind(),
ldap_unbind_s().
ldap_init_getfilter()
The ldap_init_getfilter()
function reads a valid
LDAP filter configuration file (such as ldapfilter.conf
)
and returns a pointer to an
LDAPFiltDesc
structure.
For more information, see "Loading a Filter Configuration File."
Syntax
#include <ldap.h> LDAPFiltDesc * ldap_init_getfilter( char *fname );
Parameters
This function has the following parameters:
Table 18-70 - ldap_init_getfilter() function parameters
fname |
Name of the LDAP filter configuration file to use. |
Returns
One of the following values:
-
If successful, returns a pointer to an
LDAPFiltDesc
structure. -
If unsuccessful (for example, if there is an error reading the
file), returns a
NULL
.
Example
The following section of code loads the filter configuration file
named myfilters.conf
into memory.
Code Example 18-26 - Loading a filter configuration file
#include <ldap.h> ... LDAPFiltDesc *lfdp; char *filter_file = "myfilters.conf"; ... lfdp = ldap_init_getfilter( filter_file ); ...
See Also:
ldap_init_getfilter_buf(),
ldap_getfilter_free().
ldap_init_getfilter_buf()
The ldap_init_getfilter_buf()
function reads LDAP
filter configuration information from a buffer and returns a pointer
to an LDAPFiltDesc
structure. The configuration information in the buffer must use the
correct syntax, as specified in
"Understanding the Configuration File
Syntax."
For more information, see "Loading a Filter Configuration File."
Syntax
#include <ldap.h> LDAPFiltDesc * ldap_init_getfilter_buf(char *buf, long buflen );
Parameters
This function has the following parameters:
Table 18-71 - ldap_init_getfilter_buf() function parameters
buf |
Buffer containing LDAP filter configuration information. |
buflen |
Size of the buffer |
Returns
One of the following values:
-
If successful, returns a pointer to an
LDAPFiltDesc
structure. -
If unsuccessful (for example, if there is an error reading the
file), returns a
NULL
.
Example
The following section of code copies the following filter configuration to a buffer in memory.
"ldap-example" "@" " " "(mail=%v)" "email address" "(mail=%v*)" "start of email address"
The example uses this buffer to fill an
LDAPFiltDesc
structure.
Code Example 18-27 - ldap_init_getfilter() code example
See Also:
< p>ldap_init_getfilter(), ldap_getfilter_free().
ldap_is_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 toldap://
(orldaps://
, if the server is communicating over an SSL connection).For more information, see "Determining If a URL is an LDAP URL."
Syntax
#include <ldap.h> int ldap_is_ldap_url( const char *url );Parameters
This function has the following parameters:
Table 18-72 - ldap_is_ldap_url() function parameters
url |
The URL that you want to check. |
Returns
One of the following values:
1
if the URL is an LDAP URL.0
if the URL is not an LDAP URL.
Example
The following section of code determines if a URL is an LDAP URL.
Code Example 18-28 - ldap_is_ldap_url() code example
#include <ldap.h> ... char *my_url = "ldap://ldap.example.com/dc=example,dc=com"; ... if ( ldap_is_ldap_url( my_url ) != 0 ) { printf( "%s is an LDAP URL.\n", my_url ); } else { printf( "%s is not an LDAP URL.\n", my_url ); } ...
See Also:
ldap_url_parse().
ldap_memcache_destroy()
Frees an LDAPMemCache
structure from memory.
Syntax
#include <ldap.h> void ldap_memcache_destroy( LDAPMemCache *cache );
Parameters
This function has the following parameters:
Table 18-73 - ldap_memcache_destroy() function parameters
cache |
Pointer to the
LDAPMemCache
structure that you want freed from memory.
|
Description
The ldap_memcache_destroy()
function frees the
specified LDAPMemCache
structure from memory. Call this function after you are done working
with a cache.
See Also:
ldap_memcache_init().
ldap_memcache_flush()
Flushes items from the specified cache.
Syntax
#include <ldap.h> void ldap_memcache_flush( LDAPMemCache *cache, char *dn, int scope );
Parameters
This function has the following parameters:
Table 18-74 - ldap_memcache_flush() function parameters
cache |
Pointer to the
LDAPMemCache
structure that you want to flush entries from.
|
dn |
Base DN identifying the search requests that you want flushed
from the cache. If the base DN of a search request is within the
scope specified by this DN and the scope argument,
the search request is flushed from the cache.
If this argument is NULL , the entire cache is flushed.
|
scope |
Scope that (together with the dn argument)
identifies the search requests that you want flushed from the
cache. If the base DN of the request is within the scope
specified by this argument and the dn argument, the
request is flushed from the cache.
This argument can have one of the following values:
|
Description
The ldap_memcache_flush()
function flushes search
requests from the cache. If the base DN of a search request is
within the scope specified by the dn
and
scope
arguments, the search request is flushed from the
cache.
If no DN is specified, the entire cache is flushed.
ldap_memcache_get()
Gets the in-memory cache associated with an LDAP connection handle.
Syntax
#include <ldap.h> int ldap_memcache_get( LDAP *ld, LDAPMemCache **cachep );
Parameters
This function has the following parameters:
Table 18-75 - ldap_memcache_get() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
cachep |
When you call this function, the function sets this parameter to
the pointer to the
LDAPMemCache
structure associated with the connection handle.
|
Returns
One of the following values:
-
LDAP_SUCCESS
if the cache for the specified connection handle was retrieved successfully. -
LDAP_PARAM_ERROR
if an invalid parameter was passed to the function.
Description
The ldap_memcache_get()
function gets the cache
associated with the specified connection handle
(LDAP structure). This cache is
used by all search requests made through that connection.
You can call this function if you want to associate a cache with
multiple LDAP connection handles. For example, you can call this
function to get the cache associated with one connection, then you
can call the
ldap_memcache_set()
function to associate the cache with another connection.
See Also:
ldap_memcache_set().
ldap_memcache_init()
Creates an in-memory cache for your LDAP client that you can associate with an LDAP connection.
Syntax
#include <ldap.h> int ldap_memcache_init( unsigned long ttl, unsigned long size, char **baseDNs, struct ldap_thread_fns *thread_fns, LDAPMemCache **cachep );
Parameters
This function has the following parameters:
Table 18-76 - ldap_memcache_init() function parameters
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.
|
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, the function sets this parameter to
the pointer to the newly created
LDAPMemCache structure.
|
Returns
One of the following values:
LDAP_SUCCESS
if the cache was successfully created.-
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 thesize
argument) is too small.
Description
The ldap_memcache_init()
function creates an
in-memory, client-side cache that you can use to cache search
requests.
The function passes back a pointer to an
LDAPMemCache
structure,
which represents the cache. You should call the
ldap_memcache_set()
function to associate this cache with an LDAP connection handle (an
LDAP structure).
The cache uses search criteria as the key to cached items. When you send a search request, the cache checks the search criteria to determine if that request has been cached previously. If the request was cached, the search results are read from the cache.
To flush the cache, call the
ldap_memcache_flush()
function.
When you are done with the cache, you can free it from memory by
calling the
ldap_memcache_destroy()
function.
See Also:
LDAPMemCache,
ldap_memcache_set(), ,
ldap_memcache_update(),
ldap_memcache_flush(),
ldap_memcache_destroy().
ldap_memcache_set()
Associates an in-memory cache with an LDAP connection handle.
Syntax
#include <ldap.h> int ldap_memcache_set( LDAP *ld, LDAPMemCache *cache );
Parameters
This function has the following parameters:
Table 18-77 - ldap_memcache_set() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
cache |
Pointer to an
LDAPMemCache
structure, which represents the cache that you want used for
this connection.
|
Returns
One of the following values:
-
LDAP_SUCCESS
if the cache was successfully associated with the connection handle. -
LDAP_PARAM_ERROR
if an invalid parameter was passed to the function. -
LDAP_SIZELIMIT_EXCEEDED
if the size of the cache is too small.
Description
The ldap_memcache_set()
function associates a cache
that you have created (by calling the
ldap_memcache_init()
function) with an LDAP connection handle.
After you call this function, search requests made over the
specified LDAP connection will use this cache. Note that calling the
ldap_unbind()
function
or the ldap_unbind()
function will disassociate the cache from the 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 this function associate the cache with another connection.
See Also:
ldap_memcache_init(),
ldap_memcache_get().
ldap_memcache_update()
Checks the cache for items that have expired and removes them.
Syntax
#include <ldap.h> void ldap_memcache_update( LDAPMemCache *cache );
Parameters
This function has the following parameters:
Table 18-78 - ldap_memcache_update() function parameters
cache |
Pointer to an
LDAPMemCache
structure, which represents the cache that you want to updated.
|
Description
The ldap_memcache_update()
function checks the cache
for items that have expired and removes them. This check is
typically done as part of the way the cache normally works. You do
not need to call this function unless you want to update the cache
at this point in time.
This function is only useful in a multithreaded application, since it will not return until the cache is destroyed.
See Also:
ldap_memcache_flush().
ldap_memfree()
ldap_memfree()
frees memory allocated by an LDAP API
function call. For more information, see
"Managing Memory."
Syntax
#include <ldap.h> void ldap_memfree( void *p );
Parameters
This function has the following parameters:
Table 18-79 - ldap_memfree() function parameter
p |
Pointer to memory used by the LDAP library. |
Example
The following section of code frees the memory allocated by the
ldap_get_dn()
function.
Code Example 18-29 - ldap_memfree() code example
... LDAP *ld; char *dn; LDAPMessage *entry; ... /* Get the distinguished name (DN) for an entry */ dn = ldap_get_dn( ld, entry ); ... /* When you are finished working with the DN, free the memory allocated for the DN */ ldap_memfree( dn ); ...
See Also:
ldap_free_friendlymap(),
ldap_free_urldesc(),
ldap_msgfree(),
ldap_value_free(),
ldap_value_free_len().
ldap_modify()
Modifies an existing entry in the directory asynchronously.
Note that this is an older function that is included in the LDAP
API for backward-compatibility. If you are writing a new LDAP client,
use ldap_modify_ext()
instead.
Syntax
#include <ldap.h> int ldap_modify( LDAP *ld, const char *dn, LDAPMod **mods );
Parameters
This function has the following parameters:
Table 18-80 - ldap_modify() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
dn |
Distinguished name (DN) of the entry to modify. |
mods |
Pointer to a NULL-terminated array of pointers to
LDAPMod structures
representing the attributes that you want to modify.
|
Returns
Returns the message ID of the ldap_modify()
operation. To check the result of this operation, call
ldap_result()
and
ldap_result2error()
.
For a list of possible result codes for an LDAP modify operation,
see the result code documentation on the
ldap_modify_ext_s()
function.
Description
The ldap_modify()
function updates an entry in the
directory.
A newer version of this function,
ldap_modify_ext()
, is
available in this release of the LDAP API.
ldap_modify()
(the older version of the function) is
included only for backward-compatibility. If you are writing a new
LDAP client, use
ldap_modify_ext()
instead of ldap_modify()
.
If you want more information on ldap_modify()
, refer
to the LDAP C SDK 1.0 Programmer's Guide.
Example
The following section of code uses the asynchronous
ldap_modify()
function to modify the entry for "Barbara
Jensen" in the directory. The example makes the following changes to
the entry:
- Adds the
homePhone
attribute. - Changes the
telephoneNumber
attribute. - Removes the
facsimileTelephoneNumber
attribute.
Code Example 18-30 - ldap_modify() code example
#include <ldap.h> ... LDAP *ld; LDAPMod *list_of_attrs[4]; LDAPMod attribute1, attribute2, attribute3; LDAPMessage *result; int msgid, rc; struct timeval tv; /* Distinguished name of the entry that you want to modify. */ char *dn = "uid=bjensen, ou=People, dc=example,dc=com"; /* Values to add or change */ char *homePhone_values[] = { "555-1212", NULL }; char *telephoneNumber_values[] = { "869-5309", NULL }; ... /* Specify each change in separate LDAPMod structures */ attribute1.mod_type = "homePhone"; attribute1.mod_op = LDAP_MOD_ADD; attribute1.mod_values = homePhone_values; attribute2.mod_type = "telephoneNumber"; attribute2.mod_op = LDAP_MOD_REPLACE; attribute2.mod_values = telephoneNumber_values; attribute3.mod_type = "facsimileTelephoneNumber"; attribute3.mod_op = LDAP_MOD_DELETE; attribute3.mod_values = NULL; /* NOTE: When removing entire attributes, you need to specify a NULL value for the mod_values field. */ /* Add the pointers to these LDAPMod structures to an array */ list_of_attrs[0] = &attribute1; list_of_attrs[1] = &attribute2; list_of_attrs[2] = &attribute3; list_of_attrs[3] = NULL; ... /* Set up the timeout period to wait for the "modify" operation */ tv.tv_sec = tv.tv_usec = 0; /* Change the entry */ if ( ( msgid = ldap_modify( ld, dn, list_of_attrs ) ) == -1 ) { ldap_perror( ld, "ldap_modify" ); return( 1 ); } /* Check to see if the operation has completed */ while ( ( rc = ldap_result( ld, msgid, 0, &tv, &result ) ) == 0 ) { ... /* do other work while waiting for the operation to complete */ ... } /* Check the result to see if any errors occurred */ ldap_result2error( ld, result, 1 ); ldap_perror( ld, "ldap_modify" ); ...
See Also:
ldap_modify_ext().
ldap_modify_ext()
Modifies an existing entry in the directory asynchronously.
Syntax
#include <ldap.h> int ldap_modify_ext( LDAP *ld, const char *dn, LDAPMod **mods, LDAPControl **serverctrls, LDAPControl **clientctrls, int *msgidp );
Parameters
This function has the following parameters:
Table 18-81 - ldap_modify_ext() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
dn |
Distinguished name (DN) of the entry to 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
LDAP operation. If you do not want to pass any server controls,
specify NULL for this argument.
|
clientctrls |
Pointer to an array of
LDAPControl
structures representing LDAP client controls that apply to this
LDAP operation. If you do not want to pass any client controls,
specify NULL for this argument.
|
msgidp |
Pointer to an integer that will be set to the message ID of the
LDAP operation. To check the result of this operation, call
ldap_result() and
ldap_parse_result()
functions.
|
Returns
One of the following values:
LDAP_SUCCESS
if successful.LDAP_PARAM_ERROR
if any of the arguments are invalid.-
LDAP_ENCODING_ERROR
if an error occurred when BER-encoding the request. -
LDAP_SERVER_DOWN
if the LDAP server did not receive the request or if the connection to the server was lost. LDAP_NO_MEMORY
if memory cannot be allocated.-
LDAP_NOT_SUPPORTED
if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAPv3 protocol. Make sure that you set the version of your LDAP client to version 3 before calling this function. (For details, see "Specifying the LDAP Version of Your Client.")
Description
The ldap_modify_ext()
modifies an entry in the
directory asynchronously.
This function is a new version of the
ldap_modify()
function.
If you are writing a new LDAP client, you should call this function
instead of ldap_modify()
.
To make changes to an entry to the directory, you need to specify the following information:
-
A unique DN identifying the new entry. Use the
dn
argument to specify the DN of the entry that you want to modify. -
A set of attributes for the new entry. Create an
LDAPMod
structure for change that you want to make to an attribute. Create an array of theseLDAPMod
structures and pass the array as themods
argument. For information on using theLDAPMod
structure to specify a change, seeLDAPMod
.
The function ldap_modify_ext()
is 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. (For more information on asynchronous and synchronous
functions, see "Calling Synchronous and
Asynchronous Functions.")
In order to get the results of the LDAP modify operation, you
need to call the
ldap_result()
function
and the ldap_parse_result()
function. (See "Calling Asynchronous
Functions" for details.) For a list of possible result codes for
an LDAP modify operation, see the result code documentation for the
ldap_modify_ext_s()
function.
For more information on modifying entries in the directory, see "Modifying an Entry."
Example
See the example under "Example: Modifying an Entry in the Directory (Asynchronous)."
See Also:
ldap_modify_ext_s(),
ldap_result(),
ldap_parse_result(),
LDAPMod.
ldap_modify_ext_s()
Modifies an existing entry in the directory synchronously.
Syntax
#include <ldap.h> int ldap_modify_ext_s( LDAP *ld, const char *dn, LDAPMod **mods, LDAPControl **serverctrls, LDAPControl **clientctrls );
Parameters
This function has the following parameters:
Table 18-82 - ldap_modify_ext_s() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
dn |
Distinguished name (DN) of the entry to modify. |
mods |
Pointer to a NULL-terminated array of pointers to
LDAPMod structures
for the attributes you want modified.
|
serverctrls |
Pointer to an array of
LDAPControl
structures representing LDAP server controls that apply to this
LDAP operation. If you do not want to pass any server controls,
specify NULL for this argument.
|
clientctrls |
Pointer to an array of
LDAPControl
structures representing LDAP client controls that apply to this
LDAP operation. If you do not want to pass any client controls,
specify NULL for this argument.
|
Returns
One of the following values:
LDAP_SUCCESS
if successful.LDAP_PARAM_ERROR
if any of the arguments are invalid.-
LDAP_ENCODING_ERROR
if an error occurred when BER-encoding the request. -
LDAP_SERVER_DOWN
if the LDAP server did not receive the request or if the connection to the server was lost. LDAP_NO_MEMORY
if memory cannot be allocated.-
LDAP_LOCAL_ERROR
if an error occurred when receiving the results from the server. -
LDAP_DECODING_ERROR
if an error occurred when decoding the BER-encoded results from the server. -
LDAP_NOT_SUPPORTED
if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAPv3 protocol. Make sure that you set the version of your LDAP client to version 3 before calling this function. (For details, see "Specifying the LDAP Version of Your Client.")
The following result codes can be returned by the Directory Server when processing an LDAP modify request. Other LDAP servers may send these result codes under different circumstances or may send different result codes back to your LDAP client.
-
LDAP_OPERATIONS_ERROR
may be sent by the Directory Server for general errors encountered by the server when processing the request. -
LDAP_PROTOCOL_ERROR
if the modify request did not comply with the LDAP protocol. The Directory Server may set this error code in the results for a variety of reasons. Some of these reasons include:- The server encountered an error when decoding your client's BER-encoded request.
-
An unknown modification operator (other that
LDAP_MOD_ADD
,LDAP_MOD_DELETE
, andLDAP_MOD_REPLACE
) is specified in the request. -
The modification operator is
LDAP_MOD_ADD
and no values are specified. - No modifications are specified.
-
LDAP_CONSTRAINT_VIOLATION
may be sent by the Directory Server if your client is attempting to modify theuserpassword
attribute in the following situations:-
The server is configured to require a minimum password length
and the new value of the
userpassword
attribute is shorter than the minimum length. -
The server is configured to keep track of previous passwords,
and the new value of the
userpassword
attribute is the same as a previous value of that attribute. -
The new value of the
userpassword
attribute is the same as the value of theuid
,cn
,sn
,givenname
,ou
, ormail
attributes. (Using a password that is the same as your user id or email address would make the password trivial and easy to crack.)
-
The server is configured to require a minimum password length
and the new value of the
-
LDAP_UNWILLING_TO_PERFORM
may be sent by the Directory Server in the following situations:-
Your client is attempting to modify the
aci
attribute and an error occurs. -
The value of the
userpassword
attribute needs to be changed. (The password has expired.) - Your client is attempting to add attributes to the configuration DSE (DSA-specific entry, where DSA stands for Directory-Specific Agent).
- Your client is attempting to replace attributes in the schema DSE.
- The server's database is read-only.
-
Your client is attempting to modify the
-
LDAP_REFERRAL
may be sent by the Directory Server if the DN specified by thedn
argument identifies an entry not handled by the current server and if referral URLs identify a different server to handle the entry. (For example, if the DN isuid=bjensen, ou=European Sales, dc=example,dc=com
, all entries underou=European Sales
might be handled by a different directory server.) -
LDAP_NO_SUCH_ATTRIBUTE
may be sent by the Directory Server if the attribute that you want to modify (add, replace, or delete) does not exist. -
LDAP_INVALID_SYNTAX
may be sent by the Directory Server if your client is modifying the schema DSE and no object class or attribute type is specified. -
LDAP_NO_SUCH_OBJECT
may be sent by the Directory Server if the entry that you want modified does not exist. -
LDAP_INSUFFICIENT_ACCESS
may be sent by the Directory Server if the DN that your client is authenticated as does not have the access rights to modify the entry. -
LDAP_TYPE_OR_VALUE_EXISTS
may be sent by the Directory Server if your client is attempting to add an attribute to an entry and the attribute values already exist in the entry. -
LDAP_OBJECT_CLASS_VIOLATION
may be sent by the Directory Server if the modified entry does not comply with the Directory Server schema (for example, if one or more required attributes are not specified). -
LDAP_NOT_ALLOWED_ON_RDN
may be sent by the Directory Server if the modified entry no longer contains attributes for each DN component.
Note that the Directory Server may send other result codes in addition to the codes described here (for example, the server may have loaded a custom plug-in that returns other result codes).
Description
The ldap_modify_ext_s()
modifies an entry in the
directory synchronously.
This function is a new version of the
ldap_modify_s()
function. If you are writing a new LDAP client, you should call this
function instead of
ldap_modify_s()
.
To make changes to an entry to the directory, you need to specify the following information:
-
A unique DN identifying the new entry.
Use the
dn
argument to specify the DN of the entry that you want to modify. -
A set of attributes for the new entry.
Create an
LDAPMod
structure for change that you want to make to an attribute. Create an array of theseLDAPMod
structures and pass the array as themods
argument. For information on using theLDAPMod
structure to specify a change, seeLDAPMod
.
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. (For more information on asynchronous and synchronous
functions, see "Calling Synchronous and
Asynchronous Functions.")
For more information on modifying entries in the directory, see "Modifying an Entry."
Example
See the example under "Example: Modifying an Entry in the Directory (Synchronous)."
See Also:
ldap_modify_ext(),
LDAPMod.
ldap_modify_s()
Modifies an existing entry in the directory synchronously.
Note that this is an older function that is included in the LDAP
API for backward-compatibility. If you are writing a new LDAP
client, use
ldap_modify_ext_s()
instead.
Syntax
#include <ldap.h> int ldap_modify_s( LDAP *ld, const char *dn, LDAPMod **mods );
Parameters
This function has the following parameters:
Table 18-83 - ldap_modify_s() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
dn |
Distinguished name (DN) of the entry to modify. |
mods |
Pointer to a NULL -terminated array of pointers to
LDAPMod structures
for the attributes you want modified.
|
Returns
For a list of possible result codes for an LDAP modify operation,
see the result code documentation for the
ldap_modify_ext_s()
function.
Description
The ldap_modify_s()
function updates an entry in the
directory.
A newer version of this function,
ldap_modify_ext_s()
,
is available in this release of the LDAP API.
ldap_modify_s()
(the older version of the function) is
included only for backward-compatibility. If you are writing a new
LDAP client, use
ldap_modify_ext_s()
instead of ldap_modify_s()
.
If you want more information on ldap_modify_s()
,
refer to the LDAP C SDK 1.0 Programmer's Guide.
Example
The following section of code uses the synchronous
ldap_modify_s()
function to makes the following changes
to the "Barbara Jensen
" entry:
- Adds the
homePhone
attribute. - Changes the
telephoneNumber
attribute. - Removes the
facsimileTelephoneNumber
attribute.
Code Example 18-31 - ldap_modify_s() code example
#include <ldap.h> ... LDAP *ld; LDAPMod *list_of_attrs[4]; LDAPMod attribute1, attribute2, attribute3; LDAPControl **srvrctrls, **clntctrls; /* Distinguished name of the entry that you want to modify. */ char *dn = "uid=bjensen, ou=People, dc=example,dc=com"; /* Values to add or change */ char *homePhone_values[] = { "555-1212", NULL }; char *telephoneNumber_values[] = { "869-5309", NULL }; ... /* Specify each change in separate LDAPMod structures */ attribute1.mod_type = "homePhone"; attribute1.mod_op = LDAP_MOD_ADD; attribute1.mod_values = homePhone_values; attribute2.mod_type = "telephoneNumber"; attribute2.mod_op = LDAP_MOD_REPLACE; attribute2.mod_values = telephoneNumber_values; attribute3.mod_type = "facsimileTelephoneNumber"; attribute3.mod_op = LDAP_MOD_DELETE; attribute3.mod_values = NULL; /* NOTE: When removing entire attributes, you need to specify a NULL value for the mod_values or mod_bvalues field. */ /* Add the pointers to these LDAPMod structures to an array */ list_of_attrs[0] = &attribute1; list_of_attrs[1] = &attribute2; list_of_attrs[2] = &attribute3; list_of_attrs[3] = NULL; ... /* Change the entry */ if ( ldap_modify_s( ld, dn, list_of_attrs ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldap_modify_s" ); return( 1 ); } ...
See Also:
ldap_modify_ext_s().
ldap_modrdn()
The ldap_modrdn()
function is a deprecated function.
Use the ldap_rename()
or ldap_modrdn2()
functions instead.
ldap_modrdn_s()
The ldap_modrdn_s()
function is a deprecated
function. Use the
ldap_rename_s()
or
ldap_modrdn2_s()
functions instead.
ldap_modrdn2()
Changes the relative distinguished name (RDN) of an entry in the directory asynchronously.
Note that this is an older function that is included in the LDAP
API for backward-compatibility. If you are writing a new LDAP
client, use ldap_rename()
instead.
#include <ldap.h> int ldap_modrdn2( LDAP *ld, const char *dn, const char *newrdn, int deleteoldrdn );
Parameters
This function has the following parameters:
Table 18-84 - ldap_modrdn2() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
dn |
Distinguished name (DN) of the entry to modify. |
newrdn |
New relative distinguished name (RDN) to assign to the entry. |
deleteoldrdn |
If this is a non-zero value, the old RDN is not retained as a
value in the modified entry. If 0 , the old RDN is
retained as an attribute in the modified entry.
|
Returns
Returns the message ID of the ldap_modrdn2()
operation. To check the result of this operation, call
ldap_result()
and
ldap_result2error()
.
For a list of possible result codes, see the result code
documentation for the
ldap_rename_s()
function.
Description
The ldap_modrdn2()
function modifies the relative
distinguished name (RDN) of an entry in a directory and lets you
specify whether or not the old RDN is retained as an attribute of
the entry.
A newer version of this function,
ldap_rename()
, is
available in this release of the LDAP API. ldap_modrdn2()
(the older version of the function) is included only for
backward-compatibility. If you are writing a new LDAP client, use
ldap_rename()
instead
of ldap_modrdn2()
.
If you want more information on ldap_modrdn2()
,
refer to the LDAP C SDK 1.0 Programmer's Guide.
Example
The following section of code uses the asynchronous
ldap_modrdn2()
function to change the RDN of an entry
from "uid=bjensen
" to "uid=babs
". The code
removes the existing RDN "bjensen
" from the
uid
attribute of the entry.
Code Example 18-32 - ldap_modrdn2() code example
... LDAP *ld; LDAPMessage *result; int msgid, rc; struct timeval tv; /* Distinguished name of the entry that you want to rename. */ char *dn = "uid=bjensen, ou=People, dc=example,dc=com"; /* New relative distinguished name (RDN) of the entry */ char *rdn = "uid=babs"; ... /* Set up the timeout period to wait for the "modify RDN" operation */ tv.tv_sec = tv.tv_usec = 0; /* Rename the entry */ if ( ( msgid = ldap_modrdn2( ld, dn, rdn, 1 ) ) == -1 ) { ldap_perror( ld, "ldap_modrdn2" ); return( 1 ); } /* Check to see if the operation has completed */ while ( ( rc = ldap_result( ld, msgid, 0, &tv, &result ) ) == 0 ) { ... /* do other work while waiting for the operation to complete */ ... } /* Check the result to see if any errors occurred */ ldap_result2error( ld, result, 1 ); ldap_perror( ld, "ldap_modrdn2" ); ...
See Also:
ldap_rename().
ldap_modrdn2_s()
Changes the relative distinguished name (RDN) of an entry in the directory synchronously.
Note that this is an older function that is included in the LDAP
API for backward-compatibility. If you are writing a new LDAP client,
use ldap_rename_s()
instead.
Syntax
#include <ldap.h> int ldap_modrdn2_s( LDAP *ld, const char *dn, const char *newrdn, int deleteoldrdn );
Parameters
This function has the following parameters:
Table 18-85 - ldap_modrdn2_s() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
dn |
Distinguished name (DN) of the entry to modify. |
newrdn |
New relative distinguished name (RDN) to assign to the entry. |
deleteoldrdn |
If this is a non-zero value, the old RDN is not retained as a
value in the modified entry. If 0 , the old RDN is
retained as an attribute in the modified entry.
|
Returns
For a list of possible result codes, see the result code
documentation for the
ldap_rename_s()
function.
Description
The ldap_modrdn2_s()
function modifies the relative
distinguished name (RDN) of an entry in a directory and lets you
specify whether or not the old RDN is retained as an attribute of
the entry.
A newer version of this function,
ldap_rename_s()
, is
available in this release of the LDAP API.
ldap_modrdn2_s()
(the older version of the function) is
included only for backward-compatibility. If you are writing a new
LDAP client, use
ldap_rename_s()
instead
of ldap_modrdn2_s()
.
If you want more information on ldap_modrdn2_s()
,
refer to the LDAP C SDK 1.0 Programmer's Guide.
Example
The following section of code uses the synchronous
ldap_modrdn2_s()
function to change the RDN of an entry
from "uid=bjensen
" to "uid=babs
". The code
removes the existing RDN "babs
" from the
uid
attribute of the entry.
Code Example 18-33 - ldap_modrdn2_s() code example
... LDAP *ld; /* Distinguished name of the entry that you want to rename. */ char *dn = "uid=bjensen, ou=People, dc=example,dc=com"; /* New relative distinguished name (RDN) of the entry */ char *rdn = "uid=babs"; ... /* Rename the entry */ if ( ldap_modrdn2_s( ld, dn, rdn, 1 ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldap_modrdn2_s" ); return( 1 ); } ...
See Also:
ldap_rename_s().
ldap_mods_free()
The ldap_mods_free()
function frees the
LDAPMod
structures
that you've allocated to add or modify entries. You need to call
this function only if you've allocated memory for these structures
yourself.
Syntax
#include <ldap.h> void ldap_mods_free( LDAPMod **mods, int freemods );
Parameters
This function has the following parameters:
Table 18-86 - ldap_mods_free() function parameters
mods |
Pointer to a NULL-terminated array of pointers to
LDAPMod structures.
|
freemods |
If this is a non-zero value, frees the array of pointers as well
as the LDAPMod
structures. If 0, just frees the
LDAPMod structures.
|
Example
The following example allocates memory for
LDAPMod
structures and
frees them when done.
Code Example 18-34 - ldap_mods_free() code example
#include <ldap.h> ... LDAP *ld; char *dn; int i, msgid; LDAPMod **mods; ... /* Construct the array of values to add */ mods = ( LDAPMod ** ) malloc(( NMODS + 1 ) * sizeof( LDAPMod * )); if ( mods == NULL ) { fprintf( stderr, "Cannot allocate memory for mods array\n" ); } for ( i = 0; i < NMODS; i++ ) { if (( mods[ i ] = ( LDAPMod * ) malloc( sizeof( LDAPMod ))) == NULL) { fprintf( stderr, "Cannot allocate memory for mods element\n" ); exit( 1 ); } } ... /* Code for filling the structures goes here. */ ... /* Initiate the add operation */ if (( msgid = ldap_add( ld, dn, mods )) < 0 ) { ldap_perror( ld, "ldap_add" ); ldap_mods_free( mods, 1 ); return( 1 ); } ...
ldap_msgfree()
The ldap_msgfree()
function frees the memory
allocated for a result by
ldap_result()
or
ldap_search_s()
. For
more information, see "Freeing the
Results of a Search."
Syntax
#include <ldap.h> int ldap_msgfree( LDAPMessage *lm );
Parameters
This function has the following parameters:
Table 18-87 - ldap_msgfree() function parameters
lm |
ID of the result to be freed from memory. |
Returns
One of the following values:
-
If successful, returns the type of result freed. Possible types of
results are listed below.
Table 18-88 - ldap_msgfree() return codes
LDAP_RES_BIND
Results from an LDAP bind operation. LDAP_RES_SEARCH_ENTRY
Entry returned by an LDAP search operation. LDAP_RES_SEARCH_RESULT
Results from an LDAP search operation. LDAP_RES_MODIFY
Results from an LDAP modify operation. LDAP_RES_ADD
Results from an LDAP add operation. LDAP_RES_DELETE
Results from an LDAP delete operation. LDAP_RES_MODRDN, LDAP_RES_RENAME
Results from an LDAP modify DN operation. LDAP_RES_COMPARE
Results from an LDAP compare operation. LDAP_RES_SEARCH_REFERENCE
Search reference returned by an LDAP search operation. LDAP_RES_EXTENDED
Results from an LDAP extended operation. LDAP_RES_ANY
Results from any asynchronous LDAP operation. - If unsuccessful, returns the LDAP error code for the operation. (See Chapter 19 "Result Codes" for a complete listing.)
- If the operation times out, returns
LDAP_SUCCESS
.
Example
The following example frees the results of a search.
Code Example 18-35 - ldap_msgfree() code example
#include <ldap.h> ... LDAP *ld; LDAPMessage *result; char *my_searchbase = "dc=example,dc=com"; char *my_filter = "(sn=Jensen)"; char *get_attr[] = { "cn", "mail", NULL }; ... /* Search the directory */ if ( ldap_search_s( ld, my_searchbase, LDAP_SCOPE_SUBTREE, my_filter, get_attr, 0, &result ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldap_search_s" ); return( 1 ); } ... /* Free the results when done */ ldap_msgfree( result ); ...
See Also:
ldap_result(),
ldap_search_s().
ldap_msgid()
The ldap_msgid()
function determines the message ID
of a result obtained by calling
ldap_result()
or
ldap_search_s()
.
Syntax
#include <ldap.h> int ldap_msgid( LDAPMessage *lm );
Parameters
This function has the following parameters:
Table 18-89 - ldap_msgid() function parameters
lm |
ID of the result to check. |
Returns
One of the following values:
- The message ID if successful.
-1
if unsuccessful.
Example
The following example prints the message ID from the result obtained from a synchronous LDAP search operation.
Code Example 18-36 - ldap_msgid() code example
#include <ldap.h> ... LDAP *ld; LDAPMessage *result; ... /* Perform a search */ if ( ldap_search_s( ld, MY_SEARCHBASE, LDAP_SCOPE_SUBTREE, MY_FILTER, NULL, 0, &result ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldap_search_s" ); return( 1 ); } /* Get and print the message ID */ if ( ldap_msgid( result ) != -1 ) { printf( "Message ID: %d\n" ); } else { printf( "An error occurred.\n" ); } ...
See Also:
ldap_msgtype(),
ldap_result(),
ldap_search_s().
ldap_msgtype()
The ldap_msgtype()
function determines the type of
result obtained by calling
ldap_result()
or
ldap_search_s()
.
Syntax
#include <ldap.h> int ldap_msgtype( LDAPMessage *lm );
Parameters
This function has the following parameters:
Table 18-90 - ldap_msgtype() function parameters
lm |
ID of the result to check. |
Returns
One of the following values:
-
LDAP_RES_BIND
indicates that theLDAPMessage
structure contains the result of an LDAP bind operation. -
LDAP_RES_SEARCH_ENTRY
indicates that theLDAPMessage
structure contains an entry found during an LDAP search operation. -
LDAP_RES_SEARCH_REFERENCE
indicates that theLDAPMessage
structure contains an LDAPv3 search reference (a referral to another LDAP server) found during an LDAP search operation. -
LDAP_RES_SEARCH_RESULT
indicates that theLDAPMessage
structure contains the result of an LDAP search operation. -
LDAP_RES_MODIFY
ndicates that theLDAPMessage
structure contains the result of an LDAP modify operation. -
LDAP_RES_ADD
indicates that theLDAPMessage
structure contains the result of an LDAP add operation. -
LDAP_RES_DELETE
indicates that theLDAPMessage
structure contains the result of an LDAP delete operation. -
LDAP_RES_MODRDN
orLDAP_RES_RENAME
indicates that theLDAPMessage
structure contains the result of an LDAP modify DN operation. -
LDAP_RES_COMPARE
indicates that theLDAPMessage
structure contains the result of an LDAP compare operation. -
LDAP_RES_EXTENDED
indicates that theLDAPMessage
structure contains the result of an LDAPv3 extended operation. -
-1 indicates that the
lm
argument is not a pointer to a validLDAPMessage
structure.
Example
The following example prints the message type for a result obtained from a synchronous LDAP search operation.
Code Example 18-37 - ldap_msgtype() code example
#include <ldap.h> ... LDAP *ld; LDAPMessage *result; int msgtype; ... /* Perform a search */ if ( ldap_search_s( ld, MY_SEARCHBASE, LDAP_SCOPE_SUBTREE, MY_FILTER, NULL, 0, &result ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldap_search_s" ); return( 1 ); } /* Get and print the message type */ msgtype = ldap_msgtype( result ); if ( msgtype != -1 ) { printf( "Message type: %d\n", msgtype ); } else { printf( "An error occurred.\n" ); } ...
See Also:
ldap_msgid(),
ldap_result(),
ldap_search_s().
ldap_multisort_entries()
The ldap_multisort_entries()
function sorts a chain
of entries retrieved from an LDAP search call
(ldap_search_s()
or
ldap_result()
) by a
specified set of attributes in the entries (or by DN if you don't
specify a set of attributes).
For additional information, see "Sorting the Search Results."
Syntax
#include <ldap.h> int ldap_multisort_entries( LDAP *ld, LDAPMessage **chain, char **attr, LDAP_CMP_CALLBACK *cmp );
Parameters
This function has the following parameters:
Table 18-91 - ldap_multisort_entries() function parameters
ld |
Connection handle, which is a 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 when sorting the results. If
NULL , results are sorted by distinguished name (DN).
|
cmp |
Comparison function used when sorting the values. |
Returns
One of the following values:
0
if successful.-
-1
if memory cannot be allocated by this function. (The error codeLDAP_NO_MEMORY
is set in theLDAP
structure. To get the error code, call theldap_get_lderrno()
function.) -
LDAP_PARAM_ERROR
if an invalid parameter was passed to the function
Example
The following section of code sorts entries first by the
roomNumber
attribute, then by the
telephoneNumber
attribute.
Code Example 18-38 - ldap_multisort_entries() code example
#include <stdio.h> #include <string.h> #include <ldap.h> ... LDAP *ld; LDAPMessage *result; char *my_searchbase = "dc=example,dc=com"; char *my_filter = "(sn=Jensen)"; char *attrs[3]; attrs[0] = "roomNumber"; attrs[1] = "telephoneNumber"; attrs[2] = NULL; ... /* Search the directory */ if ( ldap_search_s( ld, my_searchbase, LDAP_SCOPE_SUBTREE, my_filter, NULL, 0, &result ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldap_search_s" ); return( 1 ); } /* Sort the results, using strcasecmp */ if ( ldap_multisort_entries( ld, &result, attrs, strcasecmp ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldap_multisort_entries" ); return( 1 ); } ...
See Also:
ldap_result(),
ldap_search_s(),
ldap_sort_entries().
ldap_next_attribute()
The ldap_next_attribute()
function returns the name
of the next attribute in a entry returned by
ldap_first_entry()
or
ldap_next_entry()
.
The ldap_first_attribute()
function returns a
pointer to a BerElement
. You use this pointer with
ldap_next_attribute()
to iterate through the list of
elements. After the last call to ldap_next_element()
,
you should free the BerElement
pointer using
ldap_ber_free()
. When calling
ldap_ber_free()
, make
sure to specify that the buffer is not freed (pass 0
for the freebuf
parameter).
For more information, see "Getting Attributes from an Entry."
Syntax
#include <ldap.h> char * ldap_next_attribute( LDAP *ld, LDAPMessage *entry, BerElement *ber);
Parameters
This function has the following parameters:
Table 18-92 - ldap_next_attribute() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
entry |
Pointer to the
LDAPMessage
structure representing the entry returned by the
ldap_first_entry()
or ldap_next_entry()
function.
|
ber |
A pointer to a
BerElement allocated
to keep track of its current position. Pass this pointer to
subsequent calls to
ldap_next_attribute()
to step through the entry's attributes.
|
Returns
One of the following values:
-
If successful, returns the name of the next attribute in an entry.
When you are done using this data, you should free the memory by
calling the
ldap_memfree()
function. - If no more attributes exist in the entry, returns a NULL.
-
If unsuccessful, returns a
NULL
and sets the appropriate error code in the LDAP structure. To get the error code, call theldap_get_lderrno()
function. (See Chapter 19 "Result Codes" for a complete listing of error codes.)
Example
See the example under
ldap_first_attribute()
.
See Also:
ldap_first_attribute(),
ldap_getfirstfilter(),
ldap_next_entry().
ldap_next_entry()
Returns a pointer to the
LDAPMessage
structure
representing the next directory entry in a chain of search results.
Syntax
#include <ldap.h> LDAPMessage * ldap_next_entry( LDAP *ld, LDAPMessage *entry );
Parameters
This function has the following parameters:
Table 18-93 - ldap_next_entry() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
entry |
Pointer to an
LDAPMessage
structure in a chain of search results.
|
Returns
One of the following values:
-
If successful, returns the pointer to the next
LDAPMessage
structure of the typeLDAP_RES_SEARCH_ENTRY
in a chain of search results. -
If no more
LDAPMessage
structures of the typeLDAP_RES_SEARCH_ENTRY
are in the chain or if the function is unsuccessful, returns aNULLMSG
.
Description
The ldap_next_entry()
function returns a pointer to
the LDAPMessage
structure representing the next directory entry in a chain of search
results. Messages containing directory entries have the type
LDAP_RES_SEARCH_ENTRY
.
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
.
For more information, see "Iterating Through a Chain of Results."
See Also:
ldap_first_entry().
ldap_next_message()
Returns a pointer to the next
LDAPMessage
structure
in a chain of search results.
Syntax
#include <ldap.h> LDAPMessage * ldap_next_message( LDAP *ld, LDAPMessage *msg );
Parameters
This function has the following parameters:
Table 18-94 - ldap_next_message() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
msg |
Pointer to an
LDAPMessage
structure in a chain of search results.
|
Returns
One of the following values:
-
If successful, returns the pointer to the next
LDAPMessage
structure in a chain of search results. -
If no more
LDAPMessage
structures are in the chain or if the function is unsuccessful, returns aNULLMSG
.
Description
The ldap_next_message()
function returns a pointer
to the next LDAPMessage
structure in a chain of search results.
You can use this function in conjunction with the
ldap_first_message()
function to iterate through the chain of search results. You can
call the ldap_msgtype()
function to determine if each message contains a matching entry (a
message of the type LDAP_RES_SEARCH_ENTRY
) or a search
reference (a message of the type LDAP_RES_SEARCH_REFERENCE
).
For more information, see "Iterating Through a Chain of Results."
Example
See the examples under "Example: Searching the Directory (Synchronous)" and "Example: Searching the Directory (Asynchronous)."
See Also:
ldap_first_message().
ldap_next_reference()
Returns a pointer to the
LDAPMessage
structure
representing the next search reference in a chain of search results.
Syntax
#include <ldap.h> LDAPMessage * ldap_next_reference( LDAP *ld, LDAPMessage *ref );
Parameters
This function has the following parameters:
Table 18-95 - ldap_next_reference() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
msg |
Pointer to an
LDAPMessage
structure in a chain of search results.
|
Returns
One of the following values:
-
If successful, returns the pointer to the next
LDAPMessage
structure of the typeLDAP_RES_SEARCH_REFERENCE
in a chain of search results. -
If no more
LDAPMessage
structures of the typeLDAP_RES_SEARCH_REFERENCE
are in the chain or if the function is unsuccessful, returns aNULLMSG
.
Description
The ldap_next_reference()
function returns a pointer
to the LDAPMessage
structure representing the next search reference in a chain of
search results. Messages containing search references have the type
LDAP_RES_SEARCH_REFERENCE
.
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
.
For more information, see "Iterating Through a Chain of Results."
See Also:
ldap_first_reference().
ldap_parse_entrychange_control()
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 LDAPv3 protocol. Entry change notification is an optional LDAP server feature; it may not be supported on all LDAP servers. Call this function when interacting with LDAP servers that support this LDAPv3 extension.
Syntax
#include <ldap.h> int ldap_parse_entrychange_control( LDAP *ld, LDAPControl **ctrls, int *chgtypep, char **prevdnp, int *chgnumpresentp, long *chgnump );
Parameters
This function has the following parameters:
Table 18-96 - ldap_parse_entrychange_control() function parameters
ld |
Connection handle, which is a 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:
|
prevdnp |
Pointer to the previous DN of the entry, if the
changetypes argument is
LDAP_CHANGETYPE_MODDN . (If the
changetypes argument has a different value, this
argument is set to NULL .)
When done, you can free this by calling the
ldap_memfree()
function.
|
chgnumpresentp |
Pointer to an integer specifying whether or not to the change
number is included in the control. The parameter can have the
following possible values:
|
chgnump |
Pointer to the change number identifying the change made to the
entry, if chgnumpresentp points to a non-zero value.
|
Returns
One of the following values:
LDAP_SUCCESS
if successful.LDAP_NO_MEMORY
if memory cannot be allocated.-
LDAP_DECODING_ERROR
if an error occurred when BER-decoding the control.
Description
Call the ldap_parse_entrychange_control()
function
to parse an entry returned from a persistent search operation and
retrieve an entry change control.
Call this function after receiving an entry from a persistent
search and retrieving the controls from the entry (call
ldap_get_entry_controls()
to get the controls).
See Also:
ldap_create_persistentsearch_control(),
ldap_get_entry_controls().
ldap_parse_extended_result()
Parses the results of an LDAP extended operation and retrieves the OID and data returned by the server.
This function implements an extension to the LDAPv3 protocol. Extended operations might not be supported on all LDAP servers. Call this function when interacting with LDAP servers that support this LDAPv3 extension. See "Determining the Extended Operations Supported" to determine if the server supports extended operations.
Syntax
#include <ldap.h> int ldap_parse_extended_result( LDAP *ld, LDAPMessage *res, char **retoidp, struct berval **retdatap, int freeit );
Parameters
This function has the following parameters:
Table 18-97 - ldap_parse_extended_result() function parameters
ld |
Connection handle, which is a 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 object identifier (OID) returned by the server
after performing the extended operation.
When done, you can free this by calling the
ldap_memfree()
function.
|
retdatap |
Pointer to the pointer to a
berval structure containing the
data returned by the server after performing the extended
operation.
When done, you can free this by calling the
ber_bvfree()
function.
|
freeit |
Specifies whether or not to free the results of the operation
(the LDAPMessage structure
specified by the res argument). The parameter can
have the following possible values:
|
Returns
One of the following values, which indicates the result of parsing the server's response (this value does not apply to the LDAP extended operation itself):
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 your LDAP client does not specify that it is using the LDAPv3 protocol. Make sure that you set the version of your LDAP client to version 3 before calling this function. (For details, see "Specifying the LDAP Version of Your Client.")
Description
After you call the
ldap_extended_operation()
function and the
ldap_result()
function,
you can pass the results to the
ldap_parse_extended_result()
function.
ldap_parse_extended_result()
parses the server's
response to an extended operation.
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 theldap_get_lderrno()
function. For a list of possible result codes for an LDAP extended operation, see the result code documentation for theldap_extended_operation_s()
function.
The LDAP server must support the extended operation. The Netscape Directory Server supports a server plug-in interface that you can use to add support for extended operations to the server. For details, see the Netscape Directory Server Programmer's Guide.
See Also:
ldap_extended_operation(),
ldap_get_lderrno().
ldap_parse_reference()
Parses search references from the results received from an LDAP server.
Search references are part of the LDAPv3 protocol. When calling this function, make sure that you are working with a server that supports the LDAPv3 protocol.
Syntax
#include <ldap.h> int ldap_parse_reference( LDAP *ld, LDAPMessage *ref, char ***referralsp, LDAPControl ***serverctrlsp, int freeit );
Parameters
This function has the following parameters:
Table 18-98 - ldap_parse_reference() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
ref |
Pointer to an
LDAPMessage
structure of the type LDAP_RES_SEARCH_REFERENCE .
|
referralsp |
Pointer to an array of strings representing the referrals found
by an LDAP search operation and returned by the server (applicable
only if the LDAP operation was a search operation).
When done, you can free this by calling the
ldap_value_free()
function.
|
serverctrlsp |
Pointer to an array of
LDAPControl
structures, which represent the LDAPv3 server controls returned
by the server.
When done, you can free this by calling the
ldap_controls_free()
function.
|
freeit |
Specifies whether or not to free the results of the operation
(the LDAPMessage
structure specified by the res argument). The
parameter can have the following possible values:
|
Returns
One of the following values:
-
LDAP_SUCCESS
if the referral URLs were retrieved successfully. -
LDAP_DECODING_ERROR
if an error occurred when decoding the BER-encoded message. -
LDAP_PARAM_ERROR
if an invalid parameter was passed to the function. LDAP_NO_MEMORY
if memory cannot be allocated.
Description
The ldap_parse_reference()
function parses the
referral URLs from an
LDAPMessage
structure
of the type LDAP_RES_SEARCH_REFERENCE
.
ldap_parse_result()
Parses the results of an LDAP operation received from an LDAP server.
Syntax
#include <ldap.h> int ldap_parse_result( LDAP *ld, LDAPMessage *res, int *errcodep, char **matcheddnp, char **errmsgp, char ***referralsp, LDAPControl ***serverctrlsp, int freeit);
Parameters
This function has the following parameters:
Table 18-99 - ldap_parse_result() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
res |
Pointer to the
LDAPMessage
structure containing the results of an LDAP operation.
|
errcodep |
Pointer to the LDAP result code specifying the result of the operation. |
matcheddnp |
Pointer to a string specifying the portion of a DN that finds an
existing entry (in cases where the server cannot find the entry
specified by a DN). See "Receiving the
Portion of the DN Matching an Entry" for details.
When done, you can free this by calling the
ldap_memfree() function.
|
errmsgp |
Pointer to an additional error message string sent from the server.
When done, you can free this by calling the
ldap_memfree() function.
|
referralsp |
Pointer to an array of strings representing the referrals
returned by the server.
When done, you can free this by calling the
ldap_value_free()
function.
|
serverctrlsp |
Pointer to an array of
LDAPControl
structures, which represent the LDAPv3 server controls returned
by the server.
When done, you can free this by calling the
ldap_controls_free()
function.
|
freeit |
Specifies whether or not to automatically free the results of the
operation (the
LDAPMessage
structure specified by the res argument). The
parameter can have the following possible values:
|
Returns
One of the following values:
LDAP_SUCCESS
if the results were parsed successfully.-
LDAP_NO_RESULTS_RETURNED
if the specifiedLDAPMessage
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 theLDAPMessage
structure is part of a chain of results and the last result is not included. -
LDAP_DECODING_ERROR
if an error occurred when decoding the BER-encoded message. -
LDAP_PARAM_ERROR
if an invalid parameter was passed to the function. LDAP_NO_MEMORY
if memory cannot be allocated.
Description
The ldap_parse_result()
function parses the results
of an LDAP operation (received from an LDAP server) and retrieves
the following information:
-
The LDAP result code that indicates the result of the LDAP
operation (
errcodep
). -
An additional error message (optional) sent by the server
(
errmsgp
). -
The portion of the DN that finds an entry, if the server is unable
to find an entry from a DN that you specify
(
matcheddnp
) (see "Receiving the Portion of the DN Matching an Entry" for details). -
A set of referrals, if the server does not contain the entries
that you've specified and if the server is configured to refer
clients to other servers (
referralsp
). -
a set of server response controls that are relevant to the
operation (
serverctrlsp
).
Calling this function creates an array of
LDAPControl
structures
that you can pass to subsequent API functions (such as the
ldap_parse_sort_control()
function).
Note that this function is not intended to be used to parse
entries and search references. (Use the
ldap_msgtype()
function
to determine the type of result contained in the
LDAPMessage
structure.)
-
If the result is an entry returned as a search result, call the
ldap_first_entry()
function to retrieve the entry. -
If the result is a search reference, call the
ldap_parse_reference()
function to retrieve the reference.
Example
See the examples in the following sections:
- For an example of parsing the results of an asynchronous LDAP add operation, see "Example: Adding an Entry to the Directory (Asynchronous)."
- For an example of parsing the results of an asynchronous LDAP modify operation, see "Example: Modifying an Entry in the Directory (Asynchronous)."
- For an example of parsing the results of an asynchronous LDAP delete operation, see "Example: Deleting an Entry from the Directory (Asynchronous)."
- For an example of parsing the results of an asynchronous LDAP modify DN operation, see "Example: Renaming an Entry in the Directory (Asynchronous)."
- For an example of parsing the results of an asynchronous LDAP search operation, see "Example: Searching the Directory (Asynchronous)."
- For an example of parsing the results of an asynchronous LDAP bind operation, see "Performing an Asynchronous Authentication Operation."
See Also:
ldap_result().
ldap_parse_sasl_bind_result()
Parses the results of an LDAP SASL bind operation and retrieves
data (such as a challenge) returned by the server. This function
also gets the LDAP result code for the SASL bind operation and sets
it in the ld
structure. (You can retrieve it by
calling the
ldap_get_lderrno()
function.)
SASL authentication is part of the LDAPv3 protocol. When calling this function, make sure that you are working with a server that supports the LDAPv3 protocol.
Syntax
#include <ldap.h> int ldap_parse_sasl_bind_result( LDAP *ld, LDAPMessage *res, struct berval **servercredp, int freeit );
Parameters
This function has the following parameters:
Table 18-100 - ldap_parse_sals_bind_result() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
res |
Pointer to the
LDAPMessage
structure containing the results of an LDAP operation.
|
servercredp |
Pointer to a pointer to an
berval structure
containing any challenge or credentials returned by the server.
When done, you can free this by calling the
ber_bvfree()
function.
|
freeit |
Specifies whether or not to free the results of the operation
(the LDAPMessage
structure specified by the res argument). The
parameter can have the following possible values:
|
Returns
One of the following values, which indicates the result of parsing the server's response (this value does not apply to the SASL bind operation itself):
LDAP_SUCCESS
if the results were parsed successfully.-
LDAP_PARAM_ERROR
if an invalid parameter was passed to the function. -
LDAP_NOT_SUPPORTED
if your LDAP client does not specify that it is using the LDAPv3 protocol. Make sure that you set the version of your LDAP client to version 3 before calling this function. (For details, see "Specifying the LDAP Version of Your Client.") -
LDAP_DECODING_ERROR
if an error occurred when decoding the BER-encoded message.
Description
After you call the
ldap_sasl_bind()
function and the
ldap_result()
function, you can pass the results to the
ldap_parse_sasl_bind_result()
function parse the
results from the server.
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 theldap_get_lderrno()
function. For a list of possible result codes for an LDAP SASL bind operation, see the result code documentation for theldap_sasl_bind_s()
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.
The LDAP server must support authentication through SASL mechanisms. The Netscape Directory Server supports a server plug-in interface that you can use to add SASL support to the server. For details, see the Netscape Directory Server Programmer's Guide.
See Also:
ldap_sasl_bind(),
ldap_get_lderrno().
ldap_parse_sort_control()
Parses the result returned from a search operation that used a server control for sorting search results.
This function implements an extension to the LDAPv3 protocol. Server-side sorting is an optional LDAP server feature; it may not be supported on all LDAP servers. Call this function when interacting with LDAP servers that support this LDAPv3 extension.
Syntax
#include <ldap.h> int ldap_parse_sort_control( LDAP *ld, LDAPControl **ctrls, unsigned long *result, char **attribute );
Parameters
This function has the following parameters:
Table 18-101 - ldap_parse_sort_control() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
ctrls |
An array of controls returned by the server. You obtain these
controls by calling the
ldap_parse_result()
function on the set of results returned by the server.
|
result |
Pointer to the sort control result code retrieved by this function. |
attribute |
If the sorting operation fails, the function sets this to point
to the name of the attribute that caused the failure.
When done, you can free this by calling the
ldap_memfree()
function.
|
Returns
One of the following values:
LDAP_SUCCESS
if successful.-
LDAP_PARAM_ERROR
if an invalid parameter was passed to the function (for example, if the LDAP connection is not valid). -
LDAP_NO_MEMORY
if memory cannot be allocated to decode the control returned by the server. -
LDAP_DECODING_ERROR
if an error occurred when BER-decoding the control. -
LDAP_CONTROL_NOT_FOUND
if no control can be found in the response returned from the server.
Description
Call the ldap_parse_sort_control()
function as part
of the process of retrieving sorted search results from a server.
Call this function after receiving the results (call
ldap_result()
to get
the results) and parsing the server controls from the results (call
ldap_parse_result()
to
get the controls from the results).
See Also:
ldap_create_sort_control().
ldap_parse_virtuallist_control()
Parses the result returned from a search operation that used a server control for virtual list views.
This function implements an extension to the LDAPv3 protocol. A virtual list view is an optional LDAP server feature; it may not be supported on all LDAP servers. Call this function when interacting with LDAP servers that support this LDAPv3 extension.
Syntax
#include <ldap.h> int ldap_parse_virtuallist_control( LDAP *ld, LDAPControl **ctrls, unsigned long *target_posp, unsigned long *list_sizep, int *errcodep );
Parameters
This function has the following parameters:
Table 18-102 - ldap_parse_virtuallist_control() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
ctrls |
An array of controls returned by the server. You obtain these
controls by calling the
ldap_parse_result()
function on the set of results returned by the server.
|
target_posp |
Pointer to an unsigned long that is set by the function. The function sets this to the index or offset of the selected entry in the list of entries. |
list_sizep |
Pointer to an unsigned long that is set by the function. The function sets this to the number of entries in the total number of entries in the entire list (not just the subset). |
errcodep |
Pointer to the sort control result code retrieved by this function. |
Returns
One of the following values:
LDAP_SUCCESS
if successful.-
LDAP_PARAM_ERROR
if an invalid parameter was passed to the function (for example, if the LDAP connection is not valid). -
LDAP_NO_MEMORY
if memory cannot be allocated to decode the control returned by the server. -
LDAP_DECODING_ERROR
if an error occurred when BER-decoding the control. -
LDAP_CONTROL_NOT_FOUND
if no control can be found in the response returned from the server. -
LDAP_NOT_SUPPORTED
if your LDAP client does not specify that it is using the LDAPv3 protocol. Make sure that you set the version of your LDAP client to version 3 before calling this function. (For details, see "Specifying the LDAP Version of Your Client.")
Description
Call the ldap_parse_virtuallist_control()
function
as part of the process of retrieving a subset of entries from a list
when working with a virtual list view box.
Call this function after receiving the results (call
ldap_result()
to get
the results) and parsing the server controls from the results (call
ldap_parse_result()
to
get the controls from the results).
This function implements an extension to the LDAPv3 protocol. This control is supported by the Netscape Directory Server, version 4.0 and later. For information on determining if a server supports this or other LDAPv3 controls, see "Determining If the Server Supports LDAPv3".
For more information about this control, see "Using the Virtual List View Control."
See Also:
ldap_create_virtuallist_control().
ldap_perror()
The ldap_perror()
function prints the last LDAP
error message to standard output. The routine precedes this error
message with the text you supply as the s
parameter.
For more information, see "Printing Out
Error Messages."
Syntax
#include <ldap.h> void ldap_perror( LDAP *ld, const char *s );
Parameters
This function has the following parameters:
Table 18-103 - ldap_perror() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
s |
Text to print out before printing the error message. |
Example
The following section of code prints out an error message if the search operation cannot complete successfully.
Code Example 18-39 - ldap_perror() code example
if ( ldap_search_s( ld, my_searchbase, LDAP_SCOPE_SUBTREE, my_filter, get_attr, 0, &result ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldap_search_s" ); return( 1 ); ...
See Also:
ldap_get_lderrno(),
ldap_err2string(),
ldap_result2error(),
ldap_set_lderrno().
ldap_rename()
Changes the DN of an entry in the directory asynchronously.
Syntax
#include <ldap.h> int ldap_rename( LDAP *ld, const char *dn, const char *newrdn, const char *newparent, int deleteoldrdn, LDAPControl **serverctrls, LDAPControl **clientctrls, int *msgidp );
Parameters
This function has the following parameters:
Table 18-104 - ldap_rename() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
dn |
Distinguished name (DN) of the entry to 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 |
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.Pointer to an integer that will be set to the
message ID of the LDAP operation. To check the result of this
operation, call the
ldap_result() and
ldap_parse_result()
functions.
|
Returns
One of the following values:
LDAP_SUCCESS
if successful.LDAP_PARAM_ERROR
if any of the arguments are invalid.-
LDAP_ENCODING_ERROR
if an error occurred when BER-encoding the request. -
LDAP_SERVER_DOWN
if the LDAP server did not receive the request or if the connection to the server was lost. LDAP_NO_MEMORY
if memory cannot be allocated.-
LDAP_NOT_SUPPORTED
if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAPv3 protocol. Make sure that you set the version of your LDAP client to version 3 before calling this function. (For details, see "Specifying the LDAP Version of Your Client.")
Description
The ldap_rename()
changes the distinguished name
(DN) of an entry in the directory asynchronously and allows you to
move the entry under a different parent entry in the directory tree.
This function is a new version of the
ldap_modrdn2()
function. If you are writing a new LDAP client, you should call this
function instead of
ldap_modrdn2()
.
You can specify whether or not the old RDN is retained as an
attribute of the entry. Use the deleteoldrdn
argument
to do this. Suppose 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
ldap_rename()
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_rename_s()
instead. (For more information on asynchronous and synchronous
functions, see "Calling Synchronous and
Asynchronous Functions.")
In order to get the results of the LDAP rename operation, you
need to call the
ldap_result()
function
and the
ldap_parse_result()
function. (See "Calling Asynchronous
Functions" for details.) For a list of possible result codes for
an LDAP rename operation, see the result code documentation for the
ldap_rename_s()
function.
For more information on changing the DN of an entry, see "Changing the DN of an Entry."
Example
See the example under "Example: Renaming an Entry in the Directory (Asynchronous)."
See Also:
ldap_rename_s(),
ldap_result(),
ldap_parse_result().
ldap_rename_s()
Changes the DN of an entry in the directory synchronously.
Syntax
#include <ldap.h> int ldap_rename_s( LDAP *ld, const char *dn, const char *newrdn, const char *newparent, int deleteoldrdn, LDAPControl **serverctrls, LDAPControl **clientctrls );
Parameters
This function has the following parameters:
Table 18-105 - ldap_rename_s() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
dn |
Distinguished name (DN) of the entry to modify. |
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 |
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. |
serverctrls |
Pointer to an array of
LDAPControl
structures representing LDAP server controls that apply to this
LDAP operation. If you do not want to pass any server controls,
specify NULL for this argument.
|
clientctrls |
Pointer to an array of
LDAPControl
structures representing LDAP client controls that apply to this
LDAP operation. If you do not want to pass any client controls,
specify NULL for this argument.
|
Returns
One of the following values:
LDAP_SUCCESS
if successful.LDAP_PARAM_ERROR
if any of the arguments are invalid.-
LDAP_ENCODING_ERROR
if an error occurred when BER-encoding the request. -
LDAP_SERVER_DOWN
if the LDAP server did not receive the request or if the connection to the server was lost. LDAP_NO_MEMORY
if memory cannot be allocated.-
LDAP_LOCAL_ERROR
if an error occurred when receiving the results from the server. -
LDAP_DECODING_ERROR
if an error occurred when decoding the BER-encoded results from the server. -
LDAP_NOT_SUPPORTED
if your LDAP client does not specify that it is using the LDAPv3 protocol. Make sure that you set the version of your LDAP client to version 3 before calling this function. (For details, see "Specifying the LDAP Version of Your Client.")
The following result codes can be returned by the Directory Server when processing an LDAP modify DN request. Other LDAP servers may send these result codes under different circumstances or may send different result codes back to your LDAP client.
-
LDAP_OPERATIONS_ERROR
may be sent by the Directory Server for general errors encountered by the server when processing the request. -
LDAP_PROTOCOL_ERROR
if the modify RDN request did not comply with the LDAP protocol. The Directory Server may set this error code in the results for a variety of reasons. Some of these reasons include:- The server encountered an error when decoding your client's BER-encoded request.
-
The RDN specified by the
newrdn
argument is not a valid RDN. - Your LDAP client has not specified that it is using the LDAPv3 protocol. Make sure that you set the version of your LDAP client to version 3 before calling this function. (For details, see "Specifying the LDAP Version of Your Client.")
-
The DN specified by the
newparent
argument is not a valid DN.
-
LDAP_UNWILLING_TO_PERFORM
may be sent by the Directory Server in the following situations:- The entry to be renamed is a DSE (DSA-specific entry, where DSA is the Directory Server Agent).
-
You have specified a value for the
newparent
argument and the server does not support the ability to move an entry under another parent entry in the directory tree. - The server's database is read-only.
-
LDAP_NO_SUCH_OBJECT
may be sent by the Directory Server if the entry that you want modified does not exist and if no referral URLs are available. -
LDAP_REFERRAL
may be sent by the Directory Server if the DN specified by thedn
argument identifies an entry not handled by the current server and if referral URLs identify a different server to handle the entry. (For example, if the DN isuid=bjensen, ou=European Sales, dc=example,dc=com
, all entries underou=European Sales
might be handled by a different directory server.) -
LDAP_NOT_ALLOWED_ON_NONLEAF
may be sent by the Directory Server if the entry that you want renamed has entries beneath it in the directory tree (in other words, if this entry is a parent entry to other entries). -
LDAP_INSUFFICIENT_ACCESS
may be sent by the Directory Server if the DN that your client is authenticated as does not have the access rights to write to the entry. -
LDAP_ALREADY_EXISTS
may be sent by the Directory Server if the new DN identifies an entry that already exists in the directory (for example, if you want to change the DN of an entry touid=bjensen, ou=People, dc=example,dc=com
but an entry with that DN already exists).
Note that the Directory Server may send other result codes in addition to the codes described here (for example, the server may have loaded a custom plug-in that returns other result codes).
Description
The ldap_rename_s()
changes the DN of an entry in
the directory synchronously and allows you to move the entry under
a different parent entry in the directory tree.
This function is a new version of the
ldap_modrdn2_s()
function. If you are writing a new LDAP client, you should call this
function instead of
ldap_modrdn2_s()
.
You can specify whether or not the old RDN is retained as an
attribute of the entry. Use the deleteoldrdn
argument
to do this. Suppose 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
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()
instead.
(For more information on asynchronous and synchronous functions, see
"Calling Synchronous and Asynchronous
Functions.")
For more information on changing the DN of an entry, see "Changing the DN of an Entry."
Example
See the example under "Example: Renaming an Entry in the Directory (Synchronous)."
See Also:
ldap_rename().
ldap_result()
The function ldap_result()
waits for and returns the
result of an LDAP operation initiated by one of the asynchronous
LDAP API functions (for example,
ldap_search()
,
ldap_add()
,
ldap_modify()
).
To identify the operation that you want to check, pass the
message ID of the operation. (Asynchronous functions return a unique
message ID that you can pass to the ldap_result()
function.)
For more information, see "Getting the Server Response."
Syntax
#include <ldap.h> int ldap_result( LDAP *ld, int msgid, int all, struct timeval *timeout, LDAPMessage **result );
Parameters
This function has the following parameters:
Table 18-106 - ldap_result() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
msgid |
Message ID of the operation for which you want the results. To
check any operation, pass LDAP_RES_ANY as the value
of this parameter.
|
all |
Specifies how the results of a search are returned. This parameter
can have the following values:
|
timeout |
Specifies a maximum interval to wait for the selection to
complete. If timeout is a NULL pointer, the select
blocks indefinitely. To effect a poll, the timeout parameter
should be a non-NULL pointer, pointing to a
zero-valued timeval structure.
|
result |
Result of the operation. To interpret the results, pass this to
the LDAP parsing routines, such as
ldap_result2error() ,
ldap_parse_result() ,
and ldap_first_entry() .
|
Returns
One of the following values:
-
LDAP_RES_BIND
indicates that theLDAPMessage
structure contains the result of an LDAP bind operation. -
LDAP_RES_SEARCH_ENTRY
indicates that theLDAPMessage
structure contains an entry found during an LDAP search operation. -
LDAP_RES_SEARCH_REFERENCE
indicates that theLDAPMessage
structure contains an LDAPv3 search reference (a referral to another LDAP server) found during an LDAP search operation. -
LDAP_RES_SEARCH_RESULT
indicates that theLDAPMessage
structure contains the result of an LDAP search operation. -
LDAP_RES_MODIFY
indicates that theLDAPMessage
structure contains the result of an LDAP modify operation. -
LDAP_RES_ADD
indicates that theLDAPMessage
structure contains the result of an LDAP add operation. -
LDAP_RES_DELETE
indicates that theLDAPMessage
structure contains the result of an LDAP delete operation. -
LDAP_RES_MODDN
orLDAP_RES_RENAME
indicates that theLDAPMessage
structure contains the result of an LDAP modify DN operation. -
LDAP_RES_COMPARE
indicates that theLDAPMessage
structure contains the result of an LDAP compare operation. -
LDAP_RES_EXTENDED
indicates that theLDAPMessage
structure contains the result of an LDAPv3 extended operation. -
-1
indicates that an error occurred. The error code is set in theLDAP
structure. To get the error code, call theldap_get_lderrno()
function. (See Chapter 19 -Result Codes for a complete listing of error codes.) 0
indicates that the operation has timed out.
Example
See the examples in the following sections:
- For an example of getting the results of an asynchronous LDAP add operation, see "Example: Adding an Entry to the Directory (Asynchronous)."
- For an example of getting the results of an asynchronous LDAP modify operation, see "Example: Modifying an Entry in the Directory (Asynchronous)."
- For an example of getting the results of an asynchronous LDAP delete operation, see "Example: Deleting an Entry from the Directory (Asynchronous)."
- For an example of getting the results of an asynchronous LDAP modify DN operation, see "Example: Renaming an Entry in the Directory (Asynchronous)."
- For an example of getting the results of an asynchronous LDAP search operation, see "Example: Searching the Directory (Asynchronous)."
- For an example of getting the results of an asynchronous LDAP bind operation, see "Performing an Asynchronous Authentication Operation."
See Also:
ldap_add_ext(),
ldap_compare_ext(),
ldap_delete_ext(),
ldap_modify_ext(),
ldap_rename(),
ldap_simple_bind(),
ldap_url_search().
ldap_result2error()
This function is deprecated and is supported and documented in
this release for backward compatibility only. In its place, you should
use ldap_parse_result()
.
ldap_result2error()
returns the corresponding error
code for a result produced by the
ldap_result()
and
ldap_search_s()
functions.
Syntax
#include <ldap.h> int ldap_result2error( LDAP *ld, LDAPMessage *r, int freeit );
Parameters
This function has the following parameters:
Table 18-107 - ldap_result2error() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
r |
Pointer to the
LDAPMessage
structure representing the results returned by the
ldap_result() or
ldap_search()
function.
|
freeit |
Specifies whether or not the result should be freed after the
error code is extracted. The parameter can have the following
possible values:
|
Returns
One of the following values:
- If successful, sets the error code and other error information in the LDAP structure and returns the error code. (See Chapter 19 - Result Codes for a complete listing of error codes.)
- If unsuccessful, returns
LDAP_PARAM_ERROR
.
Example
See the example under ldap_result()
.
See Also:
ldap_parse_result(),
ldap_get_lderrno(),
ldap_err2string(),
ldap_result(),
ldap_set_lderrno().
ldap_sasl_bind()
Authenticates your client to an LDAP server using an SASL (Simple Authentication and Security Layer) mechanism. The LDAP server must support that SASL mechanism for authentication.
Syntax
#include <ldap.h> int ldap_sasl_bind( LDAP *ld, const char *dn, const char *mechanism, const struct berval *cred, LDAPControl **serverctrls, LDAPControl **clientctrls, int *msgidp );
Parameters
This function has the following parameters:
Table 18-108 - ldap_sasl_bind() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
dn |
Distinguished name (DN) of the 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
LDAP operation. If you do not want to pass any server controls,
specify NULL for this argument.
|
clientctrls |
Pointer to an array of
LDAPControl
structures representing LDAP client controls that apply to this
LDAP operation. If you do not want to pass any client controls,
specify NULL for this argument.
|
msgidp |
Pointer to an integer that will be set to the message ID of the
LDAP operation. To check the result of this operation, call
ldap_result() and
ldap_parse_sasl_bind_result()
functions.
|
Returns
One of the following values:
-
LDAP_SUCCESS
if the SASL bind request was sent successfully. -
LDAP_PARAM_ERROR
if an invalid parameter was passed to the function. -
LDAP_NOT_SUPPORTED
if your LDAP client does not specify that it is using the LDAPv3 protocol. Make sure that you set the version of your LDAP client to version 3 before calling this function. (For details, see "Specifying the LDAP Version of Your Client.") -
LDAP_ENCODING_ERROR
if an error occurred when BER-encoding the request to send to the server. LDAP_NO_MEMORY
if memory cannot be allocated.-
LDAP_SERVER_DOWN
if the LDAP server did not receive the request or if the connection to the server was lost.
Description
The ldap_sasl_bind()
function authenticates your
client to an LDAP server by using a specified SASL mechanism. The
LDAP server must support authentication through that SASL mechanism.
(The Netscape Directory Server supports a server plug-in interface
that you can use to add SASL support to the server. For details, see
the Netscape Directory Server Plug-in Programmer's Guide.)
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()
instead. (For more information on asynchronous and synchronous
functions, see "Calling Synchronous and
Asynchronous Functions.")
In order to get the results of the LDAP SASL bind operation, you
need to call the
ldap_result()
function,
the ldap_parse_sasl_bind_result()
function, and the
ldap_get_lderrno()
function. (See "Performing an Asynchronous
SASL Bind Operation" for details.) For a list of possible result
codes for an LDAP SASL bind operation, see the result code
documentation for the
ldap_sasl_bind_s()
function.
For additional information on authenticating through SASL mechanisms, see Chapter 13 - Using SASL Authentication.
See Also:
ldap_result(),
ldap_parse_sasl_bind_result(),
ldap_get_lderrno(),
ldap_sasl_bind_s().
ldap_sasl_bind_s()
Authenticates your client to an LDAP server synchronously using an SASL (Simple Authentication and Security Layer) mechanism. The LDAP server must support that SASL mechanism for authentication.
Syntax
#include <ldap.h> int ldap_sasl_bind_s( LDAP *ld, const char *dn, const char *mechanism, const struct berval *cred, LDAPControl **serverctrls, LDAPControl **clientctrls, struct berval **servercredp );
Parameters
This function has the following parameters:
Table 18-109 - ldap_sasl_bind_s() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
dn |
Distinguished name (DN) of the 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
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.
|
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_bvfree() function.
|
Returns
One of the following values:
-
LDAP_SUCCESS
if your client authenticated successfully to the server. -
LDAP_PARAM_ERROR
if an invalid parameter was passed to the function. -
LDAP_NOT_SUPPORTED
if your LDAP client does not specify that it is using the LDAPv3 protocol. Make sure that you set the version of your LDAP client to version 3 before calling this function. (For details, see "Specifying the LDAP Version of Your Client.") -
LDAP_ENCODING_ERROR
if an error occurred when BER-encoding the request to send to the server. -
LDAP_DECODING_ERROR
if an error occurred when the LDAP API library was decoding the BER-encoded results received from the server. LDAP_NO_MEMORY
if memory cannot be allocated.-
LDAP_SERVER_DOWN
if the LDAP server did not receive the request or if the connection to the server was lost. -
LDAP_LOCAL_ERROR
if an error occurred when receiving the results from the server.
The following result codes can be returned by the Directory Server when processing an LDAP SASL bind request. Other LDAP servers may send these result codes under different circumstances or may send different result codes back to your LDAP client.
-
LDAP_OPERATIONS_ERROR
may be sent by the Directory Server if the server cannot parse the LDAP controls that you are passing as arguments. -
LDAP_UNAVAILABLE_CRITICAL_EXTENSION
may be sent by the Directory Server if you specify a critical LDAP control that is not supported by the server. -
LDAP_AUTH_METHOD_NOT_SUPPORTED
can be set by the Directory Server if the SASL mechanism that you specify is not supported by the server (or if you specify an empty string as the SASL mechanism). -
LDAP_PROTOCOL_ERROR
if the bind request sent by this function did not comply with the LDAP protocol. The Directory Server may set this error code in the results for a variety of reasons. Some of these reasons include:- The server encountered an error when decoding your client's BER-encoded request.
- Your LDAP client has not specified that it is using the LDAPv3 protocol. Make sure that you set the version of your LDAP client to version 3 before sending a SASL bind request. (For details, see "Specifying the LDAP Version of Your Client.")
Note that the Netscape Directory Server may send other result
codes in addition to the codes described here (for example,
LDAP_NO_SUCH_OBJECT
if the DN in the original bind
request does not exist or LDAP_INVALID_CREDENTIALS
if
the credentials in the original bind request were incorrect). In the
Directory Server, the people deploying the server are responsible for
implementing the authentication mechanisms for SASL authentication.
Check with your server administrator for additional result codes
returned to the client.
Description
The ldap_sasl_bind_s()
function authenticates your
client to an LDAP server by using a specified SASL mechanism. The
LDAP server must support authentication through that SASL mechanism.
(The Netscape Directory Server supports a server plug-in interface
that you can use to add SASL support to the server. For details, see
the Netscape Directory Server Plug-In Programmer's Guide.)
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_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_sasl_bind()
instead. (For more information on asynchronous and synchronous
functions, see "Calling Synchronous and
Asynchronous Functions.")
For additional information on authenticating through SASL mechanisms, see Chapter 13 - Using SASL Authentication.
See Also:
ldap_sasl_bind().
ldap_search()
Searches the directory asynchronously.
Note that this is an older function that is included in the LDAP
API for backward-compatibility. If you are writing a new LDAP
client, use
ldap_search_ext()
instead.
Syntax
#include <ldap.h> int ldap_search( LDAP *ld, const char *base, int scope, const char* filter, char **attrs, int attrsonly );
Parameters
This function has the following parameters:
Table 18-110 - ldap_search() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
base |
Distinguished name (DN) of the entry that serves as the starting
point for the search. For example, setting base to
"dc=example,dc=com" restricts the search to entries
at example.com.
|
scope |
Scope of the search, which can be one of the following values:
|
filter |
String representation of the filter to apply in the search. You
can specify simple filters with the following syntax:
|
attrs |
A NULL -terminated array of attribute types to return
from entries that match filter. If you specify a
NULL , all attributes will be returned.
|
attrsonly |
Specifies whether or not attribute values are returned along with
the attribute types. This parameter can have the following values:
|
Returns
Returns the message ID of the ldap_search()
operation. To check the result of this operation, call
ldap_result()
and
ldap_result2error()
for a list of possible result codes for an LDAP search operation,
see the result code documentation for the
ldap_search_ext_s()
function.
Description
The ldap_search()
function searches the directory
asynchronously.
A newer version of this function,
ldap_search_ext()
, is
available in this release of the LDAP API. ldap_search()
(the older version of the function) is included only for
backward-compatibility. If you are writing a new LDAP client, use
ldap_search_ext()
instead of ldap_search()
.
If you want more information on ldap_search()
, refer
to the LDAP C SDK 1.0 Programmer's Guide.
Example
The following section of code searches the directory.
Code Example 18-40 - ldap_search() code example
#include "examples.h" static void do_other_work(); unsigned long global_counter = 0; int main( int argc, char **argv ) { LDAP *ld; LDAPMessage *result, *e; BerElement *ber; char *a, *dn; char **vals; int i, rc, finished, msgid; int num_entries = 0; struct timeval zerotime; zerotime.tv_sec = zerotime.tv_usec = 0L; /* get a handle to an LDAP connection */ if ( (ld = ldap_init( MY_HOST, MY_PORT )) == NULL ) { perror( "ldap_init" ); return( 1 ); } /* authenticate to the directory as nobody */ if ( ldap_simple_bind_s( ld, NULL, NULL ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldap_simple_bind_s" ); return( 1 ); } /* search for all entries with surname of Jensen */ if (( msgid = ldap_search( ld, MY_SEARCHBASE, LDAP_SCOPE_SUBTREE, MY_FILTER, NULL, 0 )) == -1 ) { ldap_perror( ld, "ldap_search" ); return( 1 ); } /* Loop, polling for results until finished */ finished = 0; while ( !finished ) { /* * Poll for results. We call ldap_result with the "all" parameter * set to zero. This causes ldap_result() to return exactly one * entry if at least one entry is available. This allows us to * display the entries as they are received. */ result = NULL; rc = ldap_result( ld, msgid, 0, &zerotime, &result ); switch ( rc ) { case -1: /* some error occurred */ ldap_perror( ld, "ldap_result" ); return( 1 ); case 0: /* Timeout was exceeded. No entries are ready for retrieval. */ if ( result != NULL ) { ldap_msgfree( result ); } break; default: /* * Either an entry is ready for retrieval, or all entries have * been retrieved. */ if (( e = ldap_first_entry( ld, result )) == NULL ) { /* All done */ finished = 1; if ( result != NULL ) { ldap_msgfree( result ); } continue; } /* for each entry print out name + all attrs and values */ num_entries++; if (( dn = ldap_get_dn( ld, e )) != NULL ) { printf( "dn: %s\n", dn ); ldap_memfree( dn ); } for ( a = ldap_first_attribute( ld, e, &ber ); a != NULL; a = ldap_next_attribute( ld, e, ber ) ) { if (( vals = ldap_get_values( ld, e, a )) != NULL ) { for ( i = 0; vals[ i ] != NULL; i++ ) { printf( "%s: %s\n", a, vals[ i ] ); } ldap_value_free( vals ); } ldap_memfree( a ); } if ( ber != NULL ) { ldap_ber_free( ber, 0 ); } printf( "\n" ); ldap_msgfree( result ); } /* Do other work here while you are waiting... */ do_other_work(); } /* All done. Print a summary. */ printf( "%d entries retrieved. I counted to %ld " "while waiting.\n", num_entries, global_counter ); ldap_unbind( ld ); return( 0 ); } /* * Perform other work while polling for results. */ static void do_other_work() { global_counter++; }
See Also:
ldap_search_ext().
ldap_search_ext()
Searches the directory asynchronously.
Syntax
#include <ldap.h> int ldap_search_ext( LDAP *ld, const char *base, int scope, const char *filter, char **attrs, int attrsonly, LDAPControl **serverctrls, LDAPControl **clientctrls, struct timeval *timeoutp, int sizelimit, int *msgidp );
Parameters
This function has the following parameters:
Table 18-111 - ldap_sort_ext() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
base |
Distinguished name (DN) of the entry that serves as the starting
point for the search. For example, setting base to
"dc=example,dc=com" restricts the search to entries
at example.com .
|
scope |
Scope of the search, which can be one of the following values:
|
>filter |
String representation of the filter to apply in the search. You
can specify simple filters with the following syntax:
|
attrs |
A NULL -terminated array of attribute types to return
from entries that match filter. If you specify a
NULL , all attributes will be returned.
|
attrsonly |
Specifies whether or not attribute values are returned along with
the attribute types. This parameter can have the following values:
|
serverctrls |
Pointer to an array of
LDAPControl
structures representing LDAP server controls that apply to this
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.
|
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. To check the result of this operation, call the
ldap_result() and
ldap_parse_result()
functions.
|
Returns
One of the following values:
LDAP_SUCCESS
if successful.LDAP_PARAM_ERROR
if any of the arguments are invalid.-
LDAP_ENCODING_ERROR
if an error occurred when BER-encoding the request. -
LDAP_SERVER_DOWN
if the LDAP server did not receive the request or if the connection to the server was lost. LDAP_NO_MEMORY
if memory cannot be allocated.-
LDAP_NOT_SUPPORTED
if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAPv3 protocol. Make sure that you set the version of your LDAP client to version 3 before calling this function. (For details, see "Specifying the LDAP Version of Your Client.")
Description
The ldap_search_ext()
function searches the directory
for matching entries asynchronously.
This function is a new version of the
ldap_search()
function.
If you are writing a new LDAP client, you should call this function
instead of ldap_search()
.
You can 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.)
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()
instead. (For more information on asynchronous and synchronous
functions, see "Calling
Synchronous and Asynchronous Functions.")
In order to get the results of the LDAP search operation, you
need to call the
ldap_result()
function
and the ldap_parse_result()
function. (See "Getting
Results Asynchronously" for details.) For a list of possible result
codes for an LDAP search operation, see the result code documentation
for the ldap_search_ext_s()
function.
For more information on searching the directory, see Chapter 6 - Searching the Directory.
Example
See the example under "Example: Searching the Directory (Asynchronous)."
See Also:
ldap_search_ext_s(),
ldap_result(),
ldap_parse_result().
ldap_search_ext_s()
Searches the directory synchronously.
Syntax
#include <ldap.h> int ldap_search_ext_s( LDAP *ld, const char *base, int scope, const char *filter, char **attrs, int attrsonly, LDAPControl **serverctrls, LDAPControl **clientctrls, struct timeval *timeoutp, int sizelimit, LDAPMessage **res );
Parameters
This function has the following parameters:
Table 18-112 - ldap_search_ext_s() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
base |
Distinguished name (DN) of the entry that serves as the starting
point for the search. For example, setting base to
"dc=example,dc=com" restricts the search to entries
at example.com .
|
>scope |
Scope of the search, which can be one of the following values:
|
filter |
String representation of the filter to apply in the search. You
can specify simple filters with the following syntax:
|
attrs |
A NULL -terminated array of attribute types to return
from entries that match filter. If you specify a NULL ,
all attributes will be returned.
|
attrsonly |
Specifies whether or not attribute values are returned along with
the attribute types. This parameter can have the following values:
|
serverctrls |
Pointer to an array of
LDAPControl
structures representing LDAP server controls that apply to this
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.
|
timeoutp |
Pointer to a timeval structure specifying the maximum
time to wait for the results of the search.
|
sizelimit |
Maximum number of results to return in the search. |
res |
Results of the search (when the call is completed). |
Returns
One of the following values:
LDAP_SUCCESS
if successful.LDAP_PARAM_ERROR
if any of the arguments are invalid.-
LDAP_ENCODING_ERROR
if an error occurred when BER-encoding the request. -
LDAP_SERVER_DOWN
if the LDAP server did not receive the request or if the connection to the server was lost. LDAP_NO_MEMORY
if memory cannot be allocated.-
LDAP_LOCAL_ERROR
if an error occurred when receiving the results from the server. -
LDAP_DECODING_ERROR
if an error occurred when decoding the BER-encoded results from the server. -
LDAP_NOT_SUPPORTED
if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAPv3 protocol. Make sure that you set the version of your LDAP client to version 3 before calling this function. (For details, see "Specifying the LDAP Version of Your Client.") -
LDAP_FILTER_ERROR
if an error occurred when parsing and BER-encoding the search filter specified by thefilter
argument. -
LDAP_TIMEOUT
if the search exceeded the time specified by thetimeoutp
argument.
The following result codes can be returned by the Netscape Directory Server when processing an LDAP search request. Other LDAP servers may send these result codes under different circumstances or may send different result codes back to your LDAP client.
-
LDAP_OPERATIONS_ERROR
may be sent by the Directory Server for general errors encountered by the server when processing the request. -
LDAP_PROTOCOL_ERROR
if the search request did not comply with the LDAP protocol. The Directory Server may set this error code in the results for a variety of reasons. Some of these reasons include:- The server encountered an error when decoding your client's BER-encoded request.
- The search request received by the server specifies an unknown search scope or filter type.
- Your LDAP client attempts to use an extensible search filter and has not specified that it is using the LDAPv3 protocol. Make sure that you set the version of your LDAP client to version 3 before sending the request. (For details, see "Specifying the LDAP Version of Your Client.")
- The server encountered an error when attempting to sort the search results or when attempting to send sorted results.
-
LDAP_INVALID_SYNTAX
may be sent by the Directory Server if your LDAP client specified a substring filter containing no value for comparison. -
LDAP_NO_SUCH_OBJECT
may be sent by the Directory Server if the entry specified by thebase
argument does not exist and if no referral URLs are available. -
LDAP_REFERRAL
may be sent by the Directory Server if the entry specified by thebase
argument is not handled by the current server and if referral URLs identify a different server to handle the entry. (For example, if the DN isuid=bjensen, ou=European Sales, dc=example,dc=com
, all entries underou=European Sales
might be handled by a different directory server.) -
LDAP_TIMELIMIT_EXCEEDED
may be sent by the Directory Server if the search exceeded the maximum time specified by thetimeoutp
argument. -
LDAP_SIZELIMIT_EXCEEDED
may be sent by the Directory Server if the search found more results than the maximum number of results specified by thesizelimit
argument. -
LDAP_ADMINLIMIT_EXCEEDED
may be sent by the Directory Server if the search found more results than the limit specified by thelookthroughlimit
directive in theslapd.conf
configuration file. (If not specified in the configuration file, the limit is 5000.)
Note that the Directory Server may send other result codes in addition to the codes described here (for example, the server may have loaded a custom plug-in that returns other result codes).
Description
The ldap_search_ext_s()
searches the directory for
matching entries synchronously.
You can 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.)
This function is a new version of the
ldap_search_s()
function. If you are writing a new LDAP client, you should call this
function instead of
ldap_search_s()
.
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()
instead. (For more information on asynchronous and synchronous
functions, see "Calling Synchronous and
Asynchronous Functions.")
For more information on searching the directory, see Chapter 6 - Searching the Directory.
Example
See the example under "Example: Searching the Directory (Synchronous)."
See Also:
ldap_search_ext().
ldap_search_s()
Searches the directory synchronously.
Note that this is an older function that is included in the LDAP
API for backward-compatibility. If you are writing a new LDAP client,
use ldap_search_ext_s()
instead.
Syntax
#include <ldap.h> int ldap_search_s( LDAP *ld, const char *base, int scope, const char* filter, char **attrs, int attrsonly, LDAPMessage **res );
Parameters
This function has the following parameters:
Table 18-113 - ldap_search_s() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
base |
Distinguished name (DN) of the entry that serves as the starting
point for the search. For example, setting base to
"dc=example,dc=com" restricts the search to entries
at example.com .
|
scope |
Scope of the search, which can be one of the following values:
|
filter |
String representation of the filter to apply in the search. You
can specify simple filters with the following syntax:
|
attrs |
A NULL -terminated array of attribute types to return
from entries that match filter. If you specify a
NULL , all attributes will be returned.
|
attrsonly |
Specifies whether or not attribute values are returned along with
the attribute types. This parameter can have the following values:
|
res |
Results of the search (when the call is completed). |
Returns
For a list of possible result codes for an LDAP search operation,
see the result code documentation for the
ldap_search_ext_s()
function.
Description
The ldap_search_s()
function searches the directory
for matching entries.
A newer version of this function,
ldap_search_ext_s()
,
is available in this release of the LDAP API.
ldap_search_s()
(the older version of the function) is
included only for backward-compatibility. If you are writing a new
LDAP client, use
ldap_search_ext_s()
instead of ldap_search_s()
.
If you want more information on ldap_search_s()
,
refer to the LDAP C SDK 1.0 Programmer's Guide.
Example
The following section of code searches the directory for all
people whose surname (last name) is "Jensen
".
Code Example 18-41 - ldap_search_s() code example
#include "examples.h" int main( int argc, char **argv ) { LDAP *ld; LDAPMessage *result, *e; BerElement *ber; char *a, *dn; char **vals; int i; /* get a handle to an LDAP connection */ if ( (ld = ldap_init( MY_HOST, MY_PORT )) == NULL ) { perror( "ldap_init" ); return( 1 ); } /* authenticate to the directory as nobody */ if ( ldap_simple_bind_s( ld, NULL, NULL ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldap_simple_bind_s" ); return( 1 ); } /* search for all entries with surname of Jensen */ if ( ldap_search_s( ld, MY_SEARCHBASE, LDAP_SCOPE_SUBTREE, MY_FILTER, NULL, 0, &result ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldap_search_s" ); return( 1 ); } /* for each entry print out name + all attrs and values */ for ( e = ldap_first_entry( ld, result ); e != NULL; e = ldap_next_entry( ld, e ) ) { if ( (dn = ldap_get_dn( ld, e )) != NULL ) { printf( "dn: %s\n", dn ); ldap_memfree( dn ); } for ( a = ldap_first_attribute( ld, e, &ber ); a != NULL; a = ldap_next_attribute( ld, e, ber ) ) { if ((vals = ldap_get_values( ld, e, a)) != NULL ) { for ( i = 0; vals[i] != NULL; i++ ) { printf( "%s: %s\n", a, vals[i] ); } ldap_value_free( vals ); } ldap_memfree( a ); } if ( ber != NULL ) { ldap_ber_free( ber, 0 ); } printf( "\n" ); } ldap_msgfree( result ); ldap_unbind( ld ); return( 0 ); }
See Also:
ldap_search_ext_s().
ldap_search_st()
Searches the directory synchronously within a specified time limit.
Note that this is an older function that is included in the LDAP
API for backward-compatibility. If you are writing a new LDAP
client, use
ldap_search_ext_s()
instead.
Syntax
#include <ldap.h> int ldap_search_st( LDAP *ld, const char *base, int scope, const char* filter, char **attrs, int attrsonly, struct timeval *timeout, LDAPMessage **res );
Parameters
This function has the following parameters:
Table 18-114 - ldap_search_st() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
base |
Distinguished name (DN) of the entry that serves as the starting
point for the search. For example, setting base to
"dc=example,dc=com" restricts the search to entries
at example.com .
|
scope |
Scope of the search, which can be one of the following values:
|
filter |
String representation of the filter to apply in the search. You
can specify simple filters with the following syntax:
|
attrs |
A NULL -terminated array of attribute types to return
from entries that match filter. If you specify a
NULL , all attributes will be returned.
|
attrsonly |
Specifies whether or not attribute values are returned along with
the attribute types. This parameter can have the following values:
|
timeout |
Maximum time to wait for the results of the search. |
res |
Results of the search (when the call is completed). |
Returns
For a list of possible result codes for an LDAP search operation,
see the result code documentation for the
ldap_search_ext_s()
function.
Description
The ldap_search_st()
function searches the directory
for matching entries. The ldap_search_st()
function
works like the
ldap_search_s()
function and lets you set a timeout period for the search.
A newer version of this function,
ldap_search_ext_s()
,
is available in this release of the LDAP API.
ldap_search_st()
(the older version of the function) is
included only for backward-compatibility. If you are writing a new
LDAP client, use
ldap_search_ext_s()
instead of ldap_search_st()
.
If you want more information on ldap_search_st()
,
refer to the LDAP C SDK 1.0 Programmer's Guide.
See Also:
ldap_search_ext_s().
ldap_set_filter_additions()
The ldap_set_filter_additions()
function sets a
prefix to be prepended and a suffix to be appended to all filters
returned by the
ldap_getfirstfilter()
and ldap_getnextfilter()
function calls.
Syntax
#include <ldap.h> int ldap_set_filter_additions( LDAPFiltDesc *lfdp, char *prefix, char *suffix );
Parameters
This function has the following parameters:
Table 18-115 - ldap_set_filter_additions() function parameters
lfdp |
Pointer to an
LDAPFiltDesc structure.
|
prefix |
Prefix to prepend to all filters. If NULL , no prefix
is prepended.
|
suffix |
Suffix to append to all filters. If NULL , no suffix
is appended.
|
Returns
One of the following values:
LDAP_SUCCESS
if successful.- If unsuccessful, returns an LDAP error code. (See Chapter 19 - Result Codes for a complete listing.)
Example
The following section of code loads the filter configuration file
named myfilters.conf
into memory and adds the prefix
"(&(objectClass=person)
" and the suffix ")" to each
filter retrieved:
Code Example 18-42 - ldap_set_filter_additions() code example
... LDAPFiltDesc *lfdp; char *filter_file = "myfilters.conf"; char *prefix = "(&(objectClass=person)"; char *suffix = ")"; int rc; ... lfdp = ldap_init_getfilter( filter_file ); rc = ldap_set_filter_additions( ldfp, prefix, suffix ); if ( rc != LDAP_SUCCESS ) { printf( "Error setting filter prefix and suffix\n"); return( rc ); } ...
See Also:
ldap_getfirstfilter(),
ldap_getnextfilter().
ldap_setfilteraffixes()
The ldap_setfilteraffixes()
function is a deprecated
function. Use the
ldap_set_filter_additions()
function instead.
ldap_set_lderrno()
The ldap_set_lderrno()
function sets an error code
and information about an error in an
LDAP structure. You can call this
function to set error information that will be retrieved by
subsequent ldap_get_lderrno()
function calls.
For more information, see "Setting Error Codes."
Syntax
#include <ldap.h> int ldap_set_lderrno( LDAP *ld, int e, char *m, char *s );
Parameters
This function has the following parameters:
Table 18-116 - ldap_set_lderrno() function parameters
ld |
Connection handle, which is a 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, you should set this parameter to the portion of the DN that identifies an existing entry. (See "Receiving the Portion of the DN Matching an Entry" for details.) |
s |
The text of the error message that you want associated with this error code. |
Returns
One of the following values:
LDAP_SUCCESS
if successful.- If unsuccessful, returns an LDAP error code. (See Chapter 19 - Result Codes for a complete listing.)
Example
The following section of code attempts to perform an operation.
If the operation fails, the LDAP_PARAM_ERROR
error code
is placed in the LDAP
structure.
Code Example 18-43 - ldap_set_lderrno() code example
int rc; char *errmsg = "Invalid parameter"; ... if ( ldap_my_function() != LDAP_SUCCESS ) { rc = ldap_set_lderrno( ld, LDAP_PARAM_ERROR, NULL, errmsg ); if ( rc != LDAP_SUCCESS ) { printf( "Error: %d\nError code could not be set.\n", rc ); } return( rc ); } ...
See Also:
ldap_err2string(),
ldap_perror(),
ldap_result2error().
ldap_set_option()
The function ldap_set_option()
sets session
preferences in the LDAP
structure. For more information on the options you can set, see
"Setting Preferences."
Syntax
#include <ldap.h> int ldap_set_option( LDAP *ld, int option, const void *optdata );
Parameters
This function has the following parameters:
Table 18-117 - ldap_set_option() function parameters
ld |
Connection handle, which is a 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. |
optdata |
Pointer to the value of the option that you want to set. |
The option parameter can have one of the following values:
Table 18-118 - Options for ldap_set_option() function
LDAP_OPT_CLIENT_CONTROLS |
Pointer to an array of
LDAPControl
structures representing the LDAPv3 client controls you want sent
with every request by default.
The data type for the optdata parameter is
(LDAPControl ***) .
|
LDAP_OPT_DEREF |
Determines how aliases are handled during a search.
The data type for the optdata parameter is
(int *) .
optdata can be one of the following values:
|
LDAP_OPT_DNS_FN_PTRS |
Lets you use alternate DNS functions for getting the host entry
of an LDAP server.
The data type for the optdata parameter is
(struct ldap_dns_fns *) .
|
LDAP_OPT_EXTRA_THREAD_FN_PTRS |
Lets you specify the locking and semaphore functions called when
getting results from the server. (See
Chapter 16 - Writing Multithreaded
Clients for details.)
The data type for the optdata parameter is
(struct ldap_extra_thread_fns *) .
|
LDAP_OPT_IO_FN_PTRS |
Lets you use alternate communication stacks.
The data type for the optdata parameter is
(struct ldap_io_fns *) .
|
LDAP_OPT_MEMALLOC_FNS_PTRS |
Lets you replace the standard function used for memory management
(for example malloc() , calloc() ,
realloc() , and free() ) with your own
function. See the prototype for the ldap_memalloc_fns
callback structure for the details on the structure that you can set.
|
LDAP_OPT_PROTOCOL_VERSION |
Version of the protocol supported by your client.
The data type for the optdata parameter is
(int *) .
You can specify either LDAP_VERSION2 or
LDAP_VERSION3 . If no version is set, the default is
LDAP_VERSION2 .
In order to use LDAPv3 features, you need to set the protocol
version to LDAP_VERSION3 .
|
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 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.
The data type for the optdata parameter is
(int *) .
optdata can be one of the following values:
|
LDAP_OPT_REFERRALS |
Determines whether or not the client should follow referrals.
The data type for the optdata parameter is
(int *) .
optdata can be one of the following values:
|
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).
The data type for the optdata parameter is
(int *) .
By default, the maximum number of referrals that the client can
follow in a sequence is 5 for the initial connection.
Note that this limit does not apply to individual requests that
generate multiple referrals in parallel.
|
LDAP_OPT_RESTART |
If there is a fatal error on connection, this option resets the connection to an initial unconnected known state. |
LDAP_OPT_SERVER_CONTROLS |
Pointer to an array of
LDAPControl
structures representing the LDAPv3 server controls you want sent
with every request by default.
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 data type for the optdata parameter is
(int *) .
|
LDAP_OPT_SSL |
Determines whether or not SSL is enabled.
The data type for the optdata parameter is
(int *) .
optdata can be one of the following values:
|
LDAP_OPT_THREAD_FN_PTRS |
Lets you specify the thread function pointers. See
Chapter 16 - Writing Multithreaded
Clients for details.
The data type for the optdata parameter is
(struct ldap_thread_fns *) .
|
LDAP_OPT_TIMELIMIT |
Maximum number of seconds that should be spent by the server when
answering a search request.
The data type for the optdata parameter is
(int *) .
|
LDAP_X_OPT_EXTIO_FN_PTRS |
Lets you specify the extended I/O callback functions which were introduced with version 4.0 of the LDAP C SDK. |
Returns
One of the following values:
LDAP_SUCCESS
if successful.-1
if unsuccessful.
Example
The following section of code sets the maximum number of entries returned in a search.
Code Example 18-44 - ldap_set_option() code example
#include <ldap.h> ... LDAP *ld; int max_ret = 100, max_tim = 30; char *host = "ldap.example.com"; ... /* Initialize a session with the LDAP server ldap.example.com:389 */ if ( ( ld = ldap_init( host, LDAP_PORT ) ) == NULL ) { perror( "ldap_init" ); return( 1 ); } /* Set the maximum number of entries returned */ if (ldap_set_option( ld, LDAP_OPT_SIZELIMIT, &max_ret) != LDAP_SUCCESS) { ldap_perror( ld, "ldap_set_option" ); return( 1 ); } ...
See Also:
ldap_init(),
ldap_get_option().
ldap_set_rebind_proc()
Sets the rebind function, which is the function called by your client to obtain authentication credentials when following a referral.
Syntax
#include <ldap.h> void ldap_set_rebind_proc( LDAP *ld, LDAP_REBINDPROC_CALLBACK *rebindproc, void *arg );
Parameters
This function has the following parameters:
Table 18-119 - ldap_set_rebind_proc() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
rebindproc |
Name of the rebind function. |
arg |
Pointer to an additional argument that you want to pass to the rebind function. |
Description
Call ldap_set_rebind_proc()
to specify the rebind
function (the function called by the LDAP client when following a
referral to a new LDAP server). This rebind function is responsible
for obtaining the credentials used to authenticate to the new LDAP
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.)
LDAP clients that are built with the Mozilla LDAP C SDK use this procedure when following referrals (the procedure explains what the rebind function is expected to do):
- The LDAP server sends a referral back to the client.
-
The client calls the rebind function, passing
0
as thefreeit
argument. -
The rebind function sets the
dnp
,passwdp
, andauthmethodp
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
).
-
The
-
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 thefreeit
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
is0
, 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
).
arg
argument, which is a pointer to the argument specified in theldap_set_rebind_proc()
function. If successful, returnLDAP_SUCCESS
. Otherwise, return the appropriate LDAP error code. - Set
-
If
freeit
is1
, free any memory that you allocated to create the DN and credentials.
After you have defined this function, pass the function name to
ldap_set_rebind_proc()
to register your rebind function.
Note that 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 already set to LDAP_OPT_ON
by
default.
Example
The following example demonstrates how to write and register a rebind function.
Code Example 18-45 - ldap_set_rebind_proc() code example
... /* Declare your rebind function */ int rebindproc( LDAP *ld, char **dnp, char **passwdp, int *authmethodp, int freeit, void *arg ); ... int main( int argc, char **argv ) { LDAP *ld; /* Additional argument to be passed to the rebind function */ char *testarg = "cn=Directory Manager"; /* Get a handle to an LDAP connection */ if ( (ld = ldap_init( "directory.myhost.com", 389 )) == NULL ) { perror( "ldap_init" ); return( 1 ); } /* Specify the function used for reauthentication on referrals */ ldap_set_rebind_proc( ld, rebindproc, (void *)testarg ); /* Authenticate */ if ( ldap_simple_bind_s( ld, "uid=bjensen,ou=People,dc=example,dc=com", "hifalutin" ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldap_simple_bind_s" ); return( 1 ); } ... /* Your code to interact with the LDAP server */ ... } ... /* rebindproc is the rebind function responsible for providing the DN, credentials, and authentication method used for authenticating the client to other Directory Servers. The function should set the following arguments: - dnp should point to the DN that will be used for authentication. - passwdp should point to the credentials used for authentication. - authmethodp should point to the method of authentication to be used (for example, LDAP_AUTH_SIMPLE). The function should return LDAP_SUCCESS if successful or an LDAP error code if an error occurs. In order to demonstrate how the freeit argument works, this example uses strdup() to copy the DN and password. You can also just copy string pointers if the DN and password are already available as global variables. */ int LDAP_CALL LDAP_CALLBACK rebindproc( LDAP *ld, char **dnp, char **passwdp, int *authmethodp, int freeit, void *arg ) { printf( "Rebind function called.\n" ); switch ( freeit ) { /* Your client calls the rebind function with freeit==1 when it needs to free any memory you've allocated. */ case 1: printf( "\tFreeing memory.\n" ); if ( dnp && *dnp ) { free( *dnp ); } if ( passwdp && *passwdp ) { free( *passwdp ); } break; /* Your client calls the rebind function with freeit==0 when it needs to get the DN, credentials, and authentication method. */ case 0: printf( "\tGetting DN and credentials.\n" ); *dnp = strdup( "uid=username,o=OtherServerSuffix" ); *passwdp = strdup( "23skidoo" ); *authmethodp = LDAP_AUTH_SIMPLE; break; default: printf( "\tUnknown value of freeit argument: %d\n", freeit ); break; } /* If you successfully set the DN and credentials, you should return LDAP_SUCCESS. (Any other return code will stop the client from automatically following the referral. */ return LDAP_SUCCESS; }
See Also:
ldap_simple_bind(),
ldap_simple_bind_s().
ldap_simple_bind()
Asynchronously authenticates your client to the LDAP server using a DN and a password.
Syntax
#include <ldap.h> int ldap_simple_bind(LDAP *ld, const char *who, const char *passwd);
Parameters
This function has the following parameters:
Table 18-120 - ldap_simple_bind() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
who |
Distinguished name (DN) of the user who wants to authenticate.
For anonymous authentication, set this or the passwd
argument to NULL .
|
passwd |
Password of the user who wants to authenticate. For anonymous
authentication, set this or the who argument to
NULL .
|
Returns
Returns the message ID of the ldap_simple_bind()
operation. To check the result of this operation, call
ldap_result()
and
ldap_result2error()
.
Description
The ldap_simple_bind()
function authenticates to the
LDAP server. The function 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()
instead. (For more information on asynchronous and synchronous
functions, see "Calling Synchronous and
Asynchronous Functions.")
Note that if you specify a DN but no password, your client will
bind to the server anonymously. If you want a NULL
password to be rejected as an incorrect password, you need to write
code to perform the check before you call the
ldap_simple_bind()
function.
For additional information on authenticating to the LDAP server, see "Binding and Authenticating to an LDAP Server."
Example
The following section of code calls ldap_simple_bind()
to authenticate the user "Barbara Jensen" to the directory.
Code Example 18-46 - ldap_simple_bind() code example
#include <ldap.h> ... LDAP *ld; char *host = "ldap.example.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 */ if ( ( ld = ldap_init( host, LDAP_PORT ) ) == NULL ) { perror( "ldap_init" ); return( 1 ); } /* Attempt to bind with the LDAP server */ msgid = ldap_simple_bind( ld, dn, pw ); /* Initialize the value returned by ldap_result() */ rc = 0; /* While the operation is still running, do this: */ while ( rc == 0 ) { ... /* do other work while waiting */... /* Check the status of the LDAP operation */ rc = ldap_result( ld, msgid, NULL, &zerotime, &result ); switch( rc ) { /* If -1 was returned, an error occurred */ case -1: ldap_perror( ld, "Error in results: " ); return( 1 ); /* If 0 was returned, the operation is still in progress */ case 0: continue; /* If any other value is returned, assume we are done */ default: /* Check if the "bind" operation was successful */ if ( ldap_result2error( result ) != LDAP_SUCCESS ) { ldap_perror( ld, "Error binding to server: " ); return( 1 ); } } } ...
See Also:
ldap_simple_bind_s().
ldap_simple_bind_s()
Synchronously authenticates your client to the LDAP server using a DN and a password.
Syntax
#include <ldap.h> int ldap_simple_bind_s( LDAP *ld, const char *who, const char *passwd );
Parameters
This function has the following parameters:
Table 18-121 - ldap_simple_bind_s() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
who |
Distinguished name (DN) of the user who wants to authenticate.
For anonymous authentication, set this or the passwd
argument to NULL .
|
passwd |
Password of the user who wants to authenticate. For anonymous
authentication, set this or the who argument to
NULL .
|
Returns
One of the following values:
LDAP_SUCCESS
if successful.LDAP_PARAM_ERROR
if any of the arguments are invalid.-
LDAP_ENCODING_ERROR
if an error occurred when BER-encoding the request. -
LDAP_SERVER_DOWN
if the LDAP server did not receive the request or if the connection to the server was lost. LDAP_NO_MEMORY
if memory cannot be allocated.-
LDAP_LOCAL_ERROR
if an error occurred when receiving the results from the server. -
LDAP_DECODING_ERROR
if an error occurred when decoding the BER-encoded results from the server. -
LDAP_NOT_SUPPORTED
if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAPv3 protocol. Make sure that you set the version of your LDAP client to version 3 before calling this function. For details, see "Specifying the LDAP Version of Your Client."
The following result codes can be returned by the Netscape Directory Server when processing an LDAP search request. Other LDAP servers may send these result codes under different circumstances or may send different result codes back to your LDAP client.
-
LDAP_OPERATIONS_ERROR
may be sent by the Directory Server for general errors encountered by the server when processing the request. -
LDAP_PROTOCOL_ERROR
if the search request did not comply with the LDAP protocol. The Directory Server may set this error code in the results for a variety of reasons. Some of these reasons include:- The server encountered an error when decoding your client's BER-encoded request.
- The search request received by the server specifies an unknown search scope or filter type.
- Your LDAP client attempts to use an extensible search filter and has not specified that it is using the LDAPv3 protocol. Make sure that you set the version of your LDAP client to version 3 before sending the request. For details, see "Specifying the LDAP Version of Your Client."
- The server encountered an error when attempting to sort the search results or when attempting to send sorted results.
-
LDAP_INVALID_SYNTAX
may be sent by the Directory Server if your LDAP client specified a substring filter containing no value for comparison. -
LDAP_NO_SUCH_OBJECT
may be sent by the Directory Server if the entry specified by thebase
argument does not exist and if no referral URLs are available. -
LDAP_REFERRAL
may be sent by the Directory Server if the entry specified by thebase
argument is not handled by the current server and if referral URLs identify a different server to handle the entry. (For example, if the DN isuid=bjensen, ou=European Sales, dc=example,dc=com
, all entries underou=European Sales
might be handled by a different directory server.) -
LDAP_TIMELIMIT_EXCEEDED
may be sent by the Directory Server if the search exceeded the maximum time specified by thetimeoutp
argument. -
LDAP_SIZELIMIT_EXCEEDED
may be sent by the Directory Server if the search found more results than the maximum number of results specified by thesizelimit
argument. -
LDAP_ADMINLIMIT_EXCEEDED
may be sent by the Directory Server if the search found more results than the limit specified by thelookthroughlimit
directive in theslapd.conf
configuration file. (If not specified in the configuration file, the limit is 5000.)
Note that the Netscape Directory Server may send other result codes in addition to the codes described here (for example, the server may have loaded a custom plug-in that returns other result codes).
Description
The ldap_simple_bind_s()
function authenticates to
the LDAP server. The function 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. (For more information on asynchronous and synchronous
functions, see "Calling Synchronous and
Asynchronous Functions.")
Note that if you specify a DN but no password, your client will
bind to the server anonymously. If you want a NULL
password to be rejected as an incorrect password, you need to write
code to perform the check before you call the
ldap_simple_bind_s()
function.
For additional information on authenticating to the LDAP server, see "Binding and Authenticating to an LDAP Server."
Example
The following section of code uses the synchronous
ldap_simple_bind_s()
function to authenticate to the
directory as the user "Barbara Jensen
".
Code Example 18-47 - ldap_simple_bind_s() code example
#include <ldap.h> ... LDAP *ld; char *host = "ldap.example.com"; char *dn = "uid=bjensen, ou=People, dc=example,dc=com"; char *pw = "hifalutin"; ... /* Initialize a session with the LDAP server ldap.example.com:389 */ if ( ( ld = ldap_init( host, LDAP_PORT ) ) == NULL ) { perror( "ldap_init" ); return( 1 ); } /* Attempt to bind with the LDAP server */ if ( ldap_simple_bind_s( ld, dn, pw ) != LDAP_SUCCESS ) { ldap_perror( ld, "Authentication failed: " ); return( 1 ); } ...
See Also:
ldap_simple_bind().
ldap_sort_entries()
The ldap_sort_entries()
function sorts a chain of
entries retrieved from an LDAP search call
(ldap_search_s()
or
ldap_result()
) either
by distinguished name (DN) or by a specified attribute in the entries.
For additional information, see "Sorting the Search Results."
Syntax
#include <ldap.h> int ldap_sort_entries( LDAP *ld, LDAPMessage *chain, char *attr, LDAP_CMP_CALLBACK *cmp );
Parameters
This function has the following parameters:
Table 18-122 - ldap_sort_entires() function parameters
ld |
Connection handle, which is a 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
distinguished name instead of by attribute, use NULL .
|
cmp |
Comparison function used when sorting the values. For details, see "Sorting Entries by an Attribute." |
Returns
One of the following values:
LDAP_SUCCESS
if successful.-
If unsuccessful, returns a
NULL
and sets the appropriate error code in the LDAP structure. To get the error code, callldap_get_lderrno()
. (See Chapter 19 - Result Codes for a complete listing of error codes.)
Example
The following section of code sorts entries by the
roomNumber
attribute.
Code Example 18-48 - ldap_sort_entries() code example
#include <string.h> #include <ldap.h> LDAP *ld; LDAPMessage *result; char *my_searchbase = "dc=example,dc=com"; char *my_filter = "(sn=Jensen)"; char *sortby = "roomNumber"; ... /* Search the directory */ if ( ldap_search_s( ld, my_searchbase, LDAP_SCOPE_SUBTREE, my_filter, NULL, 0, &result ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldap_search_s" ); return( 1 ); } /* Sort the results by room number, using strcasecmp */ if ( ldap_sort_entries( ld, &result, sortby, strcasecmp ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldap_sort_entries" ); return( 1 ); } ...
See Also:
ldap_multisort_entries(),
ldap_result(),
ldap_search_s().
ldap_sort_values()
The ldap_sort_values()
function sorts an array of
values retrieved from an
ldap_get_values()
call.
For additional information, see "Sorting the Search Results."
Syntax
#include <ldap.h> int ldap_sort_values( LDAP *ld, char **vals, LDAP_VALCMP_CALLBACK cmp );
Parameters
This function has the following parameters:
Table 18-123 - ldap_sort_values() function parameters
ld |
Connection handle, which is a 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_values() function, the comparison
function must pass (char **) parameters. Because of
this, you need to use the
ldap_sort_strcasecmp()
function, rather than a function like strcasecmp() .
|
Returns
One of the following values:
LDAP_SUCCESS
if successful.- If unsuccessful, returns an LDAP error code. (See Chapter 19 "Result Codes" for a complete listing of error codes.)
Example
The following section of code sorts the values of attributes before printing them.
Code Example 18-49 - ldap_sort_values() code example
#include <string.h> #include <ldap.h> ... LDAP *ld; LDAPMessage *result, *e; BerElement *ber; char *a, *dn; char **vals; int i; char *my_searchbase = "dc=example,dc=com"; char *my_filter = "(sn=Jensen)"; ... if ( ( vals = ldap_get_values( ld, e, a ) ) != NULL ) { /* Sort the values of the attribute */ if ( ldap_sort_values( ld, vals, strcasecmp ) ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldap_sort_values" ); return( 1 ); } /* Print the values of the attribute */ for ( i = 0; vals[i] != NULL; i++ ) { printf( "%s: %s\n", a, vals[i] ); } /* Free the values from memory */ ldap_value_free( vals ); } ...
See Also:
ldap_get_values(),
ldap_sort_strcasecmp().
ldap_sort_strcasecmp()
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_values()
,
call this function to compare the attribute values.
Syntax
#include <ldap.h> int ldap_sort_strcasecmp( const char **a, const char **b );
Parameters
This function has the following parameters:
Table 18-124 - ldap_sort_strcasecmp() function parameters
a |
Pointer to first string to compare |
b |
Pointer to second string to compare |
Returns
One of the following values:
-
If
a
is greater thanb
, returns a value greater than 0. - If
a
is equal tob
, returns0
. -
If
a
is less thanb
, returns a value less than 0.
See Also:
ldap_sort_values().
ldap_unbind()
The ldap_unbind()
function unbinds from the
directory, terminates the current association, and frees the
resources contained in the
LDAP
structure.
The ldap_unbind()
routine works the same as
ldap_unbind_s()
; both
routines are synchronous. This function is provided so that the
function ldap_simple_bind()
has a corresponding unbind
function. For additional information, see
"Closing the Connection to the Server."
Syntax
#include <ldap.h> int ldap_unbind( LDAP *ld );
Parameters
This function has the following parameters:
Table 18-125 - ldap_unbind() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server. |
Returns
For a list of possible result codes for an LDAP unbind operation,
see the result code documentation for the
ldap_unbind_s()
function.
Example
The following code closes the current connection with the LDAP server:
Code Example 18-50 - ldap_unbind() code example
... LDAP *ld; ... /* After completing your LDAP operations with the server, close the connection. */ if ( ldap_unbind( ld ) != LDAP_SUCCESS ) { ldap_perror( ld, "Error while unbinding from the directory" ); return( 1 ); } ...
See Also:
ldap_unbind_s(),
ldap_unbind_ext().
ldap_unbind_s()
The ldap_unbind_s()
function unbinds from the
directory, terminates the current association, and frees the
resources contained in the
LDAP
structure.
Syntax
#include <ldap.h> int ldap_unbind_s( LDAP *ld );
Parameters
This function has the following parameters:
Table 18-126 - ldap_unbind_s() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
Returns
One of the following values:
LDAP_SUCCESS
if successful.-
LDAP_ENCODING_ERROR
if an error occurred when BER-encoding the request. -
LDAP_SERVER_DOWN
if the LDAP server did not receive the request or if the connection to the server was lost. LDAP_NO_MEMORY
if memory cannot be allocated.
Description
The three unbind functions (ldap_unbind_ext()
,
ldap_unbind()
and ldap_unbind_s())
all
work synchronously in the sense that they send an unbind request to
the server, close all open connections associated with the LDAP
session handle, and dispose of all resources associated with the
session handle before returning.
Note that 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 LDAP API calls using
ld
. For additional information, see
"Closing the Connection to the Server."
Example
The following code closes the current connection with the LDAP server:
Code Example 18-51 - ldap_unbind_s() code example
... LDAP *ld; ... /* After completing your LDAP operations with the server, close the connection. */ if ( ldap_unbind_s( ld ) != LDAP_SUCCESS ) { ldap_perror( ld, "Error while unbinding from the directory" ); return( 1 ); } ...
See Also:
ldap_unbind(),
ldap_unbind_ext().
ldap_unbind_ext()
The ldap_unbind_ext()
function unbinds from the
directory, terminates the current association, and frees the
resources contained in the
LDAP
structure.
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 with your
unbind request.
Syntax
#include <ldap.h> int ldap_unbind_ext( LDAP *ld, LDAPControl **serverctrls, LDAPControl **clientctrls );
Parameters
This function has the following parameters:
Table 18-127 - ldap_unbind_ext() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
serverctrls |
List of LDAP server controls. |
clientctrls |
List of client controls. |
Returns
One of the following values:
LDAP_SUCCESS
if successful.-
LDAP_ENCODING_ERROR
if an error occurred when BER-encoding the request. -
LDAP_SERVER_DOWN
if the LDAP server did not receive the request or if the connection to the server was lost. LDAP_NO_MEMORY
if memory cannot be allocated.-
LDAP_NOT_SUPPORTED
if controls are included in your request (for example, as a session preference) and your LDAP client does not specify that it is using the LDAPv3 protocol. Make sure that you set the version of your LDAP client to version 3 before calling this function. (For details, see "Specifying the LDAP Version of Your Client.").
Description
The three unbind functions (ldap_unbind_ext()
,
ldap_unbind()
and ldap_unbind_s())
all
work synchronously in the sense that they send an unbind request to
the server, close all open connections associated with the LDAP
session handle, and dispose of all resources associated with the
session handle before returning.
Note that 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 LDAP API calls using
ld
. For additional information, see
"Closing the Connection to the Server."
Example
The following code closes the current connection with the LDAP server:
See Also:
ldap_unbind(),
ldap_unbind_s().
ldap_url_parse()
The ldap_url_parse()
function parses an LDAP URL
into its components. For more information, see
"Getting the Components of an LDAP URL."
Syntax
#include <ldap.h> int ldap_url_parse( const char *url, LDAPURLDesc **ludpp );
Parameters
This function has the following parameters:
Table 18-128 - ldap_url_parse() function parameters
url |
The URL that you want to check. |
ludpp |
Pointer to a structure containing the components of the URL. |
Returns
One of the following values:
LDAP_SUCCESS
if successful.-
LDAP_URL_ERR_NOTLDAP
if the URL does not begin with the "ldap://
" or "ldaps://
" prefix. -
LDAP_URL_ERR_NODN
if the URL missing trailing slash after host or port. -
LDAP_URL_ERR_BADSCOPE
if the scope within the URL is invalid. -
LDAP_URL_ERR_MEM
if not enough free memory is available for this operation. -
LDAP_URL_ERR_PARAM
if an invalid argument was passed to the function.
Example
The following section of code parses an LDAP URL and prints out each component of the URL.
Code Example 18-52 - ldap_url_parse() code example
#include <ldap.h> ... char *my_url = "ldap://ldap.example.com:5000/dc=example,dc=com?cn,mail,telephoneNumber?sub?(sn=Jensen)"; LDAPURLDesc *ludpp; int res, i; ... if ( ( res = ldap_url_parse( my_url, &ludpp ) ) != 0 ) { switch( res ){ case LDAP_URL_ERR_NOTLDAP: printf( "URL does not begin with \"ldap://\"\n" ); break; case LDAP_URL_ERR_NODN: printf( "URL missing trailing slash after host or port\n" ); break; case LDAP_URL_ERR_BADSCOPE: printf( "URL contains an invalid scope\n" ); break; case LDAP_URL_ERR_MEM: printf( "Not enough memory\n" ); break; default: printf( "Unknown error\n" ); } return( 1 ); } printf( "Components of the URL:\n" ); printf( "Host name: %s\n", ludpp->lud_host ); printf( "Port number: %d\n", ludpp->lud_port ); if ( ludpp->lud_dn != NULL ) { printf( "Base entry: %s\n", ludpp->lud_dn ); } else { printf( "Base entry: Root DN\n" ); } if ( ludpp->lud_attrs != NULL ) { printf( "Attributes returned: \n" ); for ( i=0; ludpp->lud_attrs[i] != NULL; i++ ) { printf( "\t%s\n", ludpp->lud_attrs[i] ); } } else { printf( "No attributes returned.\n" ); } printf( "Scope of the search: " ); switch( ludpp->lud_scope ) { case LDAP_SCOPE_BASE: printf( "base\n" ); break; case LDAP_SCOPE_ONELEVEL: printf( "one\n" ); break; case LDAP_SCOPE_SUBTREE: printf( "sub\n" ); break; default: printf( "Unknown scope\n" ); } printf( "Filter: %s\n", ludpp->lud_filter ); ...
See Also:
ldap_free_urldesc().
ldap_url_search()
The ldap_url_search()
function 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()
instead. For more information on asynchronous and synchronous
functions, see "Calling Synchronous and
Asynchronous Functions."
For more information on processing LDAP searches specified as URLs, see "Processing an LDAP URL."
Syntax
#include <ldap.h> int ldap_url_search( LDAP *ld, const char *url, int attrsonly );
Parameters
This function has the following parameters:
Table 18-129 - ldap_url_search() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
url |
LDAP URL specifying a search of the directory. |
Specifies whether or not attribute values are returned along with
the attribute types. This parameter can have the following values:
|
Returns
Returns the message ID of the ldap_url_search()
operation. To check the result of this operation, call
ldap_result()
and
ldap_result2error()
.
Example
Code Example 18-53 - ldap_url_search() code example
static void do_other_work(); unsigned long global_counter = 0;int main( int argc, char **argv ) { char *my_url = "ldap://ldap.example.com/dc=example,dc=com?cn,mail,telephoneNumber?sub?(sn=Jensen)"; LDAP *ld; LDAPMessage *result, *e; BerElement *ber; char *a, *dn; char **vals; int i, rc, finished, msgid; int num_entries = 0; struct timeval zerotime; zerotime.tv_sec = zerotime.tv_usec = 0L;/* get a handle to an LDAP connection */ if ( (ld = ldap_init( MY_HOST, MY_PORT )) == NULL ) { perror( "ldap_init" ); return( 1 ); } /* authenticate to the directory as nobody */ if ( ldap_simple_bind_s( ld, NULL, NULL ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldap_simple_bind_s" ); return( 1 ); } /* search for all entries with surname of Jensen */ if (( msgid = ldap_url_search( ld, my_url, 0 )) == -1 ) { ldap_perror( ld, "ldap_url_search" ); return( 1 ); }/* Loop, polling for results until finished */ finished = 0; while ( !finished ) { /* * Poll for results. We call ldap_result with the "all" parameter * set to zero. This causes ldap_result() to return exactly one * entry if at least one entry is available. This allows us to * display the entries as they are received. */ result = NULL; rc = ldap_result( ld, msgid, 0, &zerotime, &result ); switch ( rc ) { case -1: /* some error occurred */ ldap_perror( ld, "ldap_result" ); return( 1 ); case 0: /* Timeout was exceeded. No entries are ready for retrieval. */ if ( result != NULL ) { ldap_msgfree( result ); } break; default: /* * Either an entry is ready for retrieval, or all entries have * been retrieved. */ if (( e = ldap_first_entry( ld, result )) == NULL ) { /* All done */ finished = 1; if ( result != NULL ) { ldap_msgfree( result ); } continue; } /* for each entry print out name + all attrs and values */ num_entries++; if (( dn = ldap_get_dn( ld, e )) != NULL ) { printf( "dn: %s\n", dn ); ldap_memfree( dn ); } for ( a = ldap_first_attribute( ld, e, &ber ); a != NULL; a = ldap_next_attribute( ld, e, ber ) ) { if (( vals = ldap_get_values( ld, e, a )) != NULL ) { for ( i = 0; vals[ i ] != NULL; i++ ) { printf( "%s: %s\n", a, vals[ i ] ); } ldap_value_free( vals ); } ldap_memfree( a ); } if ( ber != NULL ) { ldap_ber_free( ber, 0 ); } printf( "\n" ); ldap_msgfree( result ); } /* Do other work here while you are waiting... */ do_other_work(); }/* All done. Print a summary. */ printf( "%d entries retrieved. I counted to %ld " "while I was waiting.\n", num_entries, global_counter ); ldap_unbind( ld ); return( 0 ); }/* * Perform other work while polling for results. */ static void do_other_work() { global_counter++; }
See Also:
ldap_url_search_s(),
ldap_result(),
ldap_result2error().
ldap_url_search_s()
The ldap_url_search_s()
function searches the
directory 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()
instead. (For more information on asynchronous and synchronous
functions, see "Calling Synchronous and
Asynchronous Functions.")
For more information on processing LDAP searches specified as URLs, see "Processing an LDAP URL."
Syntax
#include <ldap.h> int ldap_url_search_s( LDAP *ld, const char *url, int attrsonly, LDAPMessage **res );
Parameters
This function has the following parameters:
Table 18-130 - ldap_url_search_s() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
url |
LDAP URL specifying a search of the directory. |
attrsonly |
Specifies whether or not attribute values are returned along with
the attribute types. This parameter can have the following values:
|
res |
Results of the search (when the call is completed). |
Returns
One of the following values:
LDAP_SUCCESS
if successful.- If unsuccessful, returns the LDAP error code for the operation. See Chapter 19 - Result Codes for a complete listing.
Example
The following example processes a search request from an LDAP URL.
Code Example 18-54 - ldap_url_search_s() code example
#include <ldap.h> ... LDAP *ld; LDAPMessage *result; char *my_url = "ldap://ldap.example.com/dc=example,dc=com?cn,mail,telephoneNumber?sub?(sn=Jensen)"; ... /* Process the search request in the URL */ if ( ldap_url_search_s( ld, my_url, 0, &result ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldap_url_search_s" ); return( 1 ); } ...
See Also:
ldap_search(),
ldap_search_st().
ldap_url_search_st()
The ldap_url_search_st()
function searches the
directory for matching entries, based on the contents of the URL.
This function works like
ldap_url_search_s()
and lets you specify a timeout period for the search.
For more information, see "Processing an LDAP URL."
Syntax
#include <ldap.h> int ldap_url_search_st( LDAP *ld, const char *url, int attrsonly, struct timeval *timeout, LDAPMessage **res );
Parameters
This function has the following parameters:
Table 18-131 - ldap_url_search_st() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
url |
LDAP URL specifying a search of the directory. |
attrsonly |
Specifies whether or not attribute values are returned along with
the attribute types. This parameter can have the following values:
|
timeout |
Maximum time to wait for the results of the search. |
res |
Results of the search (when the call is completed). |
Returns
One of the following values:
LDAP_SUCCESS
if successful.- If unsuccessful, returns the LDAP error code for the operation. See Chapter 19 "Result Codes" for a complete listing.
See Also:
ldap_search(),
ldap_search_s().
ldap_value_free()
The ldap_value_free()
function frees an array of
values from memory. Use the
ldap_value_free_len()
function instead of this function if the values are
berval
structures.
For additional information, see "Getting the Values of an Attribute."
Syntax
#include <ldap.h> void ldap_value_free( char **values );
Parameters
This function has the following parameters:
Table 18-132 - ldap_value_free() function parameters
values |
Array of values. |
Example
See the example under
ldap_get_values()
.
See Also:
ldap_get_values(),
ldap_value_free_len().
ldap_value_free_len()
The ldap_value_free_len()
function frees an array of
berval structures from memory. Use
the ldap_value_free()
function instead of this function if the values are string values.
For additional information, see "Getting the Values of an Attribute."
Syntax
#include <ldap.h> void ldap_value_free_len( struct berval **values );
Parameters
This function has the following parameters:
Table 18-133 - ldap_value_free_len() function parameters
values |
Array of berval
structures.
|
Example
See the example under
ldap_get_values_len()
.
See Also:
ldap_get_values(),
ldap_get_values_len().
ldap_version()
This function has been deprecated; you should use the function
ldap_get_option()
in
its place (it is documented here for backward compatibility only).
Gets version information about the LDAP C SDK libraries. The
version information is returned in an
LDAPVersion
structure.
Syntax
#include <ldap.h> int ldap_version( LDAPVersion *ver );
Parameters
This function has the following parameters:
Table 18-134 - ldap_version() function parameters
ver |
LDAPVersion structure returning version information.
If you only want the SDK version, you can pass NULL
for this parameter.
|
Returns
The version number of the LDAP C SDK, multiplied by 100. For example, for version 1.0 of the LDAP C SDK, the function returns 100.
ldapssl_advclientauth_init()
Initializes your client application to connect to a secure LDAP server over SSL and to use certificate-based client authentication.
Note: This function is not multithread safe. It needs to be called only once per process, and does not, for example, need to be called again after ldap_unbind() is called.
Syntax
#include <ldap_ssl.h> int LDAP_CALL ldapssl_advclientauth_init( char *certdbpath, void *certdbhandle, int needkeydb, char *keydbpath, void *keydbhandle, int needsecmoddb, char *secmodpath, const int sslstrength);
Parameters
This function has the following parameters:
Table 18-135 - ldapssl_advclientauth_init() function parameters
certdbpath |
Path to the database containing certificates for your client. The
database must be the cert7.db certificate database
used by a Netscape or Mozilla client.x.
Note the following:
|
certdbhandle |
Pass a NULL value for this. (This parameter is not
used currently.)
|
needkeydb |
Specifies whether or not the private key database needs to be
opened for use. This parameter can have one of the following
values:
|
keydbpath |
Path to the database containing the private key certified by your
certificate. The database must be the key3.db
private key database used by a Mozilla or Netscape client.x.
Note the following:
|
certdbhandle |
Pass a NULL value for this. (This parameter is not
used currently.)
|
needsecmoddb |
Specifies whether or not the security module database file needs
to be opened for use. This parameter can have one of the
following values:
|
secmodpath |
Path to the database containing security modules. The database
must be the secmod.db private key database used by a
Netscape or Mozilla client.x.
Note the following:
|
sslstrength |
Specifies how the server certificate is evaluated. You can
specify one of the following values:
|
Returns
One of the following values:
0
if successful.-1
if unsuccessful.
Description
You can call the ldapssl_advclientauth_init()
function to initialize your client application for SSL and for
certificate-based client authentication.
This function is similar to
ldapssl_clientauth_init()
and allows you to do the following:
- Specify the name and path of a security module database.
- Specify the method used to verify the server's certificate.
You must call this function before calling the
ldapssl_init()
function to connect to the server. For details, see
Chapter 12 - Connecting Over SSL.
Example
The following example initializes a client before connecting with a secure LDAP server.
Code Example 18-55 - ldapssl_advclientauth_init() code example
#include <ldap_ssl.h> #include <stdio.h> ... /* Initialize client, using mozilla's certificate database */ if ( ldapssl_advclientauth_init( "/home/bjensen/.mozilla/bjensen/8vlmm76q.slt/cert8.db", NULL, 1, "/home/bjensen/.mozilla/bjensen/8vlmm76q.slt/key3.db", NULL , 1, "/home/bjensen/.mozilla/bjensen/8vlmm76q.slt/secmod.db", LDAPSSL_AUTH_CNCHECK) < 0 ) { perror( "ldap_advclientauth_init" ); return( 1 ); } } ...
See Also:
ldap_init(),
ldapssl_clientauth_init(),
ldapssl_init(),
ldapssl_install_routines().
ldapssl_client_init()
Initializes your client application to connect to a secure LDAP server over SSL.
Note: This function is not multithread safe. It needs to be called only once per process, and does not, for example, need to be called again after ldap_unbind() is called.
Syntax
#include <ldap_ssl.h> int ldapssl_client_init( const char *certdbpath, void *certdbhandle );
Parameters
This function has the following parameters:
Table 18-136 - ldapssl_client_init() function parameters
certdbpath |
Path to the database containing certificates for your client. The
database must be the cert7.db certificate database
used by a Mozilla or Netscape client.x.
You can either specify the path to the directory containing the
certificate database (in which case the function assumes that the
database file is named cert7.db ) or you can include
the database filename in the path.
If you pass NULL for this parameter, the function
looks for the certificate database used by Netscape Communicator
(for example, ~/.netscape/cert7.db on UNIX).
|
certdbhandle |
Pass a NULL value for this. (This parameter is not
used currently.)
|
Returns
One of the following values:
0
if successful.-1
if unsuccessful.
Description
You can call the ldapssl_client_init()
function to
initialize your client application for SSL.
If you plan to use certificate-based authentication, you should
call the
ldapssl_clientauth_init()
or ldapssl_advclientauth_init()
function instead of this function.
You must call this function before calling the
ldapssl_init()
function to connect to the server. For details, see
Chapter 12 - Connecting Over SSL.
Example
The following example initializes a client before connecting with a secure LDAP server.
Code Example 18-56 - ldapssl_client_init() code example
#include <ldap_ssl.h> #include <stdio.h> ... /* Initialize client, using mozilla's certificate database */ if ( ldapssl_client_init( "/home/bjensen/.mozilla/bjensen/8vlmm76q.slt/cert8.db", NULL ) < 0) { printf( "Failed to initialize SSL client...\n" ); return( 1 ); } ...
See Also:
ldap_init(),
ldapssl_init(),
ldapssl_install_routines().
ldapssl_clientauth_init()
Initializes your client application to connect to a secure LDAP server over SSL and to use certificate-based client authentication.
Note: This function is not multithread safe. It needs to be called only once per process, and does not, for example, need to be called again after ldap_unbind() is called.
Syntax
#include <ldap_ssl.h> int ldapssl_clientauth_init( char *certdbpath, void *certdbhandle, int needkeydb, char *keydbpath, void *keydbhandle );
Parameters
This function has the following parameters:
Table 18-137 - ldapssl_clientauth_init() function parameters
certdbpath |
Path to the database containing certificates for your client. The
database must be the cert7.db certificate database
used by a Mozilla or Netscape client.x.
You can either specify the path to the directory containing the
certificate database (in which case the function assumes that the
database file is named cert7.db ) or you can include
the database filename in the path.
If you pass NULL for this parameter, the function
looks for the certificate database used by Netscape Communicator
(for example, ~/.netscape/cert7.db on UNIX).
|
certdbhandle |
Pass a NULL value for this. (This parameter is not
used currently.)
|
needkeydb |
Specifies whether or not the private key database needs to be
opened for use. This parameter can have one of the following
values:
|
keydbpath |
Path to the database containing the private key certified by your
certificate. The database must either be the key3.db
certificate database used by a Mozilla or Netscape client.x.
You can either specify the path to the directory containing the
private key database (in which case the function assumes that the
database file is named key3.db ) or you can include
the database filename in the path.
If you pass NULL for this parameter, the function looks for the
key database used by Netscape Communicator (for example,
~/.netscape/key3.db on UNIX).
|
certdbhandle |
Pass a NULL value for this. (This parameter is not
used currently.)
|
Returns
One of the following values:
0
if successful.-1
if unsuccessful.
Description
You can call the ldapssl_clientauth_init()
function
to initialize your client application for SSL and certificate-based
client authentication.
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 of this function.
You must call this function before calling the
ldapssl_init()
function
to connect to the server. For details, see Chapter
12 - Connecting Over SSL.
Example
The following example initializes a client before connecting with a secure LDAP server.
Code Example 18-57 - ldapssl_clientauth_init() code example
#include <ldap_ssl.h> #include <stdio.h> ... /* Initialize client, using mozilla's certificate database */ if ( ldapssl_clientauth_init( "/home/bjensen/.mozilla/bjensen/8vlmm76q.slt/cert8.db", NULL, 1, "/home/bjensen/.mozilla/bjensen/8vlmm76q.slt/key3.db", NULL ) < 0 ) { perror( "ldap_clientauth_init" ); return( 1 ); } } ...
See Also:
ldap_init(),
ldapssl_clientauth_init(),
ldapssl_init(),
ldapssl_install_routines().
ldapssl_enable_clientauth()
Enables your application to use client authentication.
Syntax
#include <ldap_ssl.h> int ldapssl_enable_clientauth( LDAP *ld, char *keynickname, char *keypasswd, char *certnickname );
Parameters
This function has the following parameters:
Table 18-138 - ldapssl_enable_clientauth() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
keynickname |
This parameter is not currently used. Pass an empty string ("") for this value. |
keypasswd |
Password to the encrypted private key database. |
certnickname |
Nickname of the certificate that you want to use for client authentication. |
Returns
One of the following values:
0
if successful.-1
if unsuccessful.
See Also:
ldapssl_clientauth_init()
ldapssl_err2string()
The ldapssl_err2string()
function returns the
corresponding error message for an SSL-specific error code. For more
information, see "Getting the Error
Message."
Syntax
#include <ldap_ssl.h> const char * LDAP_CALL ldapssl_err2string ( const int prerrno );
Parameters
This function has the following parameters:
Table 18-139 - ldapssl_err2string() function parameters
prerrno |
The SSL error code that you want interpreted into an error message. |
Returns
One of the following values:
- If successful, returns the corresponding error message for the SSL error code.
-
If unsuccessful (for example, if the error code is not a known SSL
error code), returns a pointer to the string "
Unknown error
."
Description
This function provides support for the 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()
(and ldap_err2string()
returns "Unknown Error
"), this function should be
called to determine the SSL-specific error message.
To check for SSL errors, you should call
ldapssl_err2string()
after you call any of the
following SSL initialization functions:
ldapssl_client_init()
ldapssl_clientauth_init()
ldapssl_advclientauth_init()
ldapssl_pkcs_init()
The errors returned by these functions are usually related to certificate database corruption, missing certs in a certificate database, client authentication failures, and other general SSL errors.
See Also:
ldapssl_client_init(),
ldapssl_clientauth_init(),
ldapssl_advclientauth_init(),
ldapssl_pkcs_init(),
ldap_err2string()
ldapssl_init()
Initializes the LDAP library for SSL and installs the I/O
routines for SSL. ldapssl_init()
allocates an
LDAP structure but does not open an
initial connection.
Calling this function is equivalent to calling
ldap_init()
followed by
ldapssl_install_routines()
and ldap_set_option()
to set the LDAP_OPT_SSL
option to LDAP_OPT_ON
.
Before calling this function, you should call the
ldapssl_client_init()
function to initialize your client for SSL. For details, see
Chapter 12 - Connecting Over SSL.
Syntax
#include <ldap_ssl.h> LDAP *ldapssl_init( const char *defhost, int defport, int defsecure );
Parameters
This function has the following parameters:
Table 18-140 - ldapssl_init() function parameters
defhost |
Connect to this LDAP server, if no other server is specified. |
defport |
Connect to this server port, if no other port is specified. To
specify the default port 389, use LDAP_PORT as the
value for this parameter.
|
defsecure |
Determines whether or not to establish the default connection over SSL. Set this to a non-zero value to establish the default connection over SSL. |
Returns
One of the following values:
-
If successful, returns a pointer to an
LDAP
structure, which should be passed to subsequent calls to other LDAP API functions. - If unsuccessful, returns a
-1
.
Example
The following example connects your client with a secure LDAP server.
Code Example 18-58 - ldapssl_init() code example
#include <ldap_ssl.h> #include <stdio.h> ... /* Initialize client, using mozilla's certificate database */ if ( ldapssl_client_init( "/home/bjensen/.mozilla/bjensen/8vlmm76q.slt/cert8.db", NULL ) < 0) { printf( "Failed to initialize SSL client...\n" ); return( 1 ); } /* get a handle to an LDAP connection */ if ( (ld = ldapssl_init( "cert.example.com", LDAPS_PORT, 1 )) == NULL { perror( "ldapssl_init" ); return( 1 ); } ... /* Client can now perform LDAP operations on the secure LDAP server */ ...
See Also:
ldap_init(),
ldapssl_client_init(),
ldapssl_install_routines().
ldapssl_install_routines()
Installs the I/O routines to enable SSL over LDAP. You need to
call this routine in combination with
ldap_init()
and
ldap_set_option()
. (As
an alternative, you can call
ldapssl_init()
instead
of these three functions).
As is the case with the
ldapssl_init()
function, you need to call
ldapssl_client_init()
before calling this function.
Syntax
#include <ldap_ssl.h> int ldapssl_install_routines( LDAP *ld );
Parameters
This function has the following parameters:
Table 18-141 - ldapssl_install_routines() function parameters
ld |
Connection handle, which is a pointer to an
LDAP structure
containing information about the connection to the LDAP server.
|
Returns
One of the following values:
0
if successful.-1
if unsuccessful.
Example
The following example connects your client with a secure LDAP server.
Code Example 18-59 - ldapssl_install_routines() code example
#include <ldap_ssl.h> #include <stdio.h> ... /* Initialize client, using mozilla's certificate database */ if ( ldapssl_client_init( "/home/bjensen/.mozilla/bjensen/8vlmm76q.slt/cert8.db", NULL ) < 0) { printf( "Failed to initialize SSL client...\n" ); return( 1 ); } /* Get the handle to an LDAP connection */ if ( (ld = ldap_init( MY_HOST, 6360 )) == NULL ) { perror( "ldap_init" ); return( 1 ); }/* Load SSL routines */ if ( ldapssl_install_routines( ld ) != LDAP_SUCCESS ) { ldap_perror( ld, "ldapssl_install_routines" ); return( 1 ); }/* Set the option to use SSL with the default connection */ if (ldap_set_option( ld, LDAP_OPT_SSL, LDAP_OPT_ON ) != LDAP_SUCCESS) { ldap_perror( ld, "ldap_set_option" ); return( 1 ); } ...
See Also
ldap_init()
,
ldapssl_init()
,
ldapssl_client_init()
.
ldapssl_pkcs_init()
This function provides an alternative to the ldapssl_.*_init() family
of SSL initialization functions (ldapssl_client_init()
,
ldapssl_clientauth_init()
, and
ldapssl_advclientauth_init()
Note: This function is not multithread safe. It
needs to be called only once per process, and does not, for example,
need to be called again after ldap_unbind()
is called.
The LDAP C SDK uses the Public Key Cryptography Standard (PKCS) API implemented in Network Security Services (NSS) to provide SSL security support. Specifically, NSS implements the security API as defined in the PKCS#11 standard.
Syntax
#include <ldap_ssl.h> int LDAP_CALL ldapssl_pkcs_init(const struct ldapssl_pkcs_fns *pfns);
Parameters
This function has the following parameters:
Table 18-142 - ldapssl_pkcs_init() function parameters
pfns |
A pointer to a ldapssl_okcs_fns structure that
defines the callback function for obtaining the required SSL
security parameters.
|
Returns
One of the following values:
0
is successful.-1
if unsuccessful.-
n
, a positive integer, denotes an NSPR error as returned by thePR_GetError()
NSPR function. Consult the NSPR documentation onmozilla.org
for more information.
Description
The ldap_pkcs_init()
structure sets up callbacks for
the security library to obtain required runtime information. It may
be used in place of ldapssl_client_init()
,
ldapssl_clientauth_init()
, and
ldapssl_advclientauth_init()
.
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 did
require all security parameters to be known at the time of
initialization.
The ldapssl_pkcs_fns
structure is defined as follows:
typedef int (LDAP_PKCS_GET_TOKEN_CALLBACK) (void *context, char **tokenname); typedef int (LDAP_PKCS_GET_PIN_CALLBACK) (void *context, const char *tokenname, char **tokenpin); typedef int (LDAP_PKCS_GET_CERTPATH_CALLBACK) (void *context, char **certpath); typedef int (LDAP_PKCS_GET_KEYPATH_CALLBACK)(void *context, char **keypath); typedef int (LDAP_PKCS_GET_MODPATH_CALLBACK) (void *context, char **modulepath); typedef int (LDAP_PKCS_GET_CERTNAME_CALLBACK) (void *context, char **certname); typedef int (LDAP_PKCS_GET_DONGLEFILENAME_CALLBACK) (void *context, char **filename);#define PKCS_STRUCTURE_ID 1 struct ldapssl_pkcs_fns { int local_structure_id; void *local_data; LDAP_PKCS_GET_CERTPATH_CALLBACK *pkcs_getcertpath; LDAP_PKCS_GET_CERTNAME_CALLBACK *pkcs_getcertname; LDAP_PKCS_GET_KEYPATH_CALLBACK *pkcs_getkeypath; LDAP_PKCS_GET_MODPATH_CALLBACK *pkcs_getmodpath; LDAP_PKCS_GET_PIN_CALLBACK *pkcs_getpin; LDAP_PKCS_GET_TOKEN_CALLBACK *pkcs_gettokenname; LDAP_PKCS_GET_DONGLEFILENAME_CALLBACK *pkcs_getdonglefilename; };
See Also:
ldapssl_client_init(),
ldapssl_clientauth_init(),
ldapssl_advclientauth_init().