The LDAP session handle returned by ldap_init() is a pointer
to an opaque data type representing an LDAP session. Formerly,
this data type was a structure exposed to the caller, and various
fields in the structure could be set to control aspects of the
session, such as size and time limits on searches.
To insulate callers from inevitable changes to this structure,
these aspects of the session are now accessed through a pair of
accessor functions.
The ldap_get_option() function is used to access the current
value of various session-wide parameters. The ldap_set_option()
function is used to set the value of these parameters. Note that
some options are READ-ONLY and cannot be set; it is an error to
call ldap_set_option() and attempt to set a READ-ONLY option.
int ldap_get_option(
LDAP *ld,
int option,
void *outvalue
);
int ldap_set_option(
LDAP *ld,
int option,
const void *invalue
);
Parameters are as follows:
ld The session handle. If this is NULL, a set of global
defaults is accessed. New LDAP session handles
created with ldap_init() or ldap_open() inherit their
characteristics from these global defaults.
option The name of the option being accessed or set. This
parameter should be one of the following constants,
which have the indicated meanings. After the constant,
the actual hexadecimal value of the constant is listed
in parentheses.
LDAP_OPT_DESC Type for invalue parameter: not
(0x01) applicable (option is read-only).
Type for outvalue parameter: int *
Description: The underlying socket
descriptor corresponding to the
primary LDAP connection. This
option is read-only and cannot
be set.
LDAP_OPT_DEREF Type for invalue parameter: int *
(0x02) Type for outvalue parameter: int *
Description: Determines how aliases
are handled during search. It can
have one of the following values:
LDAP_DEREF_NEVER (0x00), LDAP_
DEREF_SEARCHING (0x01), LDAP_DEREF_
FINDING (0x02), or LDAP_DEREF_
ALWAYS (0x03). The LDAP_DEREF_
SEARCHING value means aliases
should be dereferenced during
the search but not when locating
the base object of the search.The
LDAP_DEREF_FINDING value means
aliases should be dereferenced when
locating the base object but not
during the search.
LDAP_OPT_ Type for invalue parameter: int *
SIZELIMIT (0x03) Type for outvalue parameter: int *
Description: A limit on the number
of entries to return from a search.
A value of LDAP_NO_LIMIT (0) means
no limit.
LDAP_OPT_ Type for invalue parameter: int *
TIMELIMIT (0x04) Type for outvalue parameter: int *
Description: A limit on the number
of seconds to spend on a search. A
value of LDAP_NO_LIMIT (0) means no
limit.
LDAP_OPT_ Type for invalue parameter: int
REFERRALS (0x08) (LDAP_OPT_ON or LDAP_OPT_OFF)
Type for outvalue parameter: int *
Description: Determines whether
the LDAP library automatically
follows referrals returned by LDAP
servers. It can be set to one of
the constants LDAP_OPT_ON (1) or
LDAP_OPT_OFF (0).
LDAP_OPT_RESTART Type for invalue parameter: int
(0x09) (LDAP_OPT_ON or LDAP_OPT_OFF)
Type for outvalue parameter: int *
Description: Determines whether
LDAP I/O operations should
automatically be restarted if they
abort prematurely. It should be
set to one of the constants LDAP_
OPT_ON or LDAP_OPT_OFF. This option
is useful if an LDAP I/O operation
is interrupted prematurely, (for
example, by a timer going off) or
other interrupt.
LDAP_OPT_ Type for invalue parameter: int *
PROTOCOL_VERSION Type for outvalue parameter: int *
(0x11)
Description: This option indicates
the version of the LDAP protocol
used when communicating with the
primary LDAP server. It must be
one of the constants LDAP_VERSION2
(2) or LDAP_VERSION3 (3). If no
version is set, the default is
LDAP_VERSION2 (2).
LDAP_OPT_SERVER_ Type for invalue parameter:
CONTROLS (0x12) LDAPControl **
Type for outvalue parameter:
LDAPControl ***
Description: A default list of LDAP
server controls to be sent with
each request. See Controls for more
information.
LDAP_OPT_CLIENT_ Type for invalue parameter:
CONTROLS (0x13) LDAPControl **
Type for outvalue parameter:
LDAPControl ***
Description: A default list of
client controls that affect the
LDAP session. See Controls for more
information.
LDAP_OPT_HOST_ Type for invalue parameter: char *
NAME (0x30) Type for outvalue parameter: char
**
Description: The host name (or
list of host) for the primary LDAP
server.
LDAP_OPT_ERROR_ Type for invalue parameter: int *
NUMBER (0x31) Type for outvalue parameter: int *
Description: The code of the most
recent LDAP error that occurred for
this session.
LDAP_OPT_ERROR_ Type for invalue parameter: char *
STRING (0x32) Type for outvalue parameter: char
**
Description: The message returned
with the most recent LDAP error
that occurred for this session.
outvalue The address of a place to put the value of the option.
The actual type of this parameter depends on the
setting of the option parameter. For outvalues of type
char ** and LDAPControl **, a pointer to data that
is associated with the LDAP session ld is returned;
callers should dispose of the memory by calling ldap_
memfree() or ldap_controls_free().
invalue A pointer to the value the option is to be given. The
actual type of this parameter depends on the setting
of the option parameter. The constants LDAP_OPT_ON and
LDAP_OPT_OFF can be given for options that have on or
off settings.
Both ldap_get_option() and ldap_set_option() return 0
if successful and -1 if an error occurs.