6.10 Session Preference Options

These flags are used by the ldap_get_option and ldap_set_option functions.

Table 6-9 Session Preference Options

Option

Value

Description

LDAP_OPT_API_FEATURE_INFO

0x0015

Specifies version information about an LDAP API extended feature.

ldap_set_option data type: Not supported; ldap_get_option data type: LDAPAPIFeatureInfo *

LDAP_OPT_API_INFO

0x0000

Retrieves basic information about the API implementation. It cannot be used to set information.

It includes the API version, minimum LDAP version, maximum LDAP version, vendor name, and vendor version. If the ldap_get_option function returns

  • The vendor name, the application must free the memory by calling the ldap_memfree function.

  • Some ldap extensions, the application must free the memory by calling the ldap_value_free function.

ldap_set_option data type: Not supported; ldap_get_option data type: LDAPAPIInfo *;

LDAP_OPT_CLIENT_CONTROLS

0x0013

Specifies a default list of client controls that affect the LDAP session.

ldap_set_option data type, LDAPControl **; ldap_get_option data type: LDAPControl ***

The application should free memory with ldap_controls_free.

LDAP_OPT_CURRENT_NAME

0x7003

Returns the client address associated with the supplied session handle argument.

ldap_get_option data type : struct sockaddr_in *

This is read only.

LDAP_OPT_DEBUG_LEVEL

0x5001

Contains the debug level. Uses the following values:

  • 0x0001 LDAP_DEBUG_TRACE
  • 0x0002 LDAP_DEBUG_PACKETS
  • 0x0004 LDAP_DEBUG_ARGS
  • 0x0008 LDAP_DEBUG_CONNS
  • 0x0010 LDAP_DEBUG_BER
  • 0x0020 LDAP_DEBUG_FILTER
  • 0x0040 LDAP_DEBUG_CONFIG
  • 0x0080 LDAP_DEBUG_ACL
  • 0x0100 LDAP_DEBUG_STATS
  • 0x0200 LDAP_DEBUG_STATS2
  • 0x0400 LDAP_DEBUG_SHELL
  • 0x0800 LDAP_DEBUG_PARSE
  • 0x8000 LDAP_DEBUG_NONE
  • -1 LDAP_DEBUG_ANY

ldap_set_option and ldap_get_option data type: int*

LDAP_OPT_DEREF

0x0002

Determines how aliases are handled during a search. Supports the following values:

  • LDAP_DEREF_NEVER (0X00)
  • LDAP_DEREF_SEARCHING (0x01)
  • LDAP_DEREF_FINDING (0x02)
  • LDAP_DEREF_ALWAYS (0x03)

The LDAP_DEREF_SEARCHING flag indicates that aliases are dereferenced during the search but not when locating the base object of the search.

The LDAP_DEREF_FINDING flag indicates that aliases are dereferenced when locating the base object but not during the search.

The LDAP_DEREF_ALWAYS flag indicates that aliases are dereferenced when locating the base object and when finding entries.

The LDAP_DEREF_NEVER flag indicates that aliases are not dereferenced.

The default is LDAP_DEREF_NEVER.

ldap_get_option and ldap_set_option data type: int *

LDAP_OPT_ERROR_STRING

0x0032

Contains the message that returned with the most recent LDAP error that occurred on this session.

ldap_set_option data type: char *; ldap_get_option data type: char **

The application should free memory with ldap_memfree.

LDAP_OPT_HOST_NAME

0x0030

Specifies the host name or a list of hosts for the primary LDAP server.

ldap_set_option data type: char *; ldap_get_option data type: char **

The application should free memory with ldap_memfree.

LDAP_OPT_MATCHED_DN

0x0033

Contains the matched DN value returned with the most recent LDAP error that occurred on this session.

ldap_set_option data type: char *; ldap_get_option data type: char **

The application should free memory with ldap_memfree.

LDAP_OPT_NETWORK_TIMEOUT

0x5005

