ldap_parse_result

Extracts error, referral, and server control information from an LDAPMessage structure.

LDAP Version:v3
Library:*ldapsdk.*
NDS Version:7.xx or higher
Platform:NLM, Windows (NT, 95, 98, 2000, XP, Vista 32-bit and 64-bit ), Linux (32-bit and 64-bit), Solaris, AIX, and HP-UX

Syntax

  #include <ldap.h>
  
  int ldap_parse_result (
     LDAP            *ld,
     LDAPMessage     *res,
     int             *errcodep,
     char           **matcheddnp,
     char           **errmsgp,
     char          ***referralsp,
     LDAPControl   ***serverctrlsp,
     int              freeit);

Parameters

ld

(IN) Points to the handle for the LDAP session.

res

(IN) Points to an LDAPMessage containing the results of an LDAP operation.

errcodep

(OUT) Points to the LDAP error code that specifies the results of the last LDAP operation.

matcheddnp

(OUT) Points to a string that specifies how much of the name in the request was recognized. Pass in NULL to ignore this parameter. When you are finished, you must free the matched DN string by calling the ldap_memfree function.

errmsgp

(OUT) Points to the error message string that is associated with the error code. Pass in NULL to ignore this parameter. When you are finished, you must free the error message string by calling the ldap_memfree function.

referralsp

(OUT) Points to a NULL-terminated array of strings which contains zero or more alternate LDAP server URLs where the request can be sent. Pass in NULL to ignore this parameter. When you are finished, you must free the referrals array by calling the ldap_value_free function.

serverctrlsp

(OUT) Points to a NULL-terminated array of LDAPControl structures which are returned by the LDAP server and which list the controls the LDAP server supports. When you are finished, you must free the control array by calling the ldap_controls_free function.

freeit

(IN) Specifies whether the resources specified by the res parameter are freed.

  • Zero indicates that the resources specified by the res parameter are not freed automatically. When you are done with the LDAPMessage structure, you must call the ldap_msgfree function to free the memory.

  • Non-zero indicates that memory is freed by the ldap_parse_result function after it extracts the information.

Return Values

0x00

LDAP_SUCCESS

0x5E

LDAP_NO_RESULTS_RETURNED

0x5F

LDAP_MORE_RESULTS_TO_RETURN

Non-zero

Failure. For a complete list, see LDAP Return Codes.

0x54

LDAP_DECODING_ERROR

0x59

LDAP_PARAM_ERROR

Remarks

Upon successful completion, the ldap_result function returns the type of the first result returned in the res parameter. The type will be one of the following constants:

The ldap_parse_result function cannot be used to parse LDAP_RES_SEARCH_ENTRY or LDAP_RES_SEARCH_REFERENCE messages. Use ldap_first_entry to parse entries. Use ldap_parse_reference to parse references.

If a chain of messages is passed to this function, the function operates only on the first message in the result chain that is not of type LDAP_RES_SEARCH_ENTRY or LDAP_RES_SEARCH_REFERENCE. Use the ldap_first_message and ldap_next_message functions to step through a chain of messages.

If the result message contains data from an extended operation, use the ldap_parse_extended_result function to retrieve additional information.

See Also

ldap_err2string, ldap_parse_extended_result, ldap_parse_sasl_bind_result