Platform SDK: Active Directory, ADSI, and Directory Services

Using Controls

LDAP 3 operations can be extended through the use of controls. Controls may be sent to a server or returned to the client with any LDAP message. These controls are referred to as server controls.

The LDAP API also supports a client-side extension mechanism through the use of client controls. These controls affect the behavior of the LDAP API only and are never sent to a server. A common data structure, LDAPControl, is used to represent both types of controls:

Some LDAP API calls allocate an LDAPControl structure or a NULL-terminated array of LDAPControl structures. The following routines can be used to dispose of a single control or an array of controls:

A set of controls that affect the entire session can be set using the ldap_set_option function (see above). A list of controls can also be passed directly to some LDAP API calls such as ldap_search_ext, in which case any controls set for the session by means of ldap_set_option are ignored. Control lists are represented as a NULL-terminated array of pointers to LDAPControl structures.

Server controls are defined by LDAP 3 protocol extension documents. For example, a control has been proposed to support server-side sorting of search results.