LDAP_FIRST_ATTRIBUTE

Use the LDAP_FIRST_ATTRIBUTE API to step through the LDAP entry attributes.

ldap_count_attributes
ldap_first_attribute
ldap_next_attribute

Synopsis

#include ldap.h


int ldap_count_attributes(
       LDAP           *ld,
       LDAPMessage    *entry)

char *ldap_first_attribute(
       LDAP           *ld,
       LDAPMessage    *entry,
       BerElement     **berptr)

char *ldap_next_attribute(
       LDAP           *ld,
       LDAPMessage    *entry,
       BerElement     *berptr)

Input parameters

ld: Specifies the LDAP pointer that is returned by a previous call to ldap_init(), ldap_ssl_init(), or ldap_open().
entry: Pointer to the LDAPMessage that represents an entry.

Output parameters

berptrs: This parameter is an output parameter that is returned from ldap_first_attribute(). This parameter returns a pointer to a BerElement that is allocated to track the current position. It is an input and output parameter for subsequent calls to ldap_next_attribute(), where it specifies a pointer to a BerElement that is allocated by the previous call to ldap_first_attribute(). The BerElement structure is opaque to the application.

Usage

The ldap_count_attributes() routine returns a count of the number of attributes in an LDAP entry. If a NULL entry is returned from ldap_first_entry() or ldap_next_entry(), and is passed as input to ldap_count_attributes(), -1 is returned.

The ldap_first_attribute() and ldap_next_attribute() routines are used to step through the attributes in an LDAP entry.

ldap_first_attribute() takes an entry as returned by ldap_first_entry() or ldap_next_entry() and returns a pointer to a buffer that contains the first attribute type in the entry.

The pointer that is returned by ldap_first_attribute in berptr must be passed to subsequent calls to ldap_next_attribute and is used to step through the entry attributes. When there are no attributes that are left to be retrieved, ldap_next_attribute() returns NULL and sets the error code to LDAP_SUCCESS. If an error occurs, NULL is returned and an error code is set. The memory that is allocated for the BerElement buffer must be freed by using ldap_ber_free().

Therefore, when NULL is returned, the ldap_get_errno() API must be used to determine whether an error occurs.

If the caller fails to call ldap_next_attribute() enough times to exhaust the list of attributes, the caller is responsible for freeing the BerElement pointed to by berptr when it is no longer needed by calling ldap_ber_free().

The attribute names that are returned by ldap_first_attribute() and ldap_next_attribute() are suitable for inclusion in a call to ldap_get_values().

ldap_next_attribute() returns a string that contains the name of the next type in the entry. This string must be freed by using ldap_memfree() when its use is completed.

The attribute names that are returned by ldap_next_attribute() are suitable for inclusion in a call to ldap_get_values() to retrieve the attribute values.

Errors

If the ldap_first_attribute() call results in an error, then NULL is returned, the error code is set.

The ldap_get_errno() API can be used to obtain the error code. For a description about possible error codes, see LDAP_ERROR.

Notes®

The ldap_first_attribute() and ldap_next_attribute() routines allocate memory that might be required to be freed by the caller through ldap_memfree.