ldap_result — Wait for the result of an LDAP operation
#include <ldap.h>
int
ldap_result( |
LDAP * | ld, |
int | msgid, | |
int | all, | |
struct timeval * | timeout, | |
LDAPMessage ** | result) ; |
int
ldap_msgfree( |
LDAPMessage * | msg) ; |
int
ldap_msgtype( |
LDAPMessage * | msg) ; |
int
ldap_msgid( |
LDAPMessage * | msg) ; |
The ldap_result()
routine is used
to wait for and return the result of an operation previously
initiated by one of the LDAP asynchronous operation routines
(e.g., ldap_search(3), ldap_modify(3), etc.).
Those routines all return -1 in case of error, and an
invocation identifier upon successful initiation of the
operation. The invocation identifier is picked by the library
and is guaranteed to be unique across the LDAP session. It
can be used to request the result of a specific operation
from ldap_result()
through the msgid
parameter.
The ldap_result()
routine will
block or not, depending upon the setting of the timeout
parameter. If timeout
is not a NULL pointer, it specifies a maximum interval to
wait for the selection to complete. If timeout is a NULL
pointer, the select blocks indefinitely. To effect a poll,
the timeout argument should be a non-NULL pointer, pointing
to a zero-valued timeval structure. See select(2) for further
details.
If the result of a specific operation is required,
msgid
should be set
to the invocation identifier returned when the operation was
initiated, otherwise LDAP_RES_ANY or LDAP_RES_UNSOLICITED
should be supplied to wait for any or unsolicited
response.
The all
parameter,
if non-zero, causes ldap_result()
to return all
responses with msgid, otherwise only the next response is
returned. This is commonly used to obtain all the responses
of a search operation.
A search response is made up of zero or more search
entries, zero or more search references, and zero or more
extended partial responses followed by a search result. If
all
is set to 0,
search entries will be returned one at a time as they come
in, via separate calls to ldap_result()
. If it's set to
1, the search response will only be returned in its entirety,
i.e., after all entries, all references, all extended partial
responses, and the final search result have been
received.
Upon success, the type of the result received is returned
and the result
parameter will contain the result of the operation. This
result should be passed to the LDAP parsing routines,
ldap_first_message(3) and
friends, for interpretation.
The possible result types returned are:
LDAP_RES_BIND (0x61) LDAP_RES_SEARCH_ENTRY (0x64) LDAP_RES_SEARCH_REFERENCE (0x73) 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) LDAP_RES_INTERMEDIATE (0x79)
The ldap_msgfree()
routine is
used to free the memory allocated for result(s) by ldap_result()
or ldap_search_s(3) and
friends. It takes a pointer to the result or result chain to
be freed and returns the type of the last message in the
chain. If the parameter is NULL, the function does nothing
and returns zero.
The ldap_msgtype()
routine
returns the type of a message.
The ldap_msgid()
routine returns the message id of a message.