ldap_modify()--Perform an LDAP Modify Entry Request

 #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)

The ldap_modify() API is an asynchronous request. The result of the operation can be obtained by a subsequent call to ldap_result().

The mod_op field is used to specify the type of modification to perform and should be one of the following:

This field also indicates the type of values included in the mod_vals union. For binary data, you must also bitwise OR the operation type with LDAP_MOD_BVALUES (0x80). This indicates that the values are specified in a NULL-terminated array of struct berval structures. Otherwise, the mod_values will be 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 attribute to add, delete, or replace.

The mod_vals field specifies a pointer to a NULL-terminated array of values to add, modify or delete respectively. Only one of the mod_values or mod_bvalues variants should be used, with mod_bvalues being selected by ORing the mod_op field with the constant LDAP_MOD_BVALUES. mod_values is a NULL-terminated array of NULL-terminated strings and 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 given values are added to the entry, creating the attribute if necessary.

For LDAP_MOD_DELETE modifications, the given 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 should be set to NULL. The server will return an error if the attribute doesn't exist.

For LDAP_MOD_REPLACE modifications, the attribute will have the listed values after the modification, having been created if necessary, or removed if the mod_values field is NULL. The server will NOT return an error if the value doesn't exist.

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

Authorities and Locks

No IBM^® i authority is required. All authority checking is done by the LDAP server.

Parameters

ld

(Input) Specifies the LDAP pointer returned by a previous call to ldap_init(), ldap_ssl_init(), or ldap_open().

dn

(Input) Specifies the Distinguished Name (DN) of the entry to be modified.

mods

(Input) Specifies a NULL-terminated array of modifications to make to the entry. Each element of the mods array is a pointer to an LDAPMod structure.

Return Value

Message ID of the Operation Initiated

if the request was successful. A subsequent call to ldap_result(), can be used to obtain the result of the modify.

-1

if the request was not successful.

Error Conditions

If ldap_modify() is not successful, ld_errno will be set to indicate the error. See LDAP Client API Error Conditions for possible LDAP error code values. Use ldap_get_errno() function to retrieve the error information.

Error Messages

The following message may be sent from this function.

Related Information

• ldap_add() -- Asynchronously add an entry.
• ldap_delete() -- Perform an LDAP Delete Operation.
• ldap_modify_s() -- Synchronous modify to a directory entry.
• ldap_modify_ext() -- Asynchronous modify to a directory entry with controls.
• ldap_modify_ext_s() -- Synchronous modify to a directory entry with controls.
• ldap_modrdn() -- Asynchronously modify the RDN of an entry.
• ldap_modrdn_s() -- Synchronously modify the RDN of an entry.

[ Back to top | LDAP APIs | APIs by category ]