HELPLIB.HLB  —  LDAP  Search Results
    The following calls are used to parse the entries and references
    returned by ldap_search(). These results are returned in an
    opaque structure that should only be accessed by calling the
    functions. Functions are provided to step through the entries
    and references returned, step through the attributes of an entry,
    retrieve the name of an entry, and retrieve the values associated
    with a given attribute in an entry.

1  –  Stepping Through a List of Entries

    The ldap_first_entry() and ldap_next_entry()  functions are
    used to step through and retrieve the list of entries from a
    search result chain. The ldap_first_reference() and ldap_next_
    reference() functions are used to step through and retrieve the
    list of continuation references from a search result chain. The
    ldap_count_entries() function is used to count the number of
    entries returned. The ldap_count_references() function is used to
    count the number of references returned.

     LDAPMessage *ldap_first_entry( LDAP *ld, LDAPMessage *res );

     LDAPMessage *ldap_next_entry( LDAP *ld, LDAPMessage *entry );

     LDAPMessage *ldap_first_reference( LDAP *ld, LDAPMessage *res );

     LDAPMessage *ldap_next_reference( LDAP *ld, LDAPMessage *ref );

     int ldap_count_entries( LDAP *ld, LDAPMessage *res );

     int ldap_count_references( LDAP *ld, LDAPMessage *res );

    Parameters are as follows:

    ld    The session handle.
    res   The search result, as obtained by a call to one of the
          synchronous search functions or ldap_result().
    entry The entry returned by a previous call to ldap_first_
          entry()  or ldap_next_entry().

    The ldap_first_entry() and ldap_next_entry()  functions will
    return NULL when no more entries or references exist in the
    result set to be returned. NULL is also returned if an error
    occurs while stepping through the entries, in which case the
    error parameters in the session handle ld will be set to indicate
    the error.

    The ldap_count_entries() function returns the number of entries
    contained in a chain of entries. It can also be used to count
    the number of entries that remain in a chain if called with a
    message, entry or reference returned by ldap_first_message(),
    ldap_next_message(), ldap_first_entry(),  ldap_next_entry(),
    ldap_first_reference(), ldap_next_reference().

    The ldap_count_references() function returns the number of
    references contained in a chain of search results. It can also be
    used to count the number of references that remain in a chain.

2  –  Stepping Through the Attributes of an Entry

    The ldap_first_attribute() and ldap_next_attribute()  calls are
    used to step through the list of attribute types returned with an
    entry.

            char *ldap_first_attribute(
                    LDAP                                    *ld,
                    LDAPMessage                             *entry,
                    BerElement                              **ptr
            );

            char *ldap_next_attribute(
                    LDAP                                    *ld,
                    LDAPMessage                             *entry,
                    BerElement                              *ptr
            );

            void ldap_memfree( char *mem );

    Parameters are as follows:

    ld    The session handle.
    entry The entry whose attributes are to be stepped through, as
          returned by ldap_first_entry()  or ldap_next_entry().
    ptr   In ldap_first_attribute(),  the address of a pointer used
          internally to keep track of the current position in the
          entry. In ldap_next_attribute(),  the pointer returned by a
          previous call to ldap_first_attribute().
    mem   A pointer to memory allocated by the LDAP library, such
          as the attribute type names returned by ldap_first_
          attribute()  and ldap_next_attribute(), or the DN returned
          by ldap_get_dn().

    The ldap_first_attribute() and ldap_next_attribute()  functions
    will return NULL when the end of the attributes is reached, or
    if there is an error, in which case the error parameters in the
    session handle ld will be set to indicate the error.

    Both functions return a pointer to an allocated buffer containing
    the current attribute name. This should be freed when no longer
    in use by calling ldap_memfree().

    The ldap_first_attribute() function will allocate and return in
    ptr a pointer to a BerElement used to keep track of the current
    position. This pointer should be passed in subsequent calls to
    ldap_next_attribute() to step through the entry's attributes.
    After a set of calls to ldap_first_attribute() and ldap_next_
    attribute(), if ptr is non-NULL, it should be freed by calling
    ber_free(ptr, 0). Note that it is very important to pass the
    second parameter as 0 (zero) in this call, since the buffer
    associated with the BerElement does not point to separately
    allocated memory.

    The attribute type names returned are suitable for passing in a
    call to ldap_get_values() to retrieve the associated values.

