ldap_parse_reference_np()--Extract Information from a Continuation Reference

 #include <ldap.h>
 
 int ldap_parse_reference_np(LDAP           *ld,
                            LDAPMessage    *ref,
                            char           ***referralsp,
                            LDAPControl    ***serverctrlsp,
                            int            freeit)

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

Note the suffix "_np" which shows the API is in a preliminary implementation, and is not documented in the Internet Draft. The internet community may standardize this API in the future.

Authorities and Locks

No IBM^® i authority is required.

Parameters

ld

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

ref

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

referralsp

(Output) Specifies a pointer to a result parameter that is filled in with the contents of the referrals field from the LDAPMessage ref, indicating zero or more alternate LDAP servers where the request should be retried. The referrals array should be freed by calling ldap_value_free(). NULL may be supplied for this parameter to ignore the referrals field.

serverctrlsp

(Input) Specifies a pointer to a result parameter that is filled in with an allocated array of controls copied out of the LDAPMessage ref. The control array should be freed by calling ldap_controls_free().

freeit

(Input) Specifies a boolean value that determines if the LDAP result chain (as specified by ref) is to be freed. Any non-zero value will result in the LDAP result chain being freed after the requested information is extracted. Alternatively, the ldap_msgfree() API can be used to free the LDAP result chain at a later time.

Return Value

LDAP_SUCCESS

if the call was successful.

another LDAP error code

if the call was not successful.

Error Conditions

The ldap_parse_reference_np() function will return an LDAP error code if not successful. See LDAP Client API Error Conditions for possible LDAP error code values.

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_first_reference() -- Return first continuation reference in a chain of search results.
• ldap_next_reference() -- Return next continuation reference in a chain of search results.

[ Back to top | LDAP APIs | APIs by category ]