LDAP_MODIFY

Use the LDAP_MODIFY API to conduct various LDAP modify operations.

ldap_modify
ldap_modify_ext
ldap_modify_s
ldap_modify_ext_s
ldap_mods_free

Synopsis

#include ldap.h


 typedef struct ldapmod {
        int mod_op;
        char *mod_type;
        union {
        char **modv_strvals;
        struct berval **modv_bvals;
        } mod_vals;
    } LDAPMod;
    #define mod_values mod_vals.modv_strvals
    #define mod_bvalues mod_vals.modv_bvals


int ldap_modify(
       LDAP           *ld,
       const char     *dn,
       LDAPMod        *mods[])

int ldap_modify_ext( 
       LDAP           *ld,
       const char     *dn,
       LDAPMod        *mods[],
       LDAPControl    **serverctrls,
       LDAPControl    **clientctrls,
       int            *msgidp)

int ldap_modify_s(
       LDAP           *ld,
       const char     *dn,;
       LDAPMod        *mods[])

int ldap_modify_ext_s( 
       LDAP           *ld,
       const char     *dn,
       LDAPMod        *mods[],
       LDAPControl    **serverctrls,
       LDAPControl    **clientctrls)

void ldap_mods_free(
       LDAPMod        **mods,
       int            *freemods)

Input parameters

ld: Specifies the LDAP pointer that is returned by a previous call to ldap_init(), ldap_ssl_init(), orldap_open().
dn: Specifies the distinguished name (DN) of the entry to be modified. For more information about DNs, see LDAP distinguished names.
mods: Specifies a NULL-terminated array of entry modifications. Each element of the mods array is a pointer to an LDAPMod structure.
freemods: Specifies whether the mods pointer is to be freed, in addition to the NULL-terminated array of mod structures.
serverctrls: Specifies a list of LDAP server controls. This parameter can be set to NULL. For more information about server controls, see LDAP controls.
clientctrls: Specifies a list of LDAP client controls. This parameter can be set to NULL. For more information about client controls, see LDAP controls.

Output parameters

msgidp: This result parameter is set to the message ID of the request if the ldap_modify_ext() call succeeds.

Usage

The various modify APIs are used to run an LDAP modify operation. DN is the distinguished name of the entry to modify, and mods is a NULL-terminated array of modifications to make to the entry. Each element of the mods array is a pointer to an LDAPMod structure.

The mod_op field is used to specify the type of modification to run and must be one of the following types:

LDAP_MOD_ADD (0x00)
LDAP_MOD_DELETE (0x01)
LDAP_MOD_REPLACE (0x02)

This mod_op field also indicates the type of values that are included in the mod_vals union. For binary data, you must also logically or the operation type with LDAP_MOD_BVALUES (0x80). This type indicates that the values are specified in a NULL-terminated array of struct berval structures. Otherwise, the mod_values are used, that is, the values are assumed to be a NULL-terminated array of NULL-terminated character strings.

The mod_type field specifies the name of the attribute to add, modify, or delete.

The mod_vals field specifies a pointer to a NULL-terminated array of values to add, modify, or delete. Only one of the mod_values or mod_bvalues variants must be used, with mod_bvalues being selected by ORing the mod_op field with the constant LDAP_MOD_BVALUES.

The mod_values array is NULL-terminated. Because the ldap_add() API converts the string from the local code page to UTF-8, the strings must be in the local code page if the LDAP_OPT_UTF8_IO option is set to LDAP_UTF8_XLATE_ON for the connection. If the UTF-8 translation option is not set, the array of strings must be composed of NULL-terminated UTF-8 strings.

Note: US-ASCII is a subset of UTF-8.

mod_bvalues is a NULL-terminated array of berval structures that can be used to pass binary values such as images.

For LDAP_MOD_ADD modifications, the values are added to the entry, creating the attribute if necessary.

For LDAP_MOD_DELETE modifications, the values are deleted from the entry, removing the attribute if no values remain. If the entire attribute is to be deleted, the mod_values field must be set to NULL.

For LDAP_MOD_REPLACE modifications, the attribute has the listed values after the modification, which is created if necessary, or removed when the mod_vals field is NULL.

All modifications are run in the order in which they are listed.

The ldap_modify_ext() API initiates an asynchronous modify operation and returns the constant LDAP_SUCCESS if the request was successfully sent, or it returns another LDAP error code if it is not successful. If successful, ldap_modify_ext() places the message ID of the request in *msgidp. A subsequent call to ldap_result() can be used to obtain the result of the operation. When the operation is complete, ldap_result() returns the status of the operation in the form of an error code. The error code indicates whether the operation completed successfully. The ldap_parse_result() API checks the error code in the result.

The ldap_modify() API initiates an asynchronous modify operation and returns the message ID of this operation. A subsequent call to ldap_result(), can be used to obtain the result of ldap_modify(). If there is an error, ldap_modify() returns -1, which sets the session error parameters in the LDAP structure appropriately. The parameters can be obtained by using ldap_get_errno(). For more information, see LDAP_ERROR.

The synchronous ldap_modify_ext_s() and ldap_modify_s() APIs both return the result of the operation, either the constant LDAP_SUCCESS if the operation was successful, or another LDAP error code if it was not.

The ldap_modify_ext() and ldap_modify_ext_s() APIs support LDAP V3 server controls and client controls.

The ldap_modify_s() API returns the LDAP error code that results from the modify operation. This code can be interpreted by ldap_perror() or ldap_err2string().

The ldap_modify() operation works the same way as ldap_modify_s(), except that it is asynchronous, returning the message ID of the request it initiates, or -1 on error. The result of the operation can be obtained by calling ldap_result().

ldap_mods_free() can be used to free each element of a NULL-terminated array of LDAPMod structures. If freemods is nonzero, the mods pointer is freed as well.

Errors

ldap_modify_s() and ldap_modify_ext_s() return the resulting LDAP error code from the modify operation.

ldap_modify() and ldap_modify_ext() return -1 instead of a valid msgid if an error occurs, setting the session error in the LD structure, which can be obtained by using ldap_get_errno(). For more information, see LDAP_ERROR.