LDAP_COMPARE

Use the LDAP_COMPARE API to do an LDAP compare operation.

ldap_compare
ldap_compare_s
ldap_compare_ext
ldap_compare_ext_s

Synopsis

#include ldap.h


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)

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)

Input parameters

ld: Specifies the LDAP pointer that is returned by a previous call to ldap_init(), ldap_ssl_init(), or ldap_open().
dn: Specifies the DN of the entry on which to run the comparison.
attr: Specifies the attribute type to use in the comparison.
bvalue: Specifies the attribute value to compare against the entry value. This parameter is used in the ldap_compare_ext and ldap_compare_ext_s routines, and is a pointer to a struct berval, making it possible to compare binary values. See LDAP_GET_VALUES.
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_compare_ext() call succeeds.

Usage

The various LDAP compare routines are used to run LDAP compare operations. They take dn, the DN of the entry upon which to run the compare, and attr and value, the attribute type, and value to compare to those routines found in the entry.

The ldap_compare_ext() API initiates an asynchronous compare operation and returns the constant LDAP_SUCCESS if the request was successfully sent, or another LDAP error code if it was not successfully sent. If successful, ldap_compare_ext() places the message ID of the request in *msgidp. A subsequent call to ldap_result() obtains the result of the operation. After the operation completes, ldap_result() returns the status of the operation in the form of an error code. The error code indicates whether the operation completed successfully (LDAP_COMPARE_TRUE or LDAP_COMPARE_FALSE).

Similarly, the ldap_compare() API initiates an asynchronous compare operation and returns the message ID of that operation. Use a subsequent call to ldap_result() to obtain the result of the compare. If there is an error, ldap_compare() returns -1, setting the session error parameters in the LDAP structure appropriately. The session error parameters can be obtained by using ldap_get_errno().

See LDAP_ERROR for more details.

Use the synchronous ldap_compare_s() and ldap_compare_ext_s APIs to run LDAP compare operations. These APIs return an LDAP error code, which can be LDAP_COMPARE_TRUE if the entry contains the attribute value and LDAP_COMPARE_FALSE if it does not. Otherwise, some error code is returned.

The ldap_compare_ext() and ldap_compare_ext_s() APIs both support LDAP V3 server controls and client controls.

Errors