HP OpenVMS Systems Documentation

The ldap_search_ext() function initiates an asynchronous search operation and returns either the constant LDAP_SUCCESS if the request was successfully sent or another LDAP error code if not. See Section 14.18 for more information about possible errors and how to interpret them. If successful, ldap_search_ext() places the message id of the request in *msgidp. A subsequent call to ldap_result() can be used to obtain the results from the search. These results can be parsed using the result parsing functions described in Section 14.18.

Similar to ldap_search_ext() , the ldap_search() function initiates an asynchronous search operation and returns the message id of the operation initiated. As for ldap_search_ext() , a subsequent call to ldap_result() can be used to obtain the result of the search. In case of error, ldap_search() will return -1, setting the session error parameters in the LDAP structure appropriately.

The synchronous ldap_search_ext_s() , ldap_search_s() , and ldap_search_st() functions all 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. See Section 14.18 for more information about possible errors and how to interpret them. Entries returned from the search (if any) are contained in the res parameter. This parameter is opaque to the caller. Entries, attributes, and values should be extracted by calling the parsing functions. The results contained in res should be freed when no longer in use by calling ldap_msgfree() .

The ldap_search_ext() and ldap_search_ext_s() functions support LDAPv3 server controls, client controls, and allow varying size and time limits to be easily specified for each search operation. The ldap_search_st() function is identical to ldap_search_s() except that it takes an additional parameter specifying a local timeout for the search. The local search timeout is used to limit the amount of time the API implementation will wait for a search to complete. After the local search timeout the search operation will return LDAP_TIMEOUT if the search result has not been removed.

14.9.1 Reading and Listing the Children of an Entry

LDAP does not support a read operation directly. Instead, this operation is emulated by a search with base set to the DN of the entry to read, scope set to LDAP_SCOPE_BASE, and filter set to "(objectclass=*)" or NULL. The attrs parameter contains the list of attributes to return.

LDAP does not support a list operation directly. Instead, this operation is emulated by a search with base set to the DN of the entry to list, scope set to LDAP_SCOPE_ONELEVEL, and filter set to "(objectclass=*)" or NULL. The attrs parameter contains the list of attributes to return for each child entry.

14.10 Comparing a Value Against an Entry

The following functions are used to compare a given attribute value assertion against an LDAP entry. There are four variations.

        int ldap_compare_ext( 
                LDAP                              *ld, 
                const char                        *dn, 
                const char                        *attr, 
                const struct berval               *bvalue 
                LDAPControl                       **serverctrls, 
                LDAPControl                       **clientctrls, 
                int                               *msgidp 
        ); 
 
        int ldap_compare_ext_s( 
                LDAP                              *ld, 
                const char                        *dn, 
                const char                        *attr, 
                const struct berval               *bvalue, 
                LDAPControl                       **serverctrls, 
                LDAPControl                       **clientctrls 
        ); 
 
 
 
        int ldap_compare( 
                LDAP                              *ld, 
                const char                        *dn, 
                const char                        *attr, 
                const char                        *value 
        ); 
 
        int ldap_compare_s( 
                LDAP                              *ld, 
                const char                        *dn, 
                const char                        *attr, 
                const char                        *value 
        ); 

Parameters are as follows:

The ldap_compare_ext() function initiates an asynchronous compare operation and returns either the constant LDAP_SUCCESS if the request was successfully sent, or another LDAP error code if not. See Section 14.18 for more information about possible errors and how to interpret them. If successful, ldap_compare_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 compare.

Similar to ldap_compare_ext() , the ldap_compare() function initiates an asynchronous compare operation and returns the message id of the operation initiated. As for ldap_compare_ext() , a subsequent call to ldap_result() can be used to obtain the result of the compare. In case of error, ldap_compare() will return -1, setting the session error parameters in the LDAP structure appropriately.

The synchronous ldap_compare_ext_s() and ldap_compare_s() functions both return the result of the operation, either the constants LDAP_COMPARE_TRUE or LDAP_COMPARE_FALSE if the operation was successful, or another LDAP error code if it was not. See Section 14.18 for more information about possible errors and how to interpret them.

The ldap_compare_ext() and ldap_compare_ext_s() functions support LDAPv3 server controls and client controls.

14.11 Modifying an Entry

The following functions are used to modify an existing LDAP entry. There are four variations.

        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 
        ); 
 
        int ldap_modify_ext_s( 
                LDAP                              *ld, 
                const char                        *dn, 
                LDAPMod                           **mods, 
                LDAPControl                       **serverctrls, 
                LDAPControl                       **clientctrls 
 
        ); 
 
        int ldap_modify( 
                LDAP                              *ld, 
                const char                        *dn, 
                LDAPMod                           **mods 
        ); 
 
        int ldap_modify_s( 
                LDAP                              *ld, 
                const char                        *dn, 
                LDAPMod                           **mods 
        ); 

Parameters are as follows:

The fields in the LDAPMod structure have the following meanings:

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_vals 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.

The ldap_modify_ext() function initiates an asynchronous modify operation and returns the constant LDAP_SUCCESS if the request was successfully sent, or another LDAP error code if not. See Section 14.18 for more information about possible errors and how to interpret them. 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 modify.

Similar to ldap_modify_ext() , the ldap_modify() function initiates an asynchronous modify operation and returns the message id of the operation initiated. As for ldap_modify_ext() , a subsequent call to ldap_result() can be used to obtain the result of the modify. In case of error, ldap_modify() will return -1, setting the session error parameters in the LDAP structure appropriately.

The synchronous ldap_modify_ext_s() and ldap_modify_s() functions 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.

See Section 14.18 for more information about possible errors and how to interpret them.

The ldap_modify_ext() and ldap_modify_ext_s() functions support LDAPv3 server controls and client controls.

