The ldap_extended_operation() and ldap_extended_operation_s() functions allow extended LDAP operations to be passed to the server, providing a general protocol extensibility mechanism.

int ldap_extended_operation( LDAP *ld, const char *requestoid, const struct berval *request data, LDAPControl **serverctrls, LDAPControl **clientctrls, int *msgidp ); int ldap_extended_operation_s( LDAP *ld, const char *requestoid, const struct berval *request data, LDAPControl **serverctrls, LDAPControl **clientctrls, char **retoidp, struct berval **retdatap );

Parameters are as follows:

ld	The session handle.
requestoid	The dotted-OID text string naming the request.
requestdata	The arbitrary data required by the operation (if NULL, no data is sent to the server).
serverctrls	List of LDAP server controls.
clientctrls	List of client controls.
msgidp	This result parameter will be set to the message id of the request if the ldap_extended_operation() call succeeds.
retoidp	Pointer to a character string that will be set to an allocated, dotted- OID text string returned by the server. This string should be disposed of using the ldap_memfree() function. If no OID was returned, *retoidp is set to NULL.
retdatap	Pointer to a berval structure pointer that will be set to an allocated copy of the data returned by the server. This struct berval should be disposed of using ber_bvfree(). If no data is returned, *retdatap is set to NULL.

The ldap_extended_operation() function initiates an asynchronous extended operation and returns either the constant LDAP_SUCCESS if the request was successfully sent or another LDAP error code if not. See Section 14.18 for more information about possible errors and how to interpret them. If successful, ldap_extended_operation() places the message id of the request in *msgidp. A subsequent call to ldap_result() can be used to obtain the result of the extended operation which can be passed to ldap_parse_extended_result() to obtain the OID and data contained in the response.

The synchronous ldap_extended_operation_s() function returns the result of the operation, either the constant LDAP_SUCCESS if the operation was successful or another LDAP error code if it was not. See Section 14.18 for more information about possible errors and how to interpret them. The retoid and retdata parameters are filled in with the OID and data from the response. If no OID or data was returned, these parameters are set to NULL.

The ldap_extended_operation() and ldap_extended_operation_s() functions both support LDAPv3 server controls and client controls.

14.16 Abandoning an Operation

The following calls are used to abandon an operation in progress:

int ldap_abandon_ext( LDAP *ld, int msgid, LDAPControl **serverctrls, LDAPControl **clientctrls ); int ldap_abandon( LDAP *ld, int msgid );

Parameters are as follows:

ld	The session handle.
msgid	The message id of the request to be abandoned.
serverctrls	List of LDAP server controls.
clientctrls	List of client controls.

The ldap_abandon_ext() function abandons the operation with message id msgid and returns either the constant LDAP_SUCCESS if the abandon was successful or another LDAP error code if not. See Section 14.18 for more information about possible errors and how to interpret them.

The ldap_abandon() function is identical to ldap_abandon_ext() except that it does not accept client or server controls and it returns zero if the abandon was successful, -1 otherwise and does not support LDAPv3 server controls or client controls.

After a successful call to ldap_abandon() or ldap_abandon_ext() , results with the given message id are never returned from a subsequent call to ldap_result() . There is no server response to LDAP abandon operations.

14.17 Obtaining Results and Looking Inside LDAP Messages

The ldap_result() function is used to obtain the result of a previous asynchronously initiated operation. Note that depending on how it is called, ldap_result() may actually return a list or "chain" of result messages. Once a chain of messages has been returned to the caller, it is no longer tied in any caller-visible way to the LDAP request that produced it. Therefore, a chain of messages returned by calling ldap_result() or by calling a synchronous search function will never be affected by subsequent LDAP API calls (except for ldap_msgfree() , which is used to dispose of a chain of messages).

The ldap_msgfree() function frees the result messages (possibly an entire chain of messages) obtained from a previous call to ldap_result() or from a call to a synchronous search function.

The ldap_msgtype() function returns the type of an LDAP message. The ldap_msgid() function returns the message ID of an LDAP message.

