ldap_set_option() -- Set LDAP Options
Syntax
#include <ldap.h> int ldap_set_option( LDAP *ld, int optionToSet, const void *optionValue )
Library Name/Service Program: QSYS/QGLDCLNT
Default Public Authority: *USE
Threadsafe: Yes
The ldap_set_option() function is used to set options for the specified LDAP connection.
Authorities and Locks
No IBM® i authority is required.
Parameters
- ld
- (Input) An LDAP pointer returned by a previous call to
ldap_init(),
ldap_ssl_init(), or
ldap_open().
If a NULL ld is passed in, the default option value is set. Later calls to
ldap_init(),
ldap_ssl_init(), or
ldap_open()
will use the set value as the default for the option.
- optionToSet
- (Input) The option value to be set. See below for the list of supported
options.
- optionValue
- (Input) The address of the value. For LDAP V3 client options, optionValue is the actual value to be set.
The following session settings can be set using the ldap_set_option() API:
LDAP_OPT_SIZELIMIT | Mmaximum 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 referrals should be followed by the client |
LDAP_OPT_DEBUG | Client 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 option |
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 ); }
Additional details on specific options for ldap_set_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:
0 | LDAP_DEREF_NEVER |
1 | LDAP_DEREF_SEARCHING |
2 | LDAP_DEREF_FINDING |
3 | LDAP_DEREF_ALWAYS |
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 );
An alternative way to set the debug level is to set the LDAP_DEBUG environment variable in the job that the client application will run in. The environment variable is set to the same numerical value that the value variable would be set to if ldap_set_option() was used. An example of enabling client trace for an application using the LDAP_DEBUG environment variable:
ADDENVVAR ENVVAR(LDAP_DEBUG) VALUE(0X0003)
After the client application has run, use
DMPUSRTRC jobnumber-of-the-client-job
Then, to display the trace information interactively, use
DSPPFM QAP0ZDMP QP0Znnnnnn -- where nnnnnn is the job number.
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 | 05 (Non-export only) |
LDAP_SSL_RC4_SHA_US | 04 (Non-export only) |
LDAP_SSL_RC4_MD5_US | 06 |
LDAP_SSL_DES_SHA_US | 09 (Non-export only) |
LDAP_SSL_3DES_SHA_US | 0A (Non-export only) |
LDAP_SSL_AES_SHA_US | 2F (Non-export only) |
Examples:
char *setcipher = "2F090A"; char *getcipher; ldap_set_option( ld, LDAP_OPT_SSL_CIPHER, setcipher); ldap_get_option( ld, LDAP_OPT_SSL_CIPHER, &getcipher );
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, no server controls will be sent.
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. It can be set to one of the constants LDAP_UTF8_XLATE_ON or LDAP_UTF8_XLATE_OFF. By default, the LDAP library will convert string data.
When conversion is disabled, the LDAP library assumes that data received from the application by LDAP APIs is already represented in UTF-8. Similarly, the LDAP library assumes that the application is prepared to receive string data from the LDAP library represented in UTF-8 (or as binary).
When LDAP_UTF8_XLATE_ON is set (the default), the LDAP library assumes that string data received from the application by LDAP APIs is in the default (or explicitly designated) code page. Similarly, all string data returned from the LDAP library (back to the application) is converted to the designated local code page.
It is important to note that only string data supplied on connection-based APIs will be translated (that is, only those APIs that include an ld will be subject to translation). For example, string values passed in to ldap_search() will be converted, but string values passed in to ldap_init will not.
It is also important to note that translation of strings from a UTF-8 encoding to local code page may result in loss of data when one or more characters in the UTF-8 encoding cannot be represented in the local code page. When this occurs, a substitution character replaces any UTF-8 characters that cannot be converted to the local code page.
For more information about explicitly setting the locale for conversions, see ldap_set_locale().
Examples:
int value; ldap_set_option( ld, LDAP_OPT_UTF8_IO, (void *)LDAP_UTF8_XLATE_ON); ldap_get_option( ld, LDAP_OPT_UTF8_IO, &value);
Return Value
- LDAP_SUCCESS
- if the request was successful.
- another LDAP error code
- if the request was not successful.
Error Conditions
The ldap_set_option() function will return an 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 sent from this function.
Message ID | Error Message Text |
---|---|
CPF3CF2 E | Error(s) occurred during running of ldap_set_option API. |
Related Information
- ldap_get_option() -- Retrieve an option associated with an LDAP descriptor.
- ldap_init() -- Initializes a session with an LDAP server.
- ldap_open() -- Open a connection to an LDAP server (deprecated).
- ldap_set_rebind_proc() -- Set rebind procedure
- ldap_version() -- Obtain LDAP version and SSL cipher information.
API introduced: V4R5
[ Back to top | LDAP APIs | APIs by category ]