Handling Errors and Parsing Results

Nel documento Oracle Internet Directory (pagine 98-101)

ldap_parse_result

ldap_parse_sasl_bind_result ldap_parse_extended_result ldap_err2string

These calls are used to extract information from results and handle errors returned by other LDAP API routines. 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.

Syntax

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

);

C API Reference

C API for Oracle Internet Directory 3-47 int ldap_parse_extended_result

(

LDAP *ld, LDAPMessage *res, char **retoidp, struct berval **retdatap, int freeit );

#define LDAP_NOTICE_OF_DISCONNECTION "1.3.6.1.4.1.1466.20036"

char *ldap_err2string( int err );

The use of the following routines is deprecated and more complete descriptions can be found in RFC 1823:

int ldap_result2error

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

Parameters

Table 3–18 Parameters for Handling Errors and Parsing Results

Parameter Description

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 message. This is the indication from the server of the outcome of the operation.

NULL SHOULD 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 SHOULD be passed to ignore this field. The matched DN string SHOULD be freed by calling ldap_memfree() which is described later in this document.

C API Reference

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

referralsp This result parameter will be filled in with the contents of the referrals field from the LDAPMessage message, indicating zero or more alternate LDAP servers where the request is to be retried. The referrals array SHOULD be freed by calling ldap_

value_free() which is described later in this document. NULL SHOULD 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 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. 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 SHOULD be passed to ignore this field.

retoidp 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 SHOULD be passed to ignore this field. The LDAP_NOTICE_OF_DISCONNECTION macro is defined as a convenience for clients that wish to check an OID to see if it matches the one used for the unsolicited Notice of Disconnection (defined in RFC 2251[2] section 4.4.1).

retdatap 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 SHOULD be passed to ignore this field.

err For ldap_err2string(), an LDAP error code, as returned by Table 3–18 Parameters for Handling Errors and Parsing Results

Parameter Description

C API Reference

C API for Oracle Internet Directory 3-49 Usage Notes

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

The ldap_parse_result(), ldap_parse_sasl_bind_result(), and ldap_parse_extended_

result() functions all 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. If a chain of messages that contains more than one result message is passed to these routines they always operate on the first result in the chain.

ldap_err2string() is used to convert a numeric LDAP error code, as returned by ldap_parse_result(), ldap_parse_sasl_bind_result(), ldap_parse_extended_result() 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.

Nel documento Oracle Internet Directory (pagine 98-101)