HELPLIB.HLB  —  LDAP  Errors
    The following calls are used to extract information from results
    and handle errors returned by other LDAP API functions. Note that
    ldap_parse_sasl_bind_result() and ldap_parse_extended_result()
    must typically be used in addition to ldap_parse_result() to
    retrieve all the result information from SASL bind and extended
    operations, respectively.

            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 functions is deprecated.

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

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

    Parameters are as follows:

    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 LDAPMessage result.
                   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().
    errmsgp        This result parameter will be filled in with the
                   contents of the error message field from the
                   LDAPMessage result. The error message string
                   should be freed by calling ldap_memfree(). 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
                   LDAPMessage result, 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 passed to
                   ignore this field.
    serverctrlsp   This result parameter will be filled in with an
                   allocated array of controls copied out of the
                   LDAPMessage result. The control array should be
                   freed by calling ldap_controls_free().
    freeit         A boolean that determines whether or not the res
                   parameter is disposed of. Pass any non-zero value
                   to have these functions free res after extracting
                   the requested information. This option is provided
                   as a convenience; you can also use ldap_msgfree()
                   to free the result later. If freeit is non-zero,
                   the entire chain of messages represented by res is
                   disposed of.
    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 ber_bvfree(). 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 ber_
                   bvfree(). NULL may be passed to ignore this field.
    err            For ldap_err2string(), an LDAP error code, as
                   returned by ldap_parse_result() or another LDAP
                   API call.

    Additional parameters for the deprecated functions are not
    described. See RFC 1823 for more information.

    All three of the ldap_parse_*_result() functions skip over
    messages of type LDAP_RES_SEARCH_ENTRY and LDAP_RES_SEARCH_
    REFERENCE when looking for a result message to parse. They return
    either the constant LDAP_SUCCESS if the result was successfully
    parsed or 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. If a chain of messages that contains more than one
    result message is passed to these functions, they always operate
    on the first result in the chain.

    The ldap_err2string() function is used to convert a numeric LDAP
    error code, as returned by either one of the three ldap_parse_*_
    result() functions or one of the synchronous API operation calls,
    into an informative zero-terminated character string message
    describing the error. It returns a pointer to static data.

1  –  Stepping Through a List of Results

    The ldap_first_message() and ldap_next_message()  functions are
    used to step through the list of messages in a result chain
    returned by ldap_result(). For search operations, the result
    chain may actually include referral messages, entry messages,
    and result messages. The ldap_count_messages() function is used
    to count the number of messages returned. The ldap_msgtype()
    function can be used to distinguish between the different message
    types.

     LDAPMessage *ldap_first_message( LDAP *ld, LDAPMessage *res );
     LDAPMessage *ldap_next_message ( LDAP *ld, LDAPMesage *msg );
     int ldap_count_messages( LDAP *ld, LDAPMessage *res );

    Parameters are as follows:

    ld    The session handle.
    res   The result chain, as obtained by a call to one of the
          synchronous search functions or ldap_result().
    msg   The message returned by a previous call to ldap_first_
          message()  or ldap_next_message().

    The ldap_first_message() and ldap_next_message()  functions will
    return NULL when no more messages exist in the result set to be
    returned. NULL is also returned if an error occurs while stepping
    through the entries, in which case the error parameters in the
    session handle ld will be set to indicate the error.

    The ldap_count_messages() function returns the number of messages
    contained in a chain of results. It can also be used to count
    the number of messages that remain in a chain if called with a
    message, entry, or reference returned by ldap_first_message(),
    ldap_next_message(), ldap_first_entry(),  ldap_next_entry(),
    ldap_first_reference(), ldap_next_reference().
Close Help