Session Options

Session options can be specified after the LDAP session is initialized. The session option constants identify which session options to access.

The LDAP session handle, returned by the ldap_init function, is a pointer to an opaque data type that represents an LDAP session.

In earlier versions of LDAP, this data type was a structure exposed to the caller, and various fields in the structure could be set to control attributes of the session, such as result set size and search time limit.

To protect callers from inevitable changes to this structure, these session attributes are now accessed through a pair of accessor functions.

Call ldap_get_option to access the current value of session-wide optional parameters. In the following list, the Output Values column provides information about the data returned from calling the ldap_get_option function. Call ldap_set_option to set the value of these parameters. For more information about how to use these functions, see Getting and Setting Session Options.

The options, listed in the following list, are defined, where LDAP_OPT_ON = 1 and LDAP_OPT_OFF = 0.

LDAP_OPT_API_INFO

0x00

Sets or retrieves the pointer to an LDAPAPIInfo structure. This structure holds the current API information (including supported extensions).

LDAP_OPT_API_FEATURE_INFO

0x15

Sets or retrieves the pointer to an LDAPAPIFeatureInfo structure. This structure holds data about the extensions supported by the current API.

LDAP_OPT_AREC_EXCLUSIVE

0x98

When connected to the server, an A-Record only DNS lookup is performed on the supplied host string. Use this flag when passing a fully qualified, DNS hostname as opposed to a domain name for the hostname parameter. Using this option can help reduce dial-up traffic for branch sites by avoiding a query to the remote DNS server for SRV records lookup.

Sets or retrieves a ULONG value of either LDAP_OPT_ON or LDAP_OPT_OFF (default).

LDAP_OPT_AUTO_RECONNECT

0x91

Enables/disables auto-reconnect.

Sets or retrieves a ULONG value of either LDAP_OPT_ON (default) or LDAP_OPT_OFF.

LDAP_OPT_CACHE_ENABLE

0x0F

Not supported. Returns LDAP_LOCAL_ERROR when an attempt is made to set or retrieve the value of this parameter.

LDAP_OPT_CACHE_FN_PTRS

0x0D

Not supported. Returns LDAP_LOCAL_ERROR when an attempt is made to set or retrieve the value of this parameter.

LDAP_OPT_CACHE_STRATEGY

0x0E

Not supported. Returns LDAP_LOCAL_ERROR when an attempt is made to set or retrieve the value of this parameter.

LDAP_OPT_CLIENT_CERTIFICATE

0x80

Sets or retrieves the pointer to a QUERYCLIENTCERT callback routine. The routine specifies client certificates while establishing an SSL connection.

LDAP_OPT_DEREF

0x02

Determines how aliases are handled during search.

Constant	Value	Description
LDAP_DEREF_NEVER (default)	0x00	Aliases should never be dereferenced.
LDAP_DEREF_SEARCHING	0x01	Aliases should be dereferenced during the search, but not when locating the base object of the search.
LDAP_DEREF_FINDING	0x02	Aliases should be dereferenced when locating the base object, but not during the search.
LDAP_DEREF_ALWAYS	0x03	Aliases should always be dereferenced.

LDAP_OPT_DESC

0x01

Sets or retrieves the value of the underlying SOCKET descriptor that corresponds to the default LDAP connection.

LDAP_OPT_DNSDOMAIN_NAME

0x3B

Sets or retrieves the pointer to a TCHAR string giving the DNS domain name.

LDAP_OPT_ENCRYPT

0x96

Enables/disables Kerberos encryption prior to binding using the LDAP_AUTH_NEGOTIATE flag. Cannot be used over an SSL connection. NTLM encryption is also supported.

Sets or retrieves a ULONG value of either LDAP_OPT_ON or LDAP_OPT_OFF (default).

LDAP_OPT_ERROR_NUMBER

0x31

Sets or retrieves a ULONG value that contains the code of the most recent LDAP error that occurred for this session.

LDAP_OPT_ERROR_STRING

0x32

Sets or retrieves the pointer to a TCHAR string giving the error message of the most recent LDAP error that occurred for this session. The error string returned by this option should not be freed by the user.

LDAP_OPT_FAST_CONCURRENT_BIND

0x41

Enables fast/concurrent binds on a previously unbound LDAP session. Cannot be enabled if either LDAP_OPT_SIGN or LDAP_OPT_ENCRYPT have been set, and all binds performed in the session must be simple binds once this option is set for a session.

Sets or retrieves a ULONG value of either LDAP_OPT_ON or LDAP_OPT_OFF (default).

LDAP_OPT_GETDSNAME_FLAGS

0x3D

Sets or retrieves a ULONG value that contains flags to control the behavior of the DsGetDcName function.

The flags include:

• DS_FORCE_REDISCOVERY
• DS_DIRECTORY_SERVICE_REQUIRED
• DS_DIRECTORY_SERVICE_PREFERRED
• DS_GC_SERVER_REQUIRED
• DS_PDC_REQUIRED
• DS_WRITABLE_REQUIRED
• DS_FDC_REQUIRED
• DS_IP_REQUIRED
• DS_KDC_REQUIRED
• DS_TIMESERV_REQUIRED
• DS_IS_FLAT_NAME
• DS_IS_DNS_NAME

