Up to Contents

Back to Abandoning an Operation

Obtaining Results

ldap_result() is used to obtain the result of a previous asynchronously initiated operation. Note that if the all flag is specified as LDAP_MSG_ALL or LDAP_MSG_RECEIVED, ldap_result() may actually return a list or "chain" of messages.

ldap_msgfree() frees the results obtained from a previous call to ldap_result(), or a synchronous search routine.

ldap_msgtype() returns the type of an LDAP message. ldap_msgid() 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:

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

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

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

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

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

Up to Contents

Forward to Handling Errors and Parsing Results