ldap_parse_result()--Extract Information from Results

 #include <ldap.h>
 
 int ldap_parse_result(
       LDAP            *ld,
       LDAPMessage     *res,
       int             *errcodep,
       char            **matcheddnp,
       char            **errmsgp,
       char            ***referralsp,
       LDAPControl     ***servctrlsp,
       int             freeit)

The ldap_parse_result() routine is used to:

• Obtain the LDAP error code field associated with an LDAPMessage res.
• Obtain the portion of the DN that the server recognizes for a failed operation.
• Obtain the text error message associated with the error code returned in an LDAPMessage res.
• Obtain the list of alternate servers from the referrals field.
• Obtain the array of controls that may be returned by the server.

Authorities and Locks

No i5/OS authority is required.

Parameters

ld

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

res

(Input) Specifies the result of an LDAP operation as returned by ldap_result() or one of the synchronous LDAP API operation calls.

errcodep

(Output) Specifies a pointer to the result parameter that will be filled in with the LDAP error code field from the LDAPMessage res. The LDAPResult message is produced by the LDAP server, and indicates the outcome of the operation. NULL can be specified for errcodep if the error code is to be ignored.

matcheddnp

(Output) Specifies a pointer to a result parameter. When LDAP_NO_SUCH_OBJECT is returned as the LDAP error code, this result parameter will be filled in with a Distinguished Name indicating how much of the name in the request was recognized by the server. NULL can be specified for matcheddnp if the matched DN is to be ignored. The matched DN string should be freed by calling ldap_memfree().

errmsgp

(Output) Specifies a pointer to a result parameter that is filled in with the contents of the error message from the LDAPMessage res. The error message string should be freed by calling ldap_memfree().

referralsp

(Output) Specifies a pointer to a result parameter that is filled in with the contents of the referrals field from the LDAPMessage res, 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

(Ourput) Specifies a pointer to a result parameter that is filled in with an allocated array of controls copied out of the LDAPMessage res. 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 res) 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 result was successfully located and parsed.

another LDAP error code

if not successfully parsed.

Error Conditions

The ldap_parse_result() 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_message() -- Retrieve first LDAP message.
• ldap_next_message() -- Retrieve next LDAP message.
• ldap_parse_extended_result() -- Parse extended result.
• ldap_parse_sasl_bind_result() -- Extract server credentials from SASL bind results.
• ldap_result() -- Retrieve result of an asynchronous LDAP operation.