LDAP controls

Edit online

Certain LDAP Version 3 operations can be extended with the use of controls. Controls can be sent to a server or returned to the client with any LDAP message. This type of control is called a server control.

The LDAP API also supports a client-side extension mechanism, which can be used to define client controls. The client-side controls affect the behavior of the LDAP client library and are never sent to the server. The client-side controls are not defined for this client library.

A common data structure is used to represent both server-side and client-side controls:

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

The LDAPControl fields have the following definitions:

ldctl_oid: Specifies the control type, represented as a string.
ldctl_value: Specifies the data that is associated with the control. The control might not include data.
ldctl_iscritical: Specifies whether the control is critical or not. If the field is nonzero, the operation is carried out only if it is recognized and supported by the server or the client for client-side controls.

Functions to manipulate controls

The function is to add, remove, or copy controls.

ldap_insert_control
ldap_add_control
ldap_remove_control
ldap_copy_controls

Synopsis

#include ldap.h

int ldap_insert_control(
       LDAPControl *newControl,
       LDAPControl ***ctrlList);

int ldap_add_control( 
       const char *oid, ber_len_t len, 
       char *value,
       int isCritical, 
       LDAPControl ***ctrlList);

int ldap_remove_control( 
       LDAPControl *delControl,
       LDAPControl ***ctrlList, 
       int freeit);

int ldap_copy_controls( 
       LDAPControl ***to_here, 
       LDAPControl **from);

Input parameters

newcontrol: Specifies a control to be inserted into a list of controls.
ctrlList: Specifies a list of LDAP server controls
oid: Specifies the control type, represented as a string.
len: Specifies the length of the value string.
value: Specifies the data that is associated with the control.
isCritical: Specifies whether the control is critical or not.
delControl: Specifies the control to be deleted.
freeit: Specifies whether to free the control. If set to TRUE, the control is freed. If set to FALSE, the control is not freed.
to_here: Specifies the location to which to copy the control list.
from: Specifies the location of the control list to be copied.

Usage

The ldap_insert_control() API inserts the control *newcontrol into a list of controls that are specified by ***ctrlList. The function allocates space in the list for the control, but does not allocate the actual control. Returns LDAP_SUCCESS if the request was successfully sent or LDAP_NO_MEMORY if the control cannot not be inserted.

The ldap_add_control() API creates a control by using the oid, len, value and isCritical values, and inserts it into a list of controls that are specified by ***ctrlList. The function allocates space in the list for the control. Returns LDAP_SUCCESS if the request was successfully sent or LDAP_NO_MEMORY if the control cannot not be added.

The ldap_remove_control() API removes the control from the list. If freeit is not 0, the control is freed. If freeit is set to 0, the control is not freed. Returns LDAP_SUCCESS if the request was successfully sent or LDAP_NO_MEMORY if the control cannot not be removed.

The ldap_copy_controls() API makes a copy of the control list. Returns LDAP_SUCCESS if the request was successfully sent or LDAP_NO_MEMORY if the control list cannot not be copied.