14.12 Modifying the Name of an Entry

In LDAP Version 2, the ldap_modrdn() and ldap_modrdn_s() functions were used to change the name of an LDAP entry. They could only be used to change the least significant component of a name (the RDN or relative distinguished name). LDAPv3 provides the Modify DN protocol operation that allows more general name change access. The ldap_rename() and ldap_rename_s() functions are used to change the name of an entry, and the use of the ldap_modrdn() and ldap_modrdn_s() functions is deprecated.

        int ldap_rename( 
                LDAP                              *ld, 
                const char                        *dn, 
                const char                        *newrdn, 
                const char                        *newparent, 
                int                               deleteoldrdn, 
                LDAPControl                       **serverctrls, 
                LDAPControl                       **clientctrls, 
                int                               *msgidp 
        ); 
 
        int ldap_rename_s( 
                LDAP                              *ld, 
                const char                        *dn, 
                const char                        *newrdn, 
                const char                        *newparent, 
                int                               deleteoldrdn, 
                LDAPControl                       **serverctrls, 
                LDAPControl                       **clientctrls 
        ); 

Use of the following functions is deprecated.

        int ldap_modrdn( 
                LDAP                              *ld, 
                char                              *dn, 
                char                              *newrdn, 
                int                               deleteoldrdn 
        ); 
 
        int ldap_modrdn_s( 
                LDAP                              *ld, 
                char                              *dn, 
                char                              *newrdn, 
                int                               deleteoldrdn 
        ); 

Parameters are as follows:

The ldap_rename() function initiates an asynchronous modify DN operation and returns the constant LDAP_SUCCESS if the request was successfully sent, or another LDAP error code if not. See Section 14.18 for more information about possible errors and how to interpret them. If successful, ldap_rename() places the DN message id of the request in *msgidp. A subsequent call to ldap_result() can be used to obtain the result of the rename.

The synchronous ldap_rename_s() returns the result of the operation, either the constant LDAP_SUCCESS if the operation was successful, or another LDAP error code if it was not. See Section 14.18 for more information about possible errors and how to interpret them.

The ldap_rename() and ldap_rename_s() functions both support LDAPv3 server controls and client controls.

14.13 Adding an Entry

The following functions are used to add entries to the LDAP directory. There are four variations.

        int ldap_add_ext( 
                LDAP                               *ld, 
                const char                         *dn, 
                LDAPMod                            **attrs, 
                LDAPControl                        **serverctrls, 
                LDAPControl                        **clientctrls, 
                int                                *msgidp 
        ); 
 
        int ldap_add_ext_s( 
                LDAP                               *ld, 
                const char                         *dn, 
                LDAPMod                            **attrs, 
                LDAPControl                        **serverctrls, 
                LDAPControl                        **clientctrls 
        ); 
 
        int ldap_add( 
                LDAP                               *ld, 
                const char                         *dn, 
                LDAPMod                            **attrs 
        ); 
 
        int ldap_add_s( 
                LDAP                               *ld, 
                const char                         *dn, 
                LDAPMod                            **attrs 
        ); 

Parameters are as follows:

Note that the parent of the entry being added must already exist or the parent must be empty (that is, equal to the root DN) for an add to succeed.

The ldap_add_ext() function initiates an asynchronous add operation and returns either the constant LDAP_SUCCESS if the request was successfully sent or another LDAP error code if not. See Section 14.18 for more information about possible errors and how to interpret them. If successful, ldap_add_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 add.

Similar to ldap_add_ext() , the ldap_add() function initiates an asynchronous add operation and returns the message id of the operation initiated. As for ldap_add_ext() , a subsequent call to ldap_result() can be used to obtain the result of the add. In case of error, ldap_add() will return -1, setting the session error parameters in the LDAP structure appropriately.

The synchronous ldap_add_ext_s() and ldap_add_s() functions 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. See Section 14.18 for more information about possible errors and how to interpret them.

The ldap_add_ext() and ldap_add_ext_s() functions support LDAPv3 server controls and client controls.

14.14 Deleting an Entry

The following functions are used to delete a leaf entry from the LDAP directory. There are four variations.

        int ldap_delete_ext( 
                LDAP                               *ld, 
                const char                         *dn, 
                LDAPControl                        **serverctrls, 
                LDAPControl                        **clientctrls, 
                int                                *msgidp 
        ); 
 
        int ldap_delete_ext_s( 
                LDAP                               *ld, 
                const char                         *dn, 
                LDAPControl                        **serverctrls, 
                LDAPControl                        **clientctrls 
        ); 
 
        int ldap_delete( 
                LDAP                               *ld, 
                const char                         *dn 
        ); 
 
        int ldap_delete_s( 
                LDAP                               *ld, 
                const char                         *dn 
        ); 

Parameters are as follows:

Note that the entry to delete must be a leaf entry (that is, it must have no children). Deletion of entire subtrees in a single operation is not supported by LDAP.

The ldap_delete_ext() function initiates an asynchronous delete operation and returns either the constant LDAP_SUCCESS if the request was successfully sent or another LDAP error code if not. See Section 14.18 for more information about possible errors and how to interpret them. If successful, ldap_delete_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 delete.

Similar to ldap_delete_ext() , the ldap_delete() function initiates an asynchronous delete operation and returns the message id of the operation initiated. As for ldap_delete_ext() , a subsequent call to ldap_result() can be used to obtain the result of the delete. In case of error, ldap_delete() will return -1, setting the session error parameters in the LDAP structure appropriately.

The synchronous ldap_delete_ext_s() and ldap_delete_s() functions 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. See Section 14.18 for more information about possible errors and how to interpret them.

The ldap_delete_ext() and ldap_delete_ext_s() functions support LDAPv3 server controls and client controls.