Microsoft KB Archive/298741

{|
 * width="100%"|

HOWTO: Use LDAP API Timeouts

 * }

Q298741

-

The information in this article applies to:


 * Microsoft Lightweight Directory Access Protocol (LDAP) API

-

SUMMARY
Many of the LDAP API functions support the use of a timeout. The timeout limits the amount of time the function will spend attempting completion. This article describes how to properly use this timeout option.

MORE INFORMATION
A timeout can be set on the LDAP session to serve as a default. This session timeout will be used to limit the execution time of those functions that do not expose a timeout parameter, or when a null value is specified as a parameter for those functions that do expose a timeout. The exception to this is a bind operation, which has a fixed timeout of 30 seconds. The default session timeout can be set by using the ldap_set_option function. The example below shows a 10-second timeout:

LDAP *ldap = NULL; ULONG timeout = 10; ULONG err = LDAP_SUCCESS;

ldap = ldap_init(&quot;MyServer&quot;, LDAP_PORT); err = ldap_set_option( ldap, LDAP_OPT_TIMELIMIT, (void *) &timeout); // ...

Several of the LDAP API functions expose a timeout parameter. Specifying a timeout in a function will override the default session timeout. The timeout value is specified in the structure below:

typedef struct l_timeval { LONG    tv_sec; LONG   tv_usec; } LDAP_TIMEVAL, * PLDAP_TIMEVAL; where the tv_sec element is the number of seconds and the tv_usec element is the number of microseconds of the timeout. If the timeout is specified, both elements of the structure must be initialized before being passed into the LDAP API function. If the entire structure is not initialized it can cause undesirable and unpredictable results. The following are two examples of using timeouts in the LDAP API. The function ldap_connect is used in the examples, but the same methodology applies to other functions that support a timeout.

No Timeout
// assumes valid LDAP* of ldap

err = ldap_set_option(ldap, LDAP_OPT_TIMELIMIT, LDAP_NO_LIMIT ); // make sure there is not default timeout // insert code here to check err value err = ldap_connect( ldap, NULL );

Explicit Timeout of 20 Seconds
// assumes valid LDAP* of ldap

LDAP_TIMEVAL timeValue; timeValue.tv_sec = 20 ; timeValue.tv_usec = 0;

err = ldap_connect( ldap, &timeValue );