| Platform SDK: Active Directory, ADSI, and Directory Services |
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 sessionwide optional parameters. Call ldap_set_option to set the value of these parameters.
The following options are defined:
| Option Parameters | Descriptions | Output Values |
|---|---|---|
| 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 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_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_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 in Unicode or ANSI, contingent on the use of ldap_get_optionW or ldap_get_optionA, respectively. |
| 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 - 232-1. A value of LDAP_NO_LIMIT (zero) means there is no limit. See also LDAP_OPT_REFERRALs |
| LDAP_OPT_REFERRALS (0x08) | Controls whether or not 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 - 232-1. A value of LDAP_NO_LIMIT (zero) means 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 - 232-1. A value of LDAP_NO_LIMIT (zero) means 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_GETDSNAME_FLAGS (0x3D) | A Microsoft-specific option. | The flags for DsGetDcName: 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_PROMPT_CREDENTIALS (0x3F) | Indicates whether to prompt for credentials. Currently only needed for distributed password authentication (DPA) and Windows NT LAN Manager if no credentials are loaded. A Microsoft-specific option. | |
| 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 the run time waits for the response to come back after sending a ping. | Default value is 2000/10/60000 milliseconds. |