LDAP_OPT_HOST_NAME

0x30

Sets or retrieves the pointer to a TCHAR string giving the name of the LDAP server associated with the connection. The server-name string returned by this option should not be freed by the user, as it is automatically freed when ldap_unbind is called.

LDAP_OPT_HOST_REACHABLE

0x3E

Indicates whether the server can be reached.

Sets or retrieves a ULONG value of either LDAP_OPT_ON (default) or LDAP_OPT_OFF.

LDAP_OPT_IO_FN_PTRS

0x0B

Not supported. Returns LDAP_LOCAL_ERROR when an attempt is made to get or set the value of this parameter.

LDAP_OPT_PING_KEEP_ALIVE

0x36

Sets or retrieves a ULONG value giving the minimum number of seconds the run time waits, after the last response from the server, before sending a keep-alive ping. The default value is 120 seconds.

LDAP_OPT_PING_LIMIT

0x38

Sets or retrieves a ULONG value giving the number of unanswered pings that the run time sends before closing a connection. The default value is 4.

LDAP_OPT_PING_WAIT_TIME

0x37

Sets or retrieves a ULONG value giving the number of milliseconds that the run time waits for the response to come back after sending a ping. The default value is 2000 milliseconds.

LDAP_OPT_PROMPT_CREDENTIALS

0x3F

Indicates whether to prompt for credentials. Required only for distributed password authentication (DPA) and NTLM if no credentials are loaded.

Sets or retrieves a ULONG value of either LDAP_OPT_ON (default) or LDAP_OPT_OFF.

LDAP_OPT_PROTOCOL_VERSION

0x11

Sets or retrieves a ULONG value that indicates the version of the default LDAP server, either LDAP_VERSION2 or LDAP_VERSION3. If no version is set, the default is LDAP_VERSION2.

LDAP_OPT_VERSION and LDAP_OPT_PROTOCOL_VERSION are equivalent.

LDAP_OPT_VERSION

0x11

Sets or retrieves a ULONG value that indicates the version of the default LDAP server, either LDAP_VERSION2 or LDAP_VERSION3. If no version is set, the default is LDAP_VERSION2.

LDAP_OPT_VERSION and LDAP_OPT_PROTOCOL_VERSION are equivalent.

LDAP_OPT_REBIND_ARG

0x07

Not supported. Returns LDAP_LOCAL_ERROR when an attempt is made to get or set the value of this parameter.

LDAP_OPT_REBIND_FN

0x06

Not supported. Returns LDAP_LOCAL_ERROR when an attempt is made to get or set the value of this parameter.

LDAP_OPT_REF_DEREF_CONN_PER_MSG

0x94

Enables/disables the referencing of the connection on a per message basis. Must be set before calling the ldap_conn_from_msg function.

Sets or retrieves a ULONG value of either LDAP_OPT_ON or LDAP_OPT_OFF (default).

LDAP_OPT_REFERRAL_CALLBACK

0x70

Sets or retrieves the pointer to an LDAP_REFERRAL_CALLBACK structure. This structure contains the default callback routines required when chasing referrals.

LDAP_OPT_REFERRAL_HOP_LIMIT

0x10

The maximum number of referrals that will be followed when automatically chasing a referral for a particular request.

Sets or retrieves a ULONG value in the range between 0 and 2 -1. A value of LDAP_NO_LIMIT (zero) means that there is no limit. For more information, see the LDAP_OPT_REFERRALS session option. The default value is 32.

LDAP_OPT_REFERRALS

0x08

Controls whether the LDAP library automatically follows referrals returned by LDAP servers.

Sets or retrieves one of the following ULONG values:

• LDAP_OPT_ON (default)
• LDAP_OPT_OFF
• LDAP_CHASE_SUBORDINATE_REFERRALS indicates that LDAP should chase subordinate referrals (or references) returned in a search (LDAP 3 or later).
• LDAP_CHASE_EXTERNAL_REFERRALS indicates that LDAP should chase external referrals.

These can be returned on any operation except a bind.

LDAP_OPT_RESTART

0x09

Not supported. Returns LDAP_LOCAL_ERROR when an attempt is made to get or set the value of this parameter.

LDAP_OPT_ROOTDSE_CACHE

0x9A

Enable/disable the internal RootDSE cache.

Sets or retrieves a ULONG value of either LDAP_OPT_ON (default) or LDAP_OPT_OFF.

LDAP_OPT_SASL_METHOD

0x97

Sets or retrieves the preferred SASL binding method prior to binding using the LDAP_AUTH_NEGOTIATE flag.

Sets or retrieves the pointer to a TCHAR string giving the SASL method name. One example is "GSSAPI".

LDAP_OPT_SECURITY_CONTEXT

0x99