3  –  Retrieving the Values of an Attribute

    The ldap_get_values() and ldap_get_values_len()  functions are
    used to retrieve the values of a given attribute from an entry.
    The ldap_count_values() and ldap_count_values_len()  functions
    are used to count the returned values. The ldap_value_free() and
    ldap_value_free_len() functions are used to free the values.

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

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

            int ldap_count_values( char **vals )

            int ldap_count_values_len( struct berval **vals );

            void ldap_value_free( char **vals );

            void ldap_value_free_len( struct berval **vals );

    Parameters are as follows:

    ld    The session handle.
    entry The entry from which to retrieve values, as returned by
          ldap_first_entry()  or ldap_next_entry().
    attr  The attribute whose values are to be retrieved, as returned
          by ldap_first_attribute()  or ldap_next_attribute(), or a
          caller- supplied string (for example, "mail").
    vals  The values returned by a previous call to ldap_get_
          values()  or ldap_get_values_len().

    Two forms of the various calls are provided. The first form is
    only suitable for use with non-binary character string data. The
    second _len form is used with any kind of data.

    The ldap_get_values() and ldap_get_values_len()  functions return
    NULL if no values are found for attr or if an error occurs.

    The ldap_count_values() and ldap_count_values_len()  functions
    return -1 if an error occurs such as the vals parameter being
    invalid.

    Note that the values returned are dynamically allocated and
    should be freed by calling either ldap_value_free() or ldap_
    value_free_len() when no longer in use.

4  –  Retrieving the Name of an Entry

    The ldap_get_dn() function is used to retrieve the name of an
    entry. The ldap_explode_dn() and ldap_explode_rdn()  functions
    are used to break up a name into its component parts. The ldap_
    dn2ufn() function is used to convert the name into a more user-
    friendly format.

            char *ldap_get_dn( LDAP *ld, LDAPMessage *entry );

            char **ldap_explode_dn( const char *dn, int notypes );

            char **ldap_explode_rdn( const char *rdn, int notypes );

            char *ldap_dn2ufn( const char *dn );

    Parameters are as follows:

    ld         The session handle.
    entry      The entry whose name is to be retrieved, as returned by
               ldap_first_entry() or ldap_next_entry().
    dn         The dn to explode, such as returned by ldap_get_dn().
    rdn        The rdn to explode, such as returned in the components
               of the array returned by ldap_explode_dn().
    notypes    A boolean parameter, if non-zero indicating that the DN
               or RDN components should have their type information
               stripped off (i.e., "cn=Babs" would become "Babs").

    The ldap_get_dn() function will return NULL if there is some
    error parsing the dn, setting error parameters in the session
    handle ld to indicate the error. It returns a pointer to newly
    allocated space that the caller should free by calling ldap_
    memfree() when it is no longer in use.

    The ldap_explode_dn() function returns a NULL-terminated char
    * array containing the RDN components of the DN supplied, with
    or without types as indicated by the notypes parameter. The
    components are returned in the order they appear in the dn. The
    array returned should be freed when it is no longer in use by
    calling ldap_value_free().

    The ldap_explode_rdn() function returns a NULL-terminated char
    * array containing the components of the RDN supplied, with
    or without types as indicated by the notypes parameter. The
    components are returned in the order they appear in the rdn.
    The array returned should be freed when it is no longer in use by
    calling ldap_value_free().

    The ldap_dn2ufn() function converts the DN into the user friendly
    format. The UFN returned is newly allocated space that should be
    freed by a call to ldap_memfree() when no longer in use.

5  –  Retrieving Controls from an Entry

    The ldap_get_entry_controls() function is used to extract LDAP
    controls from an entry.

      int ldap_get_entry_controls(
              LDAP                                    *ld,
              LDAPMessage                             *entry,
              LDAPControl                             ***serverctrlsp
      );

    Parameters are as follows:

    ld             The session handle.
    entry          The entry to extract controls from, as returned by
                   ldap_first_entry() or ldap_next_entry().
    serverctrlsp   This result parameter will be filled in with an
                   allocated array of controls copied out of entry.
                   The control array should be freed by calling
                   ldap_controls_free(). If serverctrlsp is NULL,
                   no controls are returned.

    The ldap_get_entry_controls() function returns an LDAP error code
    that indicates whether the reference could be successfully parsed
    (LDAP_SUCCESS if all goes well).

6  –  Parsing References

    The ldap_parse_reference() function is used to extract referrals
    and controls from a SearchResultReference message.

            int ldap_parse_reference(
                    LDAP                            *ld,
                    LDAPMessage                     *ref,
                    char                            ***referralsp,
                    LDAPControl                     ***serverctrlsp,
                    int                             freeit
            );

    Parameters are as follows:

    ld             The session handle.
    ref            The reference to parse, as returned by ldap_
                   result(), ldap_first_reference(),  or ldap_next_
                   reference().
    referralsp     This result parameter will be filled in with an
                   allocated array of character strings. The elements
                   of the array are the referrals (typically LDAP
                   URLs) contained in ref. The array should be freed
                   when no longer in used by calling ldap_value_
                   free(). If referralsp is NULL, the referral URLs
                   are not returned.
    serverctrlsp   This result parameter will be filled in with an
                   allocated array of controls copied out of ref.
                   The control array should be freed by calling
                   ldap_controls_free(). If serverctrlsp is NULL,
                   no controls are returned.
    freeit         A boolean that determines whether or not the ref
                   parameter is disposed of. Pass any non-zero value
                   to have these functions free ref after extracting
                   the requested information. This option is provided
                   as a convenience; you can also use ldap_msgfree()
                   to free the result later.

    The ldap_parse_reference() function returns an LDAP error code
    that indicates whether the reference could be successfully parsed
    (LDAP_SUCCESS if all goes well).
Close Help