ldap_first_reference()--Retrieve First Continuation Reference in a Chain of Search Results

 #include <ldap.h>
 
 LDAPMessage *ldap_first_reference(LDAP           *ld,
                                   LDAPMessage    *result)

The ldap_first_reference() is used to return the first continuation reference from the search result chain.

Authorities and Locks

No i5/OS authority is required.

Parameters

ld

(Input) The LDAP pointer returned by a previous call to ldap_init(), ldap_ssl_init(), or ldap_open().

result

(Input) The result returned by a call to ldap_result() or one of the synchronous search routines (ldap_search_s(), ldap_search_st(), or ldap_search_ext_s()).

Return Value

LDAPMessage *

Pointer to the first continuation reference. The pointer returned from ldap_first_reference() should be supplied on a subsequent call to ldap_next_reference() to get the next continuation reference.

NULL

when no more continuation references exist in the result set to be returned.

Error Conditions

If ldap_first_reference() is not successful, ld_errno will be set to indicate the error. See LDAP Client API Error Conditions for possible LDAP error code values. Use ldap_get_errno() function to retrieve the error information.

Error Messages

The following message may be sent from this function.

Related Information

• ldap_first_entry() -- Return first entry in a chain of search results.
• ldap_next_entry() -- Return next entry in a chain of search results.
• ldap_count_entry() -- Return number of entry in a chain of search results.
• ldap_get_entry_controls_np() -- Extract server controls from an entry.
• ldap_count_reference() -- Return the number of continuation reference in a chain of search results.
• ldap_next_reference() -- Return next continuation reference in a chain of search results.
• ldap_parse_reference_np() -- Extract information from a continuation reference.