ldap_get_option, ldap_set_option — LDAP option handling routines
#include <ldap.h>
int
ldap_get_option( |
LDAP * | ld, |
| int | option, | |
| void * | outvalue); |
int
ldap_set_option( |
LDAP * | ld, |
| int | option, | |
| const void * | invalue); |
These routines provide access to options stored either in
a LDAP handle or as global options, where applicable. They
make use of a neutral interface, where the type of the value
either retrieved by ldap_get_option(3) or set
by ldap_set_option(3) is cast
to void *. The actual
type is determined based on the value of the option argument. Global options
are set/retrieved by passing a NULL LDAP handle.
LDAP_OPT_API_INFOFills-in a struct
ldapapiinfo; outvalue must be a
struct ldapapiinfo *,
pointing to an already allocated struct. This is a
read-only option.
LDAP_OPT_DESCReturns the file descriptor associated to the socket
buffer of the LDAP handle passed in as ld; outvalue must be a
int *. This is a
read-only, handler-specific option.
LDAP_OPT_SOCKBUFReturns a pointer to the socket buffer of the LDAP
handle passed in as ld; outvalue must be a
Sockbuf **. This
is a read-only, handler-specific option.
LDAP_OPT_TIMEOUTSets/gets a timeout value for the synchronous API
calls. outvalue
must be a struct timeval **
(the caller has to free *outvalue), and invalue must be a
struct timeval *, and they
cannot be NULL. Using a struct with seconds set to -1
results in an infinite timeout, which is the
default.
LDAP_OPT_NETWORK_TIMEOUTSets/gets the network timeout value after which
poll(2)/select(2) following a
connect(2) returns in
case of no activity. outvalue must be a
struct timeval ** (the caller
has to free *outvalue), and invalue must be a
struct timeval *, and they
cannot be NULL. Using a struct with seconds set to -1
results in an infinite timeout, which is the
default.
LDAP_OPT_DEREFSets/gets the value that defines when alias
dereferencing must occur. outvalue and invalue must be
int *, and they
cannot be NULL.
LDAP_OPT_SIZELIMITSets/gets the value that defines the maximum number
of entries to be returned by a search operation.
outvalue and
invalue must be
int *, and they
cannot be NULL.
LDAP_OPT_TIMELIMITSets/gets the value that defines the time limit
after which a search operation should be terminated by
the server. outvalue and invalue must be
int *, and they
cannot be NULL.
LDAP_OPT_REFERRALSDetermines whether the library should implicitly
chase referrals or not. outvalue and invalue must be
int *; their
value should either be LDAP_OPT_OFF or LDAP_OPT_ON.
LDAP_OPT_RESTARTDetermines whether the library should implicitly
restart connections (FIXME). outvalue and invalue must be
int *; their
value should either be LDAP_OPT_OFF or LDAP_OPT_ON.
LDAP_OPT_PROTOCOL_VERSIONSets/gets the protocol version. outvalue and invalue must be
int *.
LDAP_OPT_SERVER_CONTROLSSets/gets the server-side controls to be used for
all operations. This is now deprecated as modern LDAP C
API provides replacements for all main operations which
accepts server-side controls as explicit arguments; see
for example ldap_search_ext(3),
ldap_add_ext(3),
ldap_modify_ext(3)
and so on. outvalue must be
LDAPControl ***,
and the caller is responsible of freeing the returned
controls, if any, by calling ldap_controls_free(3),
while invalue
must be LDAPControl
**; the library duplicates the controls
passed via invalue.
LDAP_OPT_CLIENT_CONTROLSSets/gets the client-side controls to be used for
all operations. This is now deprecated as modern LDAP C
API provides replacements for all main operations which
accepts client-side controls as explicit arguments; see
for example ldap_search_ext(3),
ldap_add_ext(3),
ldap_modify_ext(3)
and so on. outvalue must be
LDAPControl ***,
and the caller is responsible of freeing the returned
controls, if any, by calling ldap_controls_free(3),
while invalue
must be LDAPControl
**; the library duplicates the controls
passed via invalue.
LDAP_OPT_HOST_NAMESets/gets a space-separated list of hosts to be
contacted by the library when trying to establish a
connection. This is now deprecated in favor of
LDAP_OPT_URI. outvalue must be a
char **, and the
caller is responsible of freeing the resulting string
by calling ldap_memfree(3),
while invalue
must be a char
*; the library duplicates the corresponding
string.
LDAP_OPT_URISets/gets a space-separated list of URIs to be
contacted by the library when trying to establish a
connection. outvalue must be a
char **, and the
caller is responsible of freeing the resulting string
by calling ldap_memfree(3),
while invalue
must be a char
*; the library parses the string into a
list of LDAPURLDesc
structures, so the invocation of ldap_set_option(3)
may fail if URL parsing fails.
LDAP_OPT_DEFBASESets/gets a string containing the DN to be used as
default base for search operations. outvalue must be a
char **, and the
caller is responsible of freeing the returned string by
calling ldap_memfree(3),
while invalue
must be a char
*; the library duplicates the corresponding
string.
LDAP_OPT_RESULT_CODESets/gets the LDAP result code associated to the
handle. This option was formerly known as LDAP_OPT_ERROR_NUMBER. Both
outvalue and
invalue must be
a int *.
LDAP_OPT_DIAGNOSTIC_MESSAGESets/gets a string containing the error string
associated to the LDAP handle. This option was formerly
known as LDAP_OPT_ERROR_STRING. outvalue must be a
char **, and the
caller is responsible of freeing the returned string by
calling ldap_memfree(3),
while invalue
must be a char
*; the library duplicates the corresponding
string.
LDAP_OPT_MATCHED_DNSets/gets a string containing the matched DN
associated to the LDAP handle. outvalue must be a
char **, and the
caller is responsible of freeing the returned string by
calling ldap_memfree(3),
while invalue
must be a char
*; the library duplicates the corresponding
string.
LDAP_OPT_REFERRAL_URLSSets/gets an array containing the referral URIs
associated to the LDAP handle. outvalue must be a
char ***, and
the caller is responsible of freeing the returned
string by calling ber_memvfree(3), while
invalue must be
a NULL-terminated char
**; the library duplicates the
corresponding string.
LDAP_OPT_API_FEATURE_INFOFills-in a LDAPAPIFeatureInfo; outvalue must be a
LDAPAPIFeatureInfo
*, pointing to an already allocated struct.
This is a read-only option.
LDAP_OPT_DEBUG_LEVELSets/gets the debug level of the client library.
Both outvalue
and invalue
must be a int
*.
On success, the functions return LDAP_OPT_SUCCESS, while they may return
LDAP_OPT_ERROR to indicate a
generic option handling error. Occasionally, more specific
errors can be returned, like LDAP_NO_MEMORY to indicate a failure in
memory allocation.
The LDAP libraries with the LDAP_OPT_REFERRALS option set to
LDAP_OPT_ON (default value)
automatically follow referrals using an anonymous bind.
Application developers are encouraged to either implement
consistent referral chasing features, or explicitly disable
referral chasing by setting that option to LDAP_OPT_OFF.
OpenLDAP Software is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. OpenLDAP Software is derived from University of Michigan LDAP 3.3 Release.