Session Options
A version of this page is also available for
4/8/2010
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 aspects of the session, such as the size of result sets 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.
Call ldap_get_option to access the current value of session-wide optional parameters. Call ldap_set_option to set the value of these parameters.
The options are described in the following table.
| Option parameters | Descriptions | Output values |
|---|---|---|
LDAP_OPT_AREC_EXCLUSIVE (0x98) |
Performs an A-Record only DNS lookup on the supplied host string. This prevents false DNS queries from being generated when resolving host names. Use this flag whenever passing a host name as opposed to a domain name for the hostname parameter. This is a Microsoft-specific option. |
LDAP_OPT_ON or LDAP_OPT_OFF. |
LDAP_OPT_DEREF (0x02) |
Determines how aliases are handled during search. |
LDAP_DEREF_NEVER (0x00) LDAP_DEREF_SEARCHING (0x01) LDAP_DEREF_FINDING (0x02) LDAP_DEREF_ALWAYS (0x03). The LDAP_DEREF_SEARCHING value means that aliases should be dereferenced during the search but not when locating the base object of the search. The LDAP_DEREF_FINDING value means that aliases should be dereferenced when locating the base object but not during the search. |
LDAP_OPT_DESC (0x01) |
The underlying socket descriptor corresponding to the default LDAP connection. |
The value of the socket. |
LDAP_OPT_ERROR_NUMBER (0x31) |
Provides an error code. This is a Microsoft-specific option. |
The code of the most recent LDAP error that occurred for this session. |
LDAP_OPT_ERROR_STRING (0x32) |
Provides an error message. This is a Microsoft-specific option. |
The message returned with the most recent LDAP error that occurred for this session. |
LDAP_OPT_SERVER_ERROR (0x33) |
Provides an error message. This is a Microsoft-specific option |
The message returned with the most recent server error that occurred for this session. |
LDAP_OPT_SERVER_EXT_ERROR (0x34) |
Provides a Win32 error code message. This is a Microsoft-specific option. |
The message returned with the most recent Win32 server error that occurred for this session. |
LDAP_OPT_HOST_NAME (0x30) |
Specifies the default LDAP server. This is a Microsoft-specific option. |
The host name of the default LDAP server. Returns the host name of the server. The server-name string returned by this option should not be freed by the user because it is automatically freed when ldap_unbind is called |
LDAP_OPT_HOST_REACHABLE (0x3E) |
This is a Microsoft-specific option. |
LDAP_ON or LDAP_OFF. |
LDAP_OPT_PROTOCOL_VERSION or LDAP_OPT_VERSION (0x11) |
Indicates the version of the default LDAP server |
LDAP_VERSION2 or LDAP_VERSION3. If no version is set, the default is LDAP_VERSION2. |
LDAP_OPT_REFERRAL_HOP_LIMIT ( 0x10) |
The number of referrals to allow. |
0-0xFFFFFFFF. A value of LDAP_NO_LIMIT (zero) means that there is no limit. See also LDAP_OPT_REFERRALs. |
LDAP_OPT_REFERRALS (0x08) |
Controls whether the LDAP library automatically follows referrals returned by LDAP servers. |
LDAP_OPT_ON LDAP_OPT_OFF A value of LDAP_CHASE_SUBORDINATE_REFERRALS indicates that LDAP should chase subordinate referrals (or references) returned in a search (LDAP 3 or later). A value of 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 |
Not supported. |
LDAP_OPT_SIZELIMIT (0x03) |
A limit on the number of entries to return from a search. |
0-0xFFFFFFFF. A value of LDAP_NO_LIMIT (zero) means that there is no limit. |
LDAP_OPT_SSL (0x0a) |
Enables Secure Socket Layer on connection. |
LDAP_OPT_ON or LDAP_OPT_OFF. |
LDAP_OPT_TIMELIMIT (0x04) |
A limit on the number of seconds the server spends on a search. |
0-0xFFFFFFFF. A value of LDAP_NO_LIMIT (zero) means that there is no limit. |
The next three options control the keep-alive logic. Keep-alive requests are sent as Internet Control Message Protocol (ICMP) request messages, which currently do not go through firewalls. To disable the keep-alive logic, set any of the options (PING_KEEP_ALIVE, PING_LIMIT, or PING_WAIT_TIME) to zero.
| Option parameters | Descriptions | Output values |
|---|---|---|
LDAP_OPT_AUTO_RECONNECT (0x91) |
Enables/disables auto-reconnect. A Microsoft-specific option. |
|
LDAP_OPT_DNSDOMAIN_NAME (0x3B) |
A Microsoft-specific option. |
The DNS host name. |
LDAP_OPT_PROMPT_CREDENTIALS (0x3F) |
Indicates whether to prompt for credentials. Currently needed only for distributed password authentication (DPA) and Windows® NT® LAN Manager if no credentials are loaded. A Microsoft-specific option. |
|
LDAP_OPT_SIGN : ULONG |
Enables or disables Kerberos signing before binding by using the LDAP_AUTH_NEGOTIATE flag. This option cannot be used over an SSL connection. > [!NOTE] > Windows Embedded CE only supports signing when the LDAP_AUTH_NEGOTIATE flag is used. |
LDAP_OPT_ON or LDAP_OPT_OFF (default) |
LDAP_OPT_SSPI_FLAGS (0x92) |
Flags to pass to the SSPI function InitializeSecurityContext. A Microsoft-specific option. |
|
PING_KEEP_ALIVE (0x36) |
The minimum number of seconds the run time waits, after the last response from the server, before sending a keep-alive ping. |
Default value is 120/5/maxInt seconds. |
PING_LIMIT (0x38) |
The number of unanswered pings that the run time sends before closing a connection. |
4/0/maxInt. |
PING_WAIT_TIME (0x37) |
The number of milliseconds that the run time waits for the response to come back after sending a ping. |
Default value is 2000/10/60000 milliseconds. |
Requirements
| Header | winldap.h |
| Windows Embedded CE | Windows CE .NET 4.0 and later |
| Windows Mobile | Windows Mobile Version 5.0 and later |
See Also
Reference
ldap_get_option
ldap_init
ldap_set_option