ldap_result - Wait for the result of an LDAP operation


SYNOPSIS

       #include <ldap.h>

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

       int ldap_msgfree(msg)
       LDAPMessage *msg;

       int ldap_msgtype(msg)
       LDAPMessage *msg;

       int ldap_msgid(msg)
       LDAPMessage *msg;


DESCRIPTION

       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  invoca­
       tion 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 should
       be supplied.  The  all  parameter  only  has  meaning  for
       search  responses  and  is used to select whether a single
       entry of the search response should be  returned,  or  all
       results of the search should be returned.

       A  search  response  is  made  up  of  zero or more search
       entries 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

       entirety, i.e., after all entries  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 pars­
       ing routines, ldap_first_entry(3) and friends, for  inter­
       pretation.

       The possible result types returned are:

            #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

       The  ldap_msgfree()  routine  is  used  to free the memory
       allocated   for   a    result    by    ldap_result()    or
       ldap_search_s(3)  and  friends.  It takes a pointer to the
       result to be freed and returns the type of the message  it
       freed.

       The  ldap_msgtype() routine returns the type of a message.

       The ldap_msgid() routine returns the message id of a  mes­
       sage.


ERRORS

       ldap_result()  returns  -1  if  something bad happens, and
       zero if the timeout  specified  was  exceeded.   ldap_msg­
       type() and ldap_msgid() return -1 on error.


NOTES

       This routine dynamically allocates memory for results that
       it receives.  The memory can be freed by the caller  using
       ldap_msgfree.


SEE ALSO

       ldap(3), ldap_search(3), select(2)


ACKNOWLEDGEMENTS

       OpenLDAP  is developed and maintained by The OpenLDAP Pro­
       ject (http://www.openldap.org/).  OpenLDAP is derived from
       University of Michigan LDAP 3.3 Release.


Man(1) output converted with man2html