ldap_set_option()--Set LDAP Options
Syntax
#include <ldap.h>
int ldap_set_option(
LDAP *ld,
int optionToSet,
void *optionValue)
Threadsafe: Yes
|
The ldap_set_option() function is used to set options for the specified LDAP connection.
Authorities and Locks
No OS/400 authority is required. All authority checking is done by the LDAP server.
- ld
- (Input) Specifies the LDAP pointer returned by a previous call to ldap_init(),ldap_ssl_init(), or ldap_open().
- optionToSet
- (Input) Identifies the option value that is to be set on the ldap_set_option() call. See USAGE below for the list of supported options.
- optionValue
- (Input) Specifies the address of the value to be set via ldap_set_option(). For LDAP V3 client optionValue can also be the actual value to be set as in the case of LDAP V2 client.
The following session settings can be set using the ldap_set_option() API:
- LDAP_OPT_SIZELIMIT
- maximum number of entries that can be returned on a search operation
- LDAP_OPT_TIMELIMIT
- maximum number of seconds to wait for search results.
- LDAP_OPT_REFHOPLIMIT
- maximum number of referrals in a sequence that the client can follow
- LDAP_OPT_DEREF
- rules for following aliases at the server.
- LDAP_OPT_REFERRALS
- whether or not referrals should be followed by the client.
- LDAP_OPT_DEBUG
- debug options.
- LDAP_OPT_SSL_CIPHER
- SSL ciphers to use.
- LDAP_OPT_SSL_TIMEOUT
- SSL timeout for refreshing session keys
- LDAP_OPT_REBIND_FN
- address of application's setrebindproc procedure.
- LDAP_OPT_PROTOCOL_VERSION
- LDAP protocol version to use (V2 or V3).
- LDAP_OPT_SERVER_CONTROLS
- default server controls.
- LDAP_OPT_CLIENT_CONTROLS
- default client library controls.
- LDAP_OPT_UTF8_IO
- String Data type UTF-8 potion.
Additional details on specific options for ldap_set_option() and ldap_get_option
are provided in the following sections.
LDAP_OPT_SIZELIMIT
Specifies the maximum number of entries that can be returned on a search
operation. Note: the actual size limit for operations
is also bounded by the maximum number of entries that the server
is configured to return. Thus, the actual size limit will be the lesser of
the value specified on this option and the value configured in the LDAP server.
The default sizelimit is unlimited, specified with a value of zero (thus deferring
to the sizelimit setting of the LDAP server).
).
Examples:
sizevalue=50;
ldap_set_option( ld, LDAP_OPT_SIZELIMIT, &sizevalue);
ldap_get_option( ld, LDAP_OPT_SIZELIMIT, &sizevalue );
LDAP_OPT_TIMELIMIT
Specifies the number of seconds to wait for search results.
Note: the actual time limit for operations
is also bounded by the maximum time that the server
is configured to allow. Thus, the actual time limit will be the lesser of
the value specified on this option and the value configured in the LDAP server.
The default is unlimited (specified with a value of zero).
Examples:
timevalue=50;
ldap_set_option( ld, LDAP_OPT_TIMELIMIT, &timevalue);
ldap_get_option( ld, LDAP_OPT_TIMELIMIT, &timevalue );
LDAP_OPT_REFHOPLIMIT
Specifies the maximum number of hops that the client library
will take when chasing referrals. The default is 5.
Examples:
hoplimit=7;
ldap_set_option( ld, LDAP_OPT_REFHOPLIMIT, &hoplimit);
ldap_get_option( ld, LDAP_OPT_REFHOPLIMIT, &hoplimit);
LDAP_OPT_DEREF
Specifies alternative rules for following aliases at the server.
The default is LDAP_DEREF_NEVER.
Supported values:
LDAP_DEREF_NEVER 0
LDAP_DEREF_SEARCHING 1
LDAP_DEREF_FINDING 2
LDAP_DEREF_ALWAYS 3
Examples:
int deref = LDAP_DEREF_NEVER;
ldap_set_option( ld, LDAP_OPT_DEREF, &deref);
ldap_get_option( ld, LDAP_OPT_DEREF, &deref);
LDAP_OPT_REFERRALS
Specifies whether the LDAP library will automatically
follow referrals returned by LDAP servers or not.
It can be set to one of the constants LDAP_OPT_ON
or LDAP_OPT_OFF.
By default, the LDAP client
will follow referrals.
Examples:
int value;
ldap_set_option( ld, LDAP_OPT_REFFERALS, (void *)LDAP_OPT_ON);
ldap_get_option( ld, LDAP_OPT_REFFERALS, &value);
LDAP_OPT_DEBUG
Specifies a bit-map that indicates the level of debug trace for the LDAP library.
Supported values:
/* Debug levels */
LDAP_DEBUG_OFF 0x000
LDAP_DEBUG_TRACE 0x001
LDAP_DEBUG_PACKETS 0x002
LDAP_DEBUG_ARGS 0x004
LDAP_DEBUG_CONNS 0x008
LDAP_DEBUG_BER 0x010
LDAP_DEBUG_FILTER 0x020
LDAP_DEBUG_CONFIG 0x040
LDAP_DEBUG_ACL 0x080
LDAP_DEBUG_STATS 0x100
LDAP_DEBUG_STATS2 0x200
LDAP_DEBUG_SHELL 0x400
LDAP_DEBUG_PARSE 0x800
LDAP_DEBUG_ANY 0xffff
Examples:
int value;
int debugvalue= LDAP_DEBUG_TRACE | LDAP_DEBUG_PACKETS;
ldap_set_option( ld, LDAP_OPT_DEBUG, &debugvalue);
ldap_get_option( ld, LDAP_OPT_DEBUG, &value );
LDAP_OPT_SSL_CIPHER
Specifies a set of one or more ciphers to be used when negotiating
the cipher algorithm with the LDAP server. The first cipher in the list
that is common with the list of ciphers supported by the server is
chosen. For the
export version of the library, the value used is "0306". For the domestic
version of the library, the default value is "05040A090306".
Note that the cipher string supported by
the export version of the LDAP client library
is fixed and cannot be modified.
Supported ciphers:
LDAP_SSL_RC4_MD5_EX "03"
LDAP_SSL_RC2_MD5_EX "06"
LDAP_SSL_RC4_SHA_US "05" (Non-export only)
LDAP_SSL_RC4_MD5_US "04" (Non-export only)
LDAP_SSL_DES_SHA_US "09" (Non-export only)
LDAP_SSL_3DES_SHA_US "0A" (Non-export only)
Examples:
char *setcipher = "090A";
char *getcipher;
ldap_set_option( ld, LDAP_OPT_SSL_CIPHER, setcipher);
ldap_get_option( ld, LDAP_OPT_SSL_CIPHER, &getcipher );
Use ldap_memfree() to free the
memory returned by the call to ldap_get_option().
LDAP_OPT_SSL_TIMEOUT
Specifies in seconds the SSL inactivity timer. After the specified
seconds, in which no SSL activity has occurred, the SSL connection will be refreshed
with new session keys. A smaller value may help increase security, but
will have a small impact on performance. The default SSL timeout value is 43200 seconds.
Examples:
value = 100;
ldap_set_option( ld, LDAP_OPT_SSL_TIMEOUT, &value );
ldap_get_option( ld, LDAP_OPT_SSL_TIMEOUT, &value)
LDAP_OPT_REBIND_FN
Specifies the address of a routine to be called by the LDAP library
when the need arises to authenticate a connection with another
LDAP server. This can occur, for example, when the LDAP library
is chasing a referral. If a routine is not defined, referrals will
always be chased using the anonymous identity.
A default routine is not defined.
Examples:
extern LDAPRebindProc proc_address;
LDAPRebindProc value;
ldap_set_option( ld, LDAP_OPT_REBIND_FN, &proc_address);
ldap_get_option( ld, LDAP_OPT_REBIND_FN, &value);
LDAP_OPT_PROTOCOL_VERSION
Specifies the LDAP protocol to be used by the LDAP client library
when connecting to an LDAP server. Also used to determine which
LDAP protocol is being used for the connection.
For an
application that uses ldap_init() to create the LDAP connection
the default value of this option will be LDAP_VERSION3
for communicating with the LDAP server.
The default value of this option will be LDAP_VERSION2 if
the application uses the deprecated ldap_open() API.
In either case, the LDAP_OPT_PROTOCOL_VERSION option can be
used with ldap_set_option() to change the default.
The LDAP protocol version should be reset prior to issuing the
bind (or any operation that causes an implicit bind).
Examples:
version2 = LDAP_VERSION2;
version3 = LDAP_VERSION3;
/* Example for Version 3 application setting version to version 2 */
ldap_set_option( ld, LDAP_OPT_PROTOCOL_VERSION, &version2);
/* Example of Version 2 application setting version to version 3 */
ldap_set_option( ld, LDAP_OPT_PROTOCOL_VERSION, &version3);
ldap_get_option( ld, LDAP_OPT_PROTOCOL_VERSION, &value);
LDAP_OPT_SERVER_CONTROLS
Specifies a default list of server controls to be sent with each
request. The default list can be overridden by specifying a server control,
or list of server controls, on specific APIs. By default, there are no settings
for Server Controls.
Example:
ldap_set_option( ld, LDAP_OPT_SERVER_CONTROLS, &ctrlp);
LDAP_OPT_CLIENT_CONTROLS
Specifies a default list of client controls to be processed by the client
library with each request. Since client controls are not defined for this version
of the library, the ldap_set_option() API can be used to define a set of
default, non-critical client controls. If one or more client controls in the set
is critical, the entire list is rejected with a return code of
LDAP_UNAVAILABLE_CRITICAL_EXTENSION.
LDAP_OPT_UTF8_IO
Specifies whether the LDAP library will automatically convert string data to and
from the local code page to UTF-8, for the specified ld or connection. It can be set to one of the constants LDAP_UTF8_XLATE_OFF or LDAP_UTF8_XLATE_ON (default). By default, the LDAP library will convert string data from local code page to UTF-8 before it goes out to the wire.
Examples:
optionValue = LDAP_UTF8_XLATE_OFF;
ldap_set_option( ld, LDAP_OPT_UTF8_IO, &optionValue);
The value returned by ldap_get_option() when LDAP_OPT_PROTOCOL_VERSION is specified
can be used to determine how parameters should be passed to the ldap_set_option() call.
The easiest way to work with this compatibility feature is to guarantee that calls to ldap_set_option()
are all performed while the LDAP_OPT_PROTOCOL_VERSION is set to the same value. If this cannot
be guaranteed by the application, then follow the format of the example below when coding
the call to ldap_set_option():
int sizeLimit=100;
int protocolVersion;
ldap_get_option( ld, LDAP_OPT_PROTOCOL_VERSION, &protocolVersion );
if ( protocolVersion == LDAP_VERSION2 ) {
ldap_set_option( ld, LDAP_OPT_SIZELIMIT, (void *)sizeLimit );
} else { /* the protocol version is LDAP_VERSION3 */
ldap_set_option( ld, LDAP_OPT_SIZELIMIT, &sizeLimit );
}
Return Value
- LDAP_SUCCESS
- if the request was successful.
- another LDAP error code
- if the request was not successful.
Error Conditions
If ldap_set_option() will return LDAP error code if not successful. See LDAP Client API Error Conditions for possible LDAP error codes values.
Error Messages
The following message may be set from this function.
CPF3CF2 E Error(s) occurred during running of ldap_set_option API.
Related Information
ldap_init() -- Initializes a session with an LDAP server.
ldap_open() -- Open a connection to an LDAP server (deprecated).
ldap_get_option() -- Retrieve an option associated with an LDAP descriptor.
ldap_version() -- Obtain LDAP version and SSL cipher information.