LDAP_PARSE_RESULT

Edit online

Use the LDAP_PARSE_RESULT API or LDAP routine to extract information from the results that are returned by other LDAP API routines.

  • ldap_parse_result
  • ldap_parse_sasl_bind_result
  • ldap_parse_extended_result

Synopsis

#include ldap.h


int ldap_parse_result(
       LDAP            *ld;
       LDAPMessage     *res,
       int             *errcodep,
       char            **matcheddnp,
       char            **errmsgp,
       char            ***referralsp,
       LDAPControl     ***servctrlsp,
       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   **resultdatap,
       int             freeit)

Input parameters

ld
Specifies the LDAP pointer that is returned by a previous call to ldap_init(), ldap_ssl_init(), or ldap_open().
res
Specifies the result of an LDAP operation as returned by ldap_result() or one of the synchronous LDAP API operation calls.
errcodep
Specifies a pointer to the result parameter that is provided with the LDAP error code field from the LDAPMessage message. The LDAPResult message is produced by the LDAP server, and indicates the outcome of the operation. NULL can be specified for errcodep if the LDAPResult message is to be ignored.
matcheddnp
Specifies a pointer to a result parameter. When LDAP_NO_SUCH_OBJECT is returned as the LDAP error code, this result parameter is provided 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 must be freed by calling ldap_memfree().
errmsgp
Specifies a pointer to a result parameter that is provided with the contents of the error message from the LDAPMessage message. The error message string must be freed by calling ldap_memfree().
referralsp
Specifies a pointer to a result parameter that is provided with the contents of the referrals field from the LDAPMessage message, indicating zero or more alternative LDAP servers where the request must be tried again. The referrals array must be freed by calling ldap_value_free(). NULL can be supplied for this parameter to ignore the referrals field.
resultoidp
This result parameter specifies a pointer that is set to point to an allocated, dotted-OID text string that is returned from the server. This string must be disposed of using the ldap_memfree() API. If no OID is returned, *resultoidp is set to NULL.
resultdatap
This result parameter specifies a pointer to a berval structure pointer that is set to an allocated data copy that is returned by the server. This struct berval must be disposed of using ber_bvfree(). If no data is returned, *resultdatap is set to NULL.
serverctrlsp
Specifies a pointer to a result parameter that is provided with an allocated array of controls that are copied out of LDAPMessage. The control array must be freed by calling ldap_controls_free().
freeit
Specifies a Boolean value that determines whether the LDAP result (as specified by res) is to be freed. Any nonzero value results in res being freed after the requested information is extracted. The ldap_msgfree() API can be used to free the result later.
servercredp
Specifies a pointer to a result parameter. For SASL bind results, this result parameter is provided with the credentials returned by the server for mutual authentication, if the credentials are returned. The credentials are returned in a struct berval structure. NULL might be supplied to ignore this field.
err
Specifies an LDAP error code, which is used as input to ldap_err2string(), so that a text description of the error can be obtained.

Usage

The ldap_parse_result() API is used to:
  • Obtain the LDAP error code field that is associated with an LDAPMessage message.
  • Obtain the portion of the DN that the server recognizes for a failed operation.
  • Obtain the text error message that is associated with the error code returned in an LDAPMessage message.
  • Obtain the list of alternative servers from the referrals field.
  • Obtain the array of controls that can be returned by the server.

The ldap_parse_sasl_bind_result() API is used to obtain server credentials, as a result of an attempt to run mutual authentication.

Both the ldap_parse_sasl_bind_result() and the ldap_parse_extended_result() APIs ignore messages of type LDAP_RES_SEARCH_ENTRY and LDAP_RES_SEARCH_REFERENCE when you look for a result message to parse. They both return LDAP_SUCCESS if the result was successfully located and parsed, and an LDAP error code if the result was not successfully parsed.

The ldap_err2string() API is used to convert the numerical LDAP error code, as returned by any of the LDAP APIs, into a NULL-terminated character string that describes the error. The character string is returned as static data and must not be freed by the application.

Errors

The parse routines return an LDAP error code if they encounter an error that parses the result.

See LDAP_ERROR for a list of the LDAP error codes.

See also

ldap_error, ldap_result