ldap_modify_ext()--Perform an LDAP Modify Entry Request with Controls

 #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_ext( LDAP           *ld,
                     const char     *dn,
                     LDAPMod        **mods, 
                     LDAPControl    **serverctrls,
                     LDAPControl    **clientctrls, 
                     int            *msgidp)

The ldap_modify_ext() routine initiates an asynchronous modify operation with controls. 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 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, replace, or delete. 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_vals field is NULL. The server should 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 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.

serverctrls

(Input) Specifies a list of LDAP server controls. This parameter may be set to NULL. See Controls for LDAP APIs for more information about server controls.

clientctrls

(Input) Specifies a list of LDAP client controls. This parameter may be set to NULL. See Controls for LDAP APIs for more information about client controls.

msgidp

(output) This result parameter is set to the message id of the request if the ldap_modify_ext() call succeeds.

Return Value

LDAP_SUCCESS

if the request was successfully sent. 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. Once the operation has completed, ldap_result() returns a result that contains the status of the operation (in the form of an error code). The error code indicates whether or not the operation completed successfully. The ldap_parse_result() API is used to check the error code in the result.

another LDAP error code

if the request was not successful.

Error Conditions

The ldap_modify_ext() API will return an LDAP error code if not successful. See LDAP Client API Error Conditions for possible LDAP error code values.

Error Messages

The following message may be sent from this function.

Related Information

• ldap_add_ext() -- Asynchronously add an entry with controls.
• ldap_delete_ext() -- Perform an LDAP delete operation with controls.
• ldap_modify() -- Asynchronous modify to a directory entry.
• ldap_modify_s() -- Synchronous modify to a directory entry.
• 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.

The ldap_modify_ext() API supports LDAP V3 server controls and client controls.

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