Session Options

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 protecting callers from inevitable changes to this structure, these aspects of the session are now accessed through a pair of accessor functions.

Call ldap_get_option to access the current value of sessionwide optional parameters. In the following table, 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 the code example that follows the table.

The following options are defined, where LDAP_OPT_ON = 1 and LDAP_OPT_OFF = 0.

The following 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. This is because an LDAP server located behind a firewall may be incorrectly detected as being down by the runtime, because it fails to respond to pings, when it is being slow to respond to requests. To avoid this, you can turn off ICMP pings by setting LDAP_OPT_PING_LIMIT to zero. TCP keep-alives can be used instead.

The following options are Microsoft-specific.

The folowing code example shows how to retrieve some of the default values for the option settings described in the preceding table.

//--------------------------------------------------------
// Retreiving Session Options
//--------------------------------------------------------

#include <windows.h>
#include <winldap.h>
#include <stdio.h>

int main(int argc, char* argv[])
{
	PCHAR hostName = "rhadsidoc.fabrikam.com";
	LDAP* pLdapConnection = NULL;
	ULONG option = 0;
	ULONG getOptSuccess = 0;
	ULONG connectSuccess = 0;
	PCHAR pOptionChar = NULL;
	LDAPAPIInfo myInfo;
	LDAPAPIInfo* pMyInfo = &myInfo;


	//-----------------------------------------------------------
	// Initialize a session. LDAP_PORT is the default port, 389.
	//-----------------------------------------------------------
	pLdapConnection = ldap_init(hostName, LDAP_PORT);

	if (pLdapConnection == NULL)
		printf( "ldap_init failed with 0x%x.\n",GetLastError());
	else
		printf("ldap_init succeeded \n");

	//--------------------------------------------------------
	// Connect to the server
	//--------------------------------------------------------
	connectSuccess = ldap_connect(pLdapConnection, NULL);

	if(connectSuccess == LDAP_SUCCESS)
		printf("ldap_connect succeeded \n");
	else
	{
		printf("ldap_connect failed with 0x%x.\n",connectSuccess);
		goto error_exit;
}

	//---------------------------------------------------------
	// Get the LDAP version used in this session
	//---------------------------------------------------------
	getOptSuccess = ldap_get_option(pLdapConnection,
									 LDAP_OPT_PROTOCOL_VERSION,
									 (void*) &option);

	if(getOptSuccess == LDAP_SUCCESS)
		printf("The current LDAP version number is %d \n", option);
	else
	{
		printf("ldap_get_option failed with 0x%x.\n",getOptSuccess);
		goto error_exit;
}

	//---------------------------------------------------------
	// Get LDAP_OPT_API_INFO
	//---------------------------------------------------------
	pMyInfo->ldapai_info_version = LDAP_API_INFO_VERSION;
	getOptSuccess = ldap_get_option(pLdapConnection,
									 LDAP_OPT_API_INFO,
									 (void*) pMyInfo);

	if(getOptSuccess == LDAP_SUCCESS)
	{
		printf("LDAP Revision Number is %d \n", 
									pMyInfo->ldapai_api_version);
		printf("Highest LDAP Version Supported is %d \n", 
									pMyInfo->ldapai_protocol_version);
		printf("The Vendor Name is %s \n", 
									pMyInfo->ldapai_vendor_name);
		printf("The Vendor Version is %d \n", 
									pMyInfo->ldapai_vendor_version);  
}
	else
	{
		printf("Get LDAP_OPT_API_INFO failed with 0x%x.\n",
												getOptSuccess);
		goto error_exit;
}

	//---------------------------------------------------------
	// Get LDAP_OPT_AREC_EXCLUSIVE.
	//---------------------------------------------------------
	getOptSuccess = ldap_get_option(pLdapConnection,
									 LDAP_OPT_AREC_EXCLUSIVE,
									 (void*) &option);

	if(getOptSuccess == LDAP_SUCCESS)
		printf("LDAP_OPT_AREC_EXCLUSIVE is %d \n", option);
	else
	{
		printf("ldap_get_option failed with 0x%x.\n",getOptSuccess);
		goto error_exit;
}

	//---------------------------------------------------------
	// Get LDAP_OPT_DEREF
	//---------------------------------------------------------
	getOptSuccess = ldap_get_option(pLdapConnection,
									 LDAP_OPT_DEREF,
									 (void*) &option);

	if(getOptSuccess == LDAP_SUCCESS)
		printf("LDAP_OPT_DEREF is %d \n", option);
	else
	{
		printf("ldap_get_option failed with 0x%x.\n",getOptSuccess);
		goto error_exit;
}

	//---------------------------------------------------------
	// Get LDAP_OPT_HOST_NAME
	//---------------------------------------------------------
	getOptSuccess = ldap_get_option(pLdapConnection,
									 LDAP_OPT_HOST_NAME,
									 (void*) &pOptionChar);

	if(getOptSuccess == LDAP_SUCCESS)
		printf("LDAP_OPT_HOST_NAME is %s \n", pOptionChar);
	else
	{
		printf("ldap_get_option failed with 0x%x.\n",getOptSuccess);
		goto error_exit;
}

	//---------------------------------------------------------
	// Get LDAP_HOST_REACHABLE
	//---------------------------------------------------------
	getOptSuccess = ldap_get_option(pLdapConnection,
									 LDAP_OPT_HOST_REACHABLE,
									 (void*) &option);

	if(getOptSuccess == LDAP_SUCCESS)
		printf("LDAP_OPT_HOST_REACHABLE is %d \n", option);
	else
	{
		printf("ldap_get_option failed with 0x%x.\n",getOptSuccess);
		goto error_exit;
}

	//---------------------------------------------------------
	// Get LDAP_OPT_REFERRAL_HOP_LIMIT
	//---------------------------------------------------------
	getOptSuccess = ldap_get_option(pLdapConnection,
									 LDAP_OPT_REFERRAL_HOP_LIMIT,
									 (void*) &option);

	if(getOptSuccess == LDAP_SUCCESS)
		printf("LDAP_OPT_REFERRAL_HOP_LIMIT is %d \n", option);
	else
	{
		printf("ldap_get_option failed with 0x%x.\n",getOptSuccess);
		goto error_exit;
}

	//---------------------------------------------------------
	// Get LDAP_OPT_REFERRALS
	//---------------------------------------------------------
	getOptSuccess = ldap_get_option(pLdapConnection,
									 LDAP_OPT_REFERRALS,
									 (void*) &option);

	if(getOptSuccess == LDAP_SUCCESS)
		printf("LDAP_OPT_REFERRALS is %d \n", option);
	else
	{
		printf("ldap_get_option failed with 0x%x.\n",getOptSuccess);
		goto error_exit;
}

	//---------------------------------------------------------
	// Get LDAP_OPT_SIZELIMIT
	//---------------------------------------------------------
	getOptSuccess = ldap_get_option(pLdapConnection,
									 LDAP_OPT_SIZELIMIT,
									 (void*) &option);

	if(getOptSuccess == LDAP_SUCCESS)
		printf("LDAP_OPT_SIZELIMIT is %d \n", option);
	else
	{
		printf("ldap_get_option failed with 0x%x.\n",getOptSuccess);
		goto error_exit;
}

	//---------------------------------------------------------
	// Get LDAP_OPT_SSL
	//---------------------------------------------------------
	getOptSuccess = ldap_get_option(pLdapConnection,
									 LDAP_OPT_SSL,
									 (void*) &option);

	if(getOptSuccess == LDAP_SUCCESS)
		printf("LDAP_OPT_SSL is %d \n", option);
	else
	{
		printf("ldap_get_option failed with 0x%x.\n",getOptSuccess);
		goto error_exit;
}

	//---------------------------------------------------------
	// Get LDAP_OPT_TIMELIMIT
	//---------------------------------------------------------
	getOptSuccess = ldap_get_option(pLdapConnection,
									 LDAP_OPT_TIMELIMIT,
									 (void*) &option);

	if(getOptSuccess == LDAP_SUCCESS)
		printf("LDAP_OPT_TIMELIMIT is %d \n", option);
	else
	{
		printf("ldap_get_option failed with 0x%x.\n",getOptSuccess);
		goto error_exit;
}

	//---------------------------------------------------------
	// Get LDAP_OPT_AUTO_RECONNECT
	//---------------------------------------------------------
	getOptSuccess = ldap_get_option(pLdapConnection,
									 LDAP_OPT_AUTO_RECONNECT,
									 (void*) &option);

	if(getOptSuccess == LDAP_SUCCESS)
		printf("LDAP_OPT_AUTO_RECONNECT is %d \n", option);
	else
	{
		printf("ldap_get_option failed with 0x%x.\n",getOptSuccess);
		goto error_exit;
}

	//---------------------------------------------------------
	// Get LDAP_OPT_PROMPT_CREDENTIALS
	//---------------------------------------------------------
	getOptSuccess = ldap_get_option(pLdapConnection,
									 LDAP_OPT_PROMPT_CREDENTIALS,
									 (void*) &option);

	if(getOptSuccess == LDAP_SUCCESS)
		printf("LDAP_OPT_PROMPT_CREDENTIALS is %d \n", option);
	else
	{
		printf("ldap_get_option failed with 0x%x.\n",getOptSuccess);
		goto error_exit;
}
	//----------------------------------------------------------
	// Normal cleanup and exit
	//----------------------------------------------------------
	ldap_unbind(pLdapConnection);
	ldap_memfree(pOptionChar);

	return 0;

	//----------------------------------------------------------
	// On error cleanup and exit
	//----------------------------------------------------------
error_exit:
	ldap_unbind(pLdapConnection);
	ldap_memfree(pOptionChar);
	return -1;
}

The following list shows the command line output from the preceding code example.

ldap_init succeeded
ldap_connect succeeded
The current LDAP version number is 2
LDAP Revision Number is 2004
Highest LDAP Version Supported is 3
The Vendor Name is Microsoft Corporation.
The Vendor Version is 510
LDAP_OPT_AREC_EXCLUSIVE is 0
LDAP_OPT_DEREF is 0
LDAP_OPT_HOST_NAME is rhadsidoc.fabrikam.com
LDAP_OPT_HOST_REACHABLE is 1
LDAP_OPT_REFERRAL_HOP_LIMIT is 32
LDAP_OPT_REFERRALS is 1
LDAP_OPT_SIZELIMIT is 0
LDAP_OPT_SSL is 0
LDAP_OPT_TIMELIMIT is 0
LDAP_OPT_AUTO_RECONNECT is 1
LDAP_OPT_PROMPT_CREDENTIALS is 1