Up to Contents

Back to LDAP Session Handle Options

Working with Controls

LDAPv3 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 is used to represent both types of controls: 

           typedef struct ldapcontrol {
                   char            *ldctl_oid;
                   struct berval   ldctl_value;
                   char            ldctl_iscritical;
           } LDAPControl, *PLDAPControl;

The fields in the ldapcontrol structure have the following meanings:

ldctl_oid
The control type, represented as a string.
ldctl_value
The data associated with the control (if any).
ldctl_iscritical
Indicates whether the control is critical of not. If this field is non-zero, the operation will only be carried out if the control is recognized by the server and/or client.

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: 

           void ldap_control_free( LDAPControl *ctrl );
           void ldap_controls_free( LDAPControl **ctrls );

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 through the use 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 LDAPv3 protocol extension documents; for example, a control has been proposed to support server-side sorting of search results.

The library provides the following definitions of server-side controls: (Specific to this Implementation)

The following helper functions can be used to create and parse paging and sorting controls:

	typedef struct LDAPsortkey {
		char *sk_attrtype;
		char *sk_matchruleoid;
		char sk_reverseorder;
	} LDAPsortkey;

	int ldap_create_sort_control (
		LDAP *ldap,
		LDAPsortkey **keys,
		char isCritical,
		LDAPControl **output
	);

	int ldap_parse_sort_control (
		LDAP *ldap,
		LDAPControl **controls,
		unsigned long *result,
		char **attributes
	);

        int ldap_create_page_control (
                LDAP *ldap,
                unsigned long pagesize,
                struct berval *cookie,
                char isCritical,
                LDAPControl **output
        );

        int ldap_parse_page_control (
                LDAP *ldap,
                LDAPControl **controls,
                unsigned long *totalcount,
                struct berval **cookie
        );

The arguments are as follows:

keys
An array of pointers to caller-allocated LDAPsortkey structures.
isCritical
Whether the resulting control should be marked critical (1 or 0).
output
The control which has been constructed. It should be freed by ldap_control_free() when the caller is done using it.
controls
An array of controls obtained by an earlier call to ldap_parse_result().
result, attributes, cookie and totalcount
These values are as defined in the paging and sorting drafts.

No client controls are defined by this document or implemented by this library, but may be added in future revisions.

Up to Contents

Forward to Authenticating to the Directory