Sets or retrieves the security context associated with the current connection.

Sets or retrieves the PCtxtHandle pointer to the CtxtHandle structure.

LDAP_OPT_SEND_TIMEOUT

0x42

A limit on the number of seconds that the local LDAP client will wait while attempting to send data to a remote computer. If the send operation is not completed before the timeout period expires, the LDAP call will fail with an LDAP_TIMEOUT error code.

Sets or retrieves a ULONG value in the range between 0 and 2 -1. A value of LDAP_NO_LIMIT (zero) means that send timeouts are disabled. The default value is 0.

LDAP_OPT_SCH_FLAGS

0x43

Sets or retrieves a ULONG value that contains flags to control the behavior of Schannel. See the SCHANNEL_CRED structure's dwFlags for the possible values. Code automatically sets the appropriate flags (SCH_CRED_AUTO_CRED_VALIDATION, SCH_CRED_MANUAL_CRED_VALIDATION, SCH_CRED_NO_DEFAULT_CREDS and SCH_CRED_USE_DEFAULT_CREDS) for the provided client certificate routine (LDAP_OPT_CLIENT_CERTIFICATE) and server certificate routine (LDAP_OPT_SERVER_CERTIFICATE). Use this option to change the default behavior of Schannel.

LDAP_OPT_SOCKET_BIND_ADDRESSES

0x44

Sets or retrieves a pointer to a TCHAR string containing a list of space-separated addresses to be used by socket bind. For a multihomed machine, use this option to set a particular network interface address to be used for socket bind. Socket bind will be performed before socket connect for the server address. See socket bind for more details.

You should provide both IPv4 and IPv6 local addresses, if available, because both IPv4 and IPv6 server addresses can be used for socket connect. Socket bind will fail if there is an address family mismatch. On the Domain Controller, for the default Server (HostName=NULL), loopback addresses will be used for socket connect. Set loopback addresses (for both IPv4 and IPv6) for this option to work.

This option can only be set before a connection is established. That is, just after ldap_init.

LDAP_OPT_SERVER_CERTIFICATE

0x81

Sets or retrieves the default callback routine for verifying server certificates while establishing an SSL connection.

Sets or retrieves the pointer to a VERIFYSERVERCERT callback routine.

LDAP_OPT_SERVER_ERROR

0x33

Sets or retrieves the pointer to a TCHAR string giving the most recent server error message that occurred for this session.

LDAP_OPT_SERVER_EXT_ERROR

0x34

Provides a Win32 error-code message.

Sets or retrieves a ULONG value giving the most recent Win32 server error that occurred for this session.

LDAP_OPT_SIGN

0x95

Determines the Kerberos signing state or enables Kerberos signing. The LDAP_OPT_SIGN session option should be enabled prior to binding using the LDAP_AUTH_NEGOTIATE flag. Cannot be used over an SSL connection. When used with Windows Server, NTLM signing is also supported.

Sets or retrieves a ULONG value of either LDAP_OPT_ON or LDAP_OPT_OFF (default).

LDAP_OPT_SIZELIMIT

0x03

The limit on the number of entries to return from a search.

Sets or retrieves a ULONG value in the range between 0 and 2 -1. A value of LDAP_NO_LIMIT (zero) indicates that there is no limit (default).

LDAP_OPT_SSL

0x0A

Enables Secure Socket Layer (SSL) on connection.

Sets or retrieves a ULONG value of either LDAP_OPT_ON or LDAP_OPT_OFF (default).

LDAP_OPT_SSL_INFO

0x93

Sets or retrieves data about the current secure connection.

Sets or retrieves the pointer to a valid SecPkgContext_ConnectionInfo structure used to return the security information.

LDAP_OPT_SSPI_FLAGS

0x92

Sets or retrieves a ULONG value giving the flags to pass to the SSPI InitializeSecurityContext function.

LDAP_OPT_TCP_KEEPALIVE

0x40

Turns on TCP keep-alives. This is separate from the ICMP ping keep-alive mechanism (LDAP_OPT_PING_KEEP_ALIVE), and enables the keep-alive mechanism built into the TCP protocol. This has no effect when using connectionless (UDP) LDAP. Keep-alives must be enabled before the connection is established, and last for the duration of the specific LDAP session.

Sets or retrieves a ULONG value of either LDAP_OPT_ON or LDAP_OPT_OFF (default).

LDAP_OPT_THREAD_FN_PTRS

0x05

Not supported. Returns LDAP_LOCAL_ERROR when an attempt is made to get or set the value of this parameter.

LDAP_OPT_TIMELIMIT

0x04

A limit on the number of seconds the server will wait to complete a bind. This also specifies the limit on the number of seconds the server spends on a search.

Sets or retrieves a ULONG value in the range between 0 and 2 -1. A value of 0 (zero) for a bind will cause the server to use its default value of 120 seconds. A value of LDAP_NO_LIMIT (zero) for a search operation means that there is no limit (default).

Requirements

See also

Getting and Setting Session Options