IBM Security Directory Server, Version 6.3.1

LDAP_RESULT

Use the LDAP_RESULT API to wait for the result of an asynchronous LDAP operation, obtain LDAP message types, or obtain the message ID of an LDAP message.

ldap_result
ldap_msgtype
ldap_msgid

Synopsis

#include sys/time.h /* for struct timeval definition */
#include ldap.h


int ldap_result(
       LDAP              *ld,
       int               msgid,
       int               all,
       struct timeval    *timeout,
       LDAPMessage       **result)

int ldap_msgtype(
       LDAPMessage       *msg)

int ldap_msgid(
       LDAPMessage       *msg)

Input parameters

ld: Specifies the LDAP pointer that is returned by a previous call to ldap_init(), ldap_ssl_init(), or ldap_open().
msgid: 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 wanted.
all: This parameter has meaning only for search results. For search results, use all to specify how many search result messages are 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() waits until all results are received before it returns all results in a single chain. Specify LDAP_MSG_RECEIVED to indicate that all results retrieved so far are to be returned in the result chain.
timeout: Specifies how long in seconds to wait for results to be returned from ldap_result, as identified by the supplied msgid. A NULL value causes ldap_result() to wait until results are available. To poll, the timeout parameter is non-NULL, pointing to a zero-valued timeval structure.
msg: Specifies a pointer to a result, as returned from ldap_result(), ldap_search_s(), ldap_search_st(), or ldap_search_ext().

Output parameters

result: Contains the result of the asynchronous operation that is identified by msgid. This result is passed to an LDAP parsing routine such as ldap_first_entry().

If ldap_result() is unsuccessful, it returns -1 and sets the appropriate LDAP error, which can be retrieved by using ldap_get_errno(). If ldap_result() times out, it returns 0. 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)
      #define LDAP_RES_RENAME   LDAP_RES_MODRDN

Usage

The ldap_result() routine is used to wait for and return the result of an operation that is previously initiated by one of the LDAP asynchronous operation routines. For example, ldap_search(), ldap_modify(), and others. These routines return a msgid that uniquely identifies the request. The msgid can then be used to request the result of a specific operation from ldap_result().

The ldap_msgtype() API returns the type of LDAP message, which is based on the LDAP message that is passed as input by using the msg parameter.

The ldap_msgid() API returns the message ID associated with the LDAP message passed as input by using the msg parameter.

Errors

ldap_result() returns 0 if the timeout expires, and -1 if an error occurs. The ldap_get_errno() routine can be used to get an error code.

Notes

This routine allocates memory for results that it receives. The memory can be deallocated by calling ldap_msgfree().