Up to Contents

Back to Obtaining Results

Handling Errors and Parsing Results

The following calls are used to extract information from results and handle errors returned by other LDAP API routines.

           int ldap_parse_result(
                   LDAP            *ld,
                   LDAPMessage     *res,
                   int             *errcodep,
                   char            **matcheddnp,
                   char            **errmsgp,
                   char            ***referralsp,
                   LDAPControl     ***serverctrlsp,
                   int             freeit
           );

           int ldap_parse_sasl_bind_result(
                   LDAP            *ld,
                   LDAPMessage     *res,
                   struct berval   **servercredp,
                   int             freeit
           );

           int ldap_parse_extended_result(
                   LDAP            *ld,
                   LDAPMessage     *res,
                   char            **resultoidp,
                   struct berval   **resultdata,
                   int             freeit
           );

           char *ldap_err2string( int err );

The use of the following routines is deprecated.

           int ldap_result2error(
                   LDAP            *ld,
                   LDAPMessage     *res,
                   int             freeit
           );

           void ldap_perror( LDAP *ld, char *msg );

Parameters are:

ld

The session handle.

res

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

errcodep

This result parameter will be filled in with the LDAP error code field from the LDAPResult message. This is the indication from the server of the outcome of the operation. NULL may be passed to ignore this field.

matcheddnp

In the case of a return of LDAP_NO_SUCH_OBJECT, this result parameter will be filled in with a DN indicating how much of the name in the request was recognized. NULL may be passed to ignore this field. The matched DN string should be freed by calling ldap_memfree() which is described later in this document.

errmsgp

This result parameter will be filled in with the contents of the error message field from the LDAPResult message. The error message string should be freed by calling ldap_memfree() which is described later in this document. NULL may be passed to ignore this field.

referralsp

This result parameter will be filled in with the contents of the referrals field from the LDAPResult message, indicating zero or more alternate LDAP servers where the request should be retried. The referrals array should be freed by calling ldap_value_free() which is described later in this document. NULL may be passed to ignore this field.

serverctrlsp

This result parameter will be filled in with an allocated array of controls copied out of the LDAPResult message. The control array should be freed by calling ldap_controls_free() which was described earlier.

freeit

A boolean that determines whether the res parameter is disposed of or not. Pass any non-zero value to have these routines free res after extracting the requested information. This is provided as a convenience; you can also use ldap_msgfree() to free the result later.

servercredp

For SASL bind results, this result parameter will be filled in with the credentials passed back by the server for mutual authentication, if given. An allocated berval structure is returned that should be disposed of by calling ldap_ber_free(). NULL may be passed to ignore this field.

resultoidp

For extended results, this result parameter will be filled in with the dotted-OID text representation of the name of the extended operation response. This string should be disposed of by calling ldap_memfree(). NULL may be passed to ignore this field.

resultdatap

For extended results, this result parameter will be filled in with a pointer to a struct berval containing the data in the extended operation response. It should be disposed of by calling ldap_ber_free(). NULL may be passed to ignore this field.

err

For ldap_err2string(), an LDAP error code, as returned by ldap_result2error() or another LDAP API call.

Additional parameters for the deprecated routines are not described. Interested readers are referred to RFC 1823.

All of the ldap_parse_*_result() routines skip over messages of type LDAP_RES_SEARCH_ENTRY and LDAP_RES_SEARCH_REFERENCE when looking for a result message to parse. They return the constant LDAP_SUCCESS if the result was successfully parsed and another LDAP error code if not. Note that the LDAP error code that indicates the outcome of the operation performed by the server is placed in the errcodep ldap_parse_result() parameter.

ldap_err2string() is used to convert a numeric LDAP error code, as returned by one of the ldap_parse_*_result() routines, or one of the synchronous API operation calls, into an informative NULL-terminated character string message describing the error. It returns a pointer to static data.

Up to Contents

Forward to Search Results