LDAP_FIRST_ENTRY, LDAP_FIRST_REFERENCE

APIs with the _np suffix are preliminary implementations, and are not documented in the Internet Draft, "C LDAP Application Program Interface".

• ldap_first_entry
• ldap_next_entry
• ldap_count_entries
• ldap_get_entry_controls_np
• ldap_first_reference
• ldap_next_reference
• ldap_count_references
• ldap_parse_reference_np

Synopsis

Input parameters

ld

Specifies the LDAP pointer that is returned by a previous call to ldap_init(), ldap_ssl_init(), or ldap_open().

result

Specifies the result that is returned by a call to ldap_result() or one of the synchronous search routines, such as ldap_search_s(), ldap_search_st(), or ldap_search_ext_s().

entry

Specifies a pointer to an entry returned on a previous call to ldap_first_entry() or ldap_next_entry().

serverctrlsp

Specifies a pointer to a result parameter that is provided with an allocated array of controls that are copied out of the LDAPMessage message. The control array must be freed by calling ldap_controls_free().

ref

Specifies a pointer to a search continuation reference returned on a previous call to ldap_first_reference() or ldap_next_reference().

referralsp

Specifies a pointer to a result parameter that is provided with the contents of the referrals field from the LDAPMessage message. The LDAPMessage message indicates zero or more alternative LDAP servers where the request must be tried again. The referrals array must be freed by calling ldap_value_free(). Supply NULL for this parameter to ignore the referrals field.

freeit

Specifies a Boolean value that determines whether the LDAP result chain, as specified by ref, is to be freed. Any nonzero value results in the LDAP result chain that is being freed after the requested information is extracted. Alternatively, the ldap_msgfree() API can be used to free the LDAP result chain later.

Usage

These routines are used to parse results that are received from ldap_result() or the synchronous LDAP search operation routines ldap_search_s(), ldap_search_st(), and ldap_search_ext_s().

Processing entries

The ldap_first_entry() and ldap_next_entry() APIs are used to step through and retrieve the list of entries from a search result chain. When an LDAP operation completes and the result is obtained as described, a list of LDAPMessage structures is returned. This list is denoted as the search result chain. A pointer to the first of these structures is returned by ldap_result() and ldap_search_s().

The ldap_first_entry() routine is used to retrieve the first entry in a chain of search results. It takes the result that is returned by a call to ldap_result(), ldap_search_s(), ldap_search_st(), or ldap_search_ext_s() and returns a pointer to the first entry in the result.

This pointer must be supplied on a subsequent call to ldap_next_entry() to get the next entry, and others, until ldap_next_entry() returns NULL. The ldap_next_entry() API returns NULL when there are no more entries. The entries that are returned from these calls are used in calls to the routines ldap_get_dn(), ldap_first_attribute(), ldap_get_values(), and others.

The ldap_get_entry_controls_np() routine is used to retrieve an array of server controls that are returned in an individual entry in a chain of search results.

Processing continuation references

The ldap_first_reference() and ldap_next_reference() APIs are used to step through and retrieve the list of continuation references from a search result chain. They return NULL when no more continuation references exist in the result that is set to be returned.

The ldap_first_reference() routine is used to retrieve the first continuation reference in a chain of search results. It takes the result as returned by a call to ldap_result(), ldap_search_s(), ldap_search_st(), or ldap_search_ext_s() and returns a pointer to the first continuation reference in the result.

The pointer that is returned from ldap_first_reference() must be supplied on a subsequent call to ldap_next_reference() to get the next continuation reference.

The ldap_parse_reference_np() routine is used to retrieve the list of alternative servers that are returned in an individual continuation reference in a chain of search results. This routine is also used to obtain an array of server controls that are returned in the continuation reference.

Counting entries and references

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

The ldap_count_references() API is used to count the number of continuation references returned. It can also be used to count the number of continuation references that remain in a chain.

Errors

If an error occurs in ldap_first_entry(), ldap_next_entry(), ldap_first_reference(), or ldap_next_reference(), NULL is returned, and ldap_get_errno() API can be used to obtain the error code.

If an error occurs in ldap_count_entries() or ldap_count_references(), -1 is returned, and ldap_get_errno() can be used to obtain the error code. The ldap_get_entry_controls_np() and ldap_parse_reference_np() APIs return an LDAP error code directly. For example, LDAP_SUCCESS if the call was successful, an LDAP error if the call was unsuccessful.

See LDAP_ERROR for a description of possible error codes.

See also

ldap_result(), ldap_search(), ldap_first_attribute(), ldap_get_values(), ldap_get_dn()