int ldap_result( LDAP *ld, int msgid, int all, struct timeval *timeout, LDAPMessage **res ); int ldap_msgfree( LDAPMessage *res ); int ldap_msgtype( LDAPMessage *res ); int ldap_msgid( LDAPMessage *res );

Parameters are as follows:

ld	The session handle.
msgid	The message id of the operation whose results are to be returned, or the constant LDAP_RES_ANY (-1) if any result is desired.
all	Specifies how many messages will be retrieved in a single call to ldap_result() . This parameter only has meaning for search results. Pass the constant LDAP_MSG_ONE (0x00) to retrieve one message at a time. Pass LDAP_MSG_ALL (0x01) to request that all results of a search be received before returning all results in a single chain. Pass LDAP_MSG_RECEIVED (0x02) to indicate that all results retrieved so far should be returned in the result chain.
timeout	A timeout specifying how long to wait for results to be returned. A NULL value causes ldap_result() to block until results are available. A timeout value of zero seconds specifies a polling behavior.
res	For ldap_result() , a result parameter that will contain the result(s) of the operation. For ldap_msgfree() , the result chain to be freed, obtained from a previous call to ldap_result() , ldap_search_s() , or ldap_search_st() .

Upon successful completion, ldap_result() returns the type of the first result returned in the res parameter. This will be one of the following constants.

LDAP_RES_BIND (0x61) LDAP_RES_SEARCH_ENTRY (0x64) LDAP_RES_SEARCH_REFERENCE (0x73) -- new in LDAPv3 LDAP_RES_SEARCH_RESULT (0x65) LDAP_RES_MODIFY (0x67) LDAP_RES_ADD (0x69) LDAP_RES_DELETE (0x6B) LDAP_RES_MODDN (0x6D) LDAP_RES_COMPARE (0x6F) LDAP_RES_EXTENDED (0x78) -- new in LDAPv3

The ldap_result() function returns 0 if the timeout expired and -1 if an error occurs, in which case the error parameters of the LDAP session handle will be set accordingly.

The ldap_msgfree() function frees the result structure pointed to by res and returns the type of the message it freed.

The ldap_msgtype() function returns the type of the LDAP message it is passed as a parameter. The type will be one of the types listed above, or -1 on error.

The ldap_msgid() function returns the message ID associated with the LDAP message passed as a parameter.

14.18 Handling Errors and Parsing Results

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.

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

14.19 Parsing Search Results

The following calls are used to parse the entries and references returned by ldap_search() . These results are returned in an opaque structure that should only be accessed by calling the functions. Functions are provided to step through the entries and references returned, step through the attributes of an entry, retrieve the name of an entry, and retrieve the values associated with a given attribute in an entry.

14.19.1 Stepping Through a List of Entries

The ldap_first_entry() and ldap_next_entry() functions are used to step through and retrieve the list of entries from a search result chain. The ldap_first_reference() and ldap_next_reference() functions are used to step through and retrieve the list of continuation references from a search result chain. The ldap_count_entries() function is used to count the number of entries returned. The ldap_count_references() function is used to count the number of references returned.

LDAPMessage *ldap_first_entry( LDAP *ld, LDAPMessage *res ); LDAPMessage *ldap_next_entry( LDAP *ld, LDAPMessage *entry ); LDAPMessage *ldap_first_reference( LDAP *ld, LDAPMessage *res ); LDAPMessage *ldap_next_reference( LDAP *ld, LDAPMessage *ref ); int ldap_count_entries( LDAP *ld, LDAPMessage *res ); int ldap_count_references( LDAP *ld, LDAPMessage *res );

Parameters are as follows:

ld	The session handle.
res	The search result, as obtained by a call to one of the synchronous search functions or ldap_result() .
entry	The entry returned by a previous call to ldap_first_entry() or ldap_next_entry() .

The ldap_first_entry() and ldap_next_entry() functions will return NULL when no more entries or references 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_entries() function returns the number of entries contained in a chain of entries. It can also be used to count the number of entries 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() .

The ldap_count_references() function returns the number of references contained in a chain of search results. It can also be used to count the number of references that remain in a chain.