LDAP_GET_VALUES

Edit online

Use the LDAP_GET_VALUES API or LDAP routine to fetch or manipulate values that handle routines.

  • ldap_get_values
  • ldap_get_values_len
  • ldap_count_values
  • ldap_count_values_len
  • ldap_value_free
  • ldap_value_free_len

Synopsis

#include ldap.h


  struct berval {
      unsigned long bv_len;
      char *bv_val;
  };


char **ldap_get_values(
          LDAP          *ld,
          LDAPMessage   *entry,
          const char    *attr)

struct berval **ldap_get_values_len(
          LDAP          *ld,
          LDAPMessage   *entry,
          const char    *attr)

int ldap_count_values(
          char          **vals)

int ldap_count_values_len(
          struct berval **bvals)

void ldap_value_free(
          char          **vals)

void ldap_value_free_len(
        struct berval   **bvals)

Input parameters

ld
Specifies the LDAP pointer that is returned by a previous call to ldap_init(), ldap_ssl_init(), or ldap_open().
attr
Specifies the attribute whose values are wanted.
entry
Specifies an LDAP entry as returned from ldap_first_entry() or ldap_next_entry().
vals
Specifies a pointer to a NULL-terminated array of attribute values, as returned by ldap_get_values().
bvals
Specifies a pointer to a NULL-terminated array of pointers to berval structures, as returned by ldap_get_values_len().

Usage

These routines are used to retrieve and manipulate attribute values from an LDAP entry as returned by ldap_first_entry() or ldap_next_entry().

The values of an attribute can be represented in two forms:
  • A NULL-terminated array of strings. This representation is appropriate when the attribute contains string data. For example, a title, description or name.
  • A NULL-terminated array of berval structures. This representation is appropriate when the attribute contains binary data. For example, a JPEG file.
String values

Use ldap_get_values() to obtain attribute values as an array of strings. The ldap_get_values() API takes the entry and the attribute attr whose values are wanted and returns a NULL-terminated array of character strings that represent the attribute values. The attr can be an attribute type as returned from ldap_first_attribute() or ldap_next_attribute(), or if the attribute type is known it can be provided.

The number of values in the array of character strings can be counted by calling ldap_count_values(). The array of values that is returned can be freed by calling ldap_value_free().

If your application is designed to rely on the LDAP library to convert LDAP V3 string data from UTF-8 to the local code page (enabled on a per-connection basis by using the ldap_set_option() API with the LDAP_OPT_UTF8_IO), strings returned in the NULL-terminated array of string values can contain multibyte characters, as defined in the local code page. In this case, the application must use string-handling routines that are properly enabled to handle multibyte strings.

If the attribute values are binary in nature, and thus not suitable to be returned as an array of character strings, the ldap_get_values_len() routine can be used instead. It takes the same parameters as ldap_get_values() but returns a NULL-terminated array of pointers to berval structures, each containing the length of, and a pointer to, a value.

Binary values

The number of values in the array of bervals can be counted by calling ldap_count_values_len(). The array of values that is returned can be freed by calling ldap_value_free_len().

Errors

If an error occurs in ldap_get_values() or ldap_get_values_len(), NULL is returned and the ldap_get_errno() API can be used to obtain the error code. See LDAP_ERROR for a description of possible error codes.

See also

ldap_first_entry, ldap_first_attribute, ldap_error