ldap_result()--Retrieve Result of an Asynchronous LDAP Operation

 #include <sys/time.h>
 #include <ldap.h>
 
 int ldap_result(
                LDAP            *ld,
                int              msgid,
                int              all,
                struct timeval  *timeout,
                LDAPMessage    **result)

The ldap_result() function is used to wait for and return the result of an operation previously initiated by one of the LDAP asynchronous operation functions (such as ldap_search() and ldap_modify()).

Authorities and Locks

No i5/OS authority is required.

Parameters

ld

(Input) Specifies the LDAP pointer returned by a previous call to ldap_init(), ldap_ssl_init(), or ldap_open().

msgid

(Input) Specifies the message ID of the operation whose results are to be returned. The parameter can be set to LDAP_RES_ANY if any result is desired.

all

(Input) This parameter only has meaning for search results. For search results, all is used to specify how many search result messages will be returned on this call to ldap_result(). Specify LDAP_MSG_ONE to retrieve one search result message (for example, a single entry). Specify LDAP_MSG_ALL to request that all results of a search be received. ldap_result() will wait until all results are received before returning the results in a single chain. Specify LDAP_MSG_RECEIVED to indicate that all results retrieved so far should be returned in the result chain.

timeout

(Input) Specifies how long in seconds to wait for results (as identified by the supplied msgid) to be returned from ldap_result. A NULL value causes ldap_result() to wait until results for the operation identified by msgid are available. To poll, the timeout parameter should be non-NULL, pointing to a zero-valued timeval structure.

result

(Output) Contains the result of the asynchronous operation identified by msgid. This value should be freed by ldap_msgfree() when the result is no longer needed.

Return Value

-1

If ldap_result() was unsuccessful, sets the appropriate LDAP error, and ldap_get_errno() API can be used to obtain the error code.

0

If ldap_result() times out or there is no message available.

If successful,

it returns one of the following result types:

LDAP_RES_BIND	0x61L
LDAP_RES_SEARCH_ENTRY	0x64L
LDAP_RES_SEARCH_RESULT	0x65L
LDAP_RES_MODIFY	0x67L
LDAP_RES_ADD	0x69L
LDAP_RES_DELETE	0x6bL
LDAP_RES_MODRDN	0x6dL
LDAP_RES_COMPARE	0x6fL
LDAP_RES_SEARCH_REFERENCE	0X73L
LDAP_RES_EXTENDED	0X78L
LDAP_EXTENDED_RES_NAME	0X8aL
LDAP_EXTENDED_RES_VALUE	0X8bL
LDAP_RES_REFERRAL	0Xa3L
LDAP_RES_ANY	(-1L)

Error Conditions

If ldap_result() is not successful, ld_errno will be set to indicate the error. See LDAP Client API Error Conditions for possible values of ld_errno field. Use ldap_get_errno() function to retrieve the error information.

Error Messages

The following message may be sent from this function.

Related Information

• ldap_count_messages() -- Count messages in a result chain.
• ldap_first_entry() -- Retrieve first LDAP entry.
• ldap_first_message() -- Retrieve first LDAP message.
• ldap_first_reference() -- Retrieve first continuation reference in a chain of search results.
• ldap_msgfree() -- Free LDAP result message.
• ldap_msgid() -- Retrieve the message ID associated with an LDAP message.
• ldap_msgtype() -- Returns the type of an LDAP message.
• ldap_msgid() -- Returns the ID of an LDAP message.
• ldap_parse_result() -- Extract information from results.