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().