Up to Contents

Back to Initializing an LDAP Session

LDAP Session Handle Options

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.

In the interest of insulating callers from inevitable changes to this structure, these aspects of the session are now accessed through a pair of accessor functions, described below.

ldap_get_option() is used to access the current value of various session-wide parameters. ldap_set_option() is used to set the value of these parameters.

           int ldap_get_option(
                   LDAP            *ld,
                   int             option,
                   void            *outvalue
           );

           int ldap_set_option(
                   LDAP            *ld,
                   int             option,
                   void            *invalue
           );

Parameters are:

ld

The session handle.

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 value of the constant is listed in hexadecimal in parentheses followed by the type of the corresponding outvalue or invalue parameter.

LDAP_OPT_DESC (0x01) int *

The underlying socket descriptor corresponding to the default LDAP connection.

LDAP_OPT_DEREF (0x02) int *

Controls 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_SIZELIMIT (0x03) int *

A limit on the number of entries to return from a search. A value of zero means no limit.

LDAP_OPT_TIMELIMIT (0x04) int *

A limit on the number of seconds to spend on a search. A value of zero means no limit

LDAP_OPT_REFERRALS (0x08) void *

This option controls whether the LDAP library automatically follows referrals returned by LDAP servers or not. It can be set to one of the constants LDAP_OPT_ON or LDAP_OPT_OFF.

LDAP_OPT_PROTOCOL_VERSION (0x11) int *

This option indicates the version of the default LDAP server. It can 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_CONTROLS (0x12) LDAPControl **

A default list of LDAP server controls to be sent with each request. See the Using Controls section below.

LDAP_OPT_CLIENT_CONTROLS (0x13) LDAPControl **

A default list of client controls that affect the LDAP session. See the Using Controls section below.

LDAP_OPT_HOST_NAME (0x30) char **

The host name of the default LDAP server.

LDAP_OPT_ERROR_NUMBER (0x31) int *

The code of the most recent LDAP error that occurred for this session.

LDAP_OPT_ERROR_STRING (0x32) char **

The message returned with the most recent LDAP error that occurred for this session.

LDAP_OPT_TLS_CERT_REQUIRED (0x5ba00001) void *

Set to LDAP_OPT_ON if the client library should require a server certificate be present when ldap_tls_start() is next called.

LDAP_OPT_TLS_VERIFY_REQUIRED (0x5ba0002) void *

Set to LDAP_OPT_ON if the client library should require a server certificate path be validiated when ldap_tls_start() is next called.

LDAP_OPT_TLS_CERT_FILE (0x5ba0003) char *

Set to the name of a file containing the client's certificate for use by ldap_tls_start().

LDAP_OPT_TLS_PKEY_FILE (0x5ba0004) char *

Set to the name of a file containing the client's private key for use by ldap_tls_start().

LDAP_OPT_TLS_CA_FILE (0x5ba0005) char *

Set to the name of a file containing CA public keys used for validiation of the server by ldap_tls_start().

LDAP_OPT_TLS_CA_PATH (0x5ba0006) char *

Set to the name of a directory on disk containing CA public key files used for validiation of the server by ldap_tls_start().

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.

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.

Options numbered over 0x5ba00000 are specific to this implementation.

Up to Contents

Forward to Working with Controls