Enables a connection timeout to be set. This is the timeout of the initial connection to a server, which usually occurs when the bind command is executed, or, if no bind command is given, on the first LDAP operation. Initial connections may also occur during a referral or rebind operation.

If no timeout is set, timeout depends upon the underlying socket timeout setting of the operating system.

ldap_set_option data type, struct timeval *; ldap_get_option data type: struct timeval **

LDAP_OPT_PEER_NAME

0x7002

Returns the peer address associated with the supplied session handle argument.

ldap_get_option data type : struct sockaddr_in *

This is read only.

LDAP_OPT_PROTOCOL_VERSION

0x0011

Specifies the version of the LDAP protocol used when communication with the LDAP server. It can be set to one of the following values:

  • LDAP_VERSION2 (2)
  • LDAP_VERSION3 (3)

If no version is set, the default is LDAP_VERSION2.

ldap_get_option and ldap_set_option data type: int *

LDAP_OPT_REFERRAL_LIST

0x5007

If the server returns referrals and the client library is set to return them to the application (LDAP_OPT_REFERRALS=0), this option can be used to obtain the list of referrals after an error 10 (LDAP_REFERRAL). It returns a NULL-terminated list of string pointers containing the referrals.

ldap_set_option data type: char**; ldap_get_option data type char***

The memory returned should be freed by the application with ldap_value_free().

LDAP_OPT_REFERRALS

0x0008

Determines whether the LDAP libraries automatically follow referrals. It can be set to one of the following values:

  • LDAP_OPT_ON (void*) 1
  • LDAP_OPT_OFF (void*) 0

The default is ON.

ldap_set_option data type: void*; ldap_get_option data type: int*

LDAP_OPT_RESULT_CODE

0x0031

Specifies the code of the most recently returned LDAP error that occurred on this session.

ldap_get_option and ldap_set_option data type: int *

LDAP_OPT_RESTART

0x0009

Determines whether LDAP I/O operations automatically restart if they abort prematurely. It can be set to one of the following values:

  • LDAP_OPT_ON (void*) 1
  • LDAP_OPT_OFF (void*) 0

The default is OFF

ldap_set_option data type: void*; ldap_get_option data type: int*

LDAP_OPT_SERVER_CONTROLS

0x0012

Specifies a default list of LDAP server controls that are sent with each request.

ldap_set_option data type, LDAPControl **; ldap_get_option data type: LDAPControl ***

The application should free memory with ldap_controls_free.

LDAP_OPT_SESSION_REFCNT

0x8001

Returns the reference count associated with the supplied session handle argument.

This is read only.

LDAP_OPT_SIZELIMIT

0x0003

LDAP server sizelimit, determines how many entries are returned from a search. A value of LDAP_NO_LIMIT (0) means no limit. This is a server limit used in all search operations except when overridden by a client timeout in the search_ext functions.

The default is LDAP_NO_LIMIT.

ldap_get_option and ldap_set_option data type: int *

LDAP_OPT_TIMELIMIT

0x0004

LDAP Server timelimit, determines the number of seconds an LDAP server will spend on a search. A value of LDAP_NO_LIMIT (0) means no limit. This value is passed to the LDAP server in the search request. This is a server limit used in all search operations except when overridden by a client timeout in the search_ext functions.

The default is LDAP_NO_LIMIT.

ldap_get_option and ldap_set_option data type: int *

LDAP_OPT_TLS_CIPHER_LIMIT

0x9001

Contains the cipher level and its values:

  • LDAP_TLS_CIPHER_LOW: The key strength is 56 and algorithm is single DES.

  • LDAP_TLS_CIPHER_MEDIUM: The key strength is 128 and algorithm is single RSA.

  • LDAP_TLS_CIPHER_HIGH: The key strength is 168 and algorithm is triple DES.

  • LDAP_TLS_CIPHER_EXPORT: The key strength is 56 and algorithm is SHA.

The default is LDAP_TLS_CIPHER_HIGH.

ldap_get_option and ldap_set_option data type:int