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

Syntax #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, char *dn, LDAPMod *mods[], LDAPControl **serverctrls, LDAPControl **clientctrls, int *msgidp) Threadsafe: Yes

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:

LDAP_MOD_ADD (0x00)

LDAP_MOD_DELETE (0x01)

LDAP_MOD_REPLACE (0x02)

This field also indicates the type of values included in the mod_vals union. For binary data, you must also logically 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 (i.e. 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, modify or delete.

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.

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.

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

Authorities and Locks

No OS/400 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 LDAP Controls for more information about server controls.

clientctrls

(Input) Specifies a list of LDAP client controls. This parameter may be set to null. See LDAP Controls 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 if 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

ldap_modify_ext() will return 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 set from this function.
    CPF3CF2 E  Error(s) occurred during running of ldap_modify_ext API.

Related Information

    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.
    ldap_add_ext() -- Asynchronously add an entry with controls.

The ldap_compare_ext_s() API support LDAP V3 server controls and client controls.