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

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

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()). Those functions return a call identifier upon successful initiation of the operation or -1 in case of error. This unique identifier can be used to request the result of a specific operation from ldap_result() through the msgid parameter.

Authorities and Locks

No OS/400 authority is required. All authority checking is done by the LDAP server.

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 in a single call to ldap_result(). Specify LDAP_MSG_ONE to retrieve one search result message at a time. 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 all 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 result should be passed to the LDAP parsing routines, such as ldap_first_entry().

Return Value

-1

If ldap_result() 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.

If successful,

it returns one of the following result types:

      #define LDAP_RES_BIND           0x61L
      #define LDAP_RES_SEARCH_ENTRY   0x64L
      #define LDAP_RES_SEARCH_RESULT  0x65L
      #define LDAP_RES_MODIFY         0x67L
      #define LDAP_RES_ADD            0x69L
      #define LDAP_RES_DELETE         0x6bL
      #define LDAP_RES_MODRDN         0x6dL
      #define LDAP_RES_COMPARE        0x6fL  
      #define LDAP_RES_SEARCH_REFERENCE	0X73L	
      #define LDAP_RES_EXTENDED		0X78L	
      #define 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 set from this function.
    CPF3CF2 E  Error(s) occurred during running of ldap_result API.

Related Information

    ldap_msgtype() -- Returns the type of an LDAP message.
    ldap_msgid() -- Returns the ID of an LDAP message.