ldap_msgid(3)

LDAP_RESULT(3)         C LIBRARY FUNCTIONS         LDAP_RESULT(3)

NAME

     ldap_result - Wait for the result of an LDAP operation

LIBRARY

     OpenLDAP LDAP (libldap, -lldap)

SYNOPSIS

     #include <ldap.h>

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

     int ldap_msgfree( LDAPMessage *msg );

     int ldap_msgtype( LDAPMessage *msg );

     int ldap_msgid( 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  ini-
     tiation  of  the  operation.  The  invocation  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   or
     LDAP_RES_UNSOLICITED  should  be supplied to wait for any or
     unsolicited response.

     The all parameter,  if  non-zero,  causes  ldap_result()  to
     return  all  responses  with  msgid, otherwise only the next
     response is returned.  This is commonly used to  obtain  all
     the responses of a search operation.

     A search response is made up of zero or more search entries,
     zero  or  more  search references, and zero or more extended

OpenLDAP 2.3.27      Last change: 2006/08/19                    1

LDAP_RESULT(3)         C LIBRARY FUNCTIONS         LDAP_RESULT(3)

     partial responses 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  1, the search response will only be returned in its
     entirety, i.e.,  after  all  entries,  all  references,  all
     extended partial responses, 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 parsing
     routines, ldap_first_message(3) and friends, for interpreta-
     tion.

     The possible result types returned are:

          LDAP_RES_BIND (0x61)
          LDAP_RES_SEARCH_ENTRY (0x64)
          LDAP_RES_SEARCH_REFERENCE (0x73)
          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)
          LDAP_RES_EXTENDED_PARTIAL (0x79)

     The ldap_msgfree() routine is used to free the memory  allo-
     cated for result(s) by ldap_result() or ldap_search_s(3) and
     friends.  It takes a pointer to the result or  result  chain
     to  be freed and returns the type of the last message in the
     chain.  If the parameter is NULL, the function does  nothing
     and returns zero.

     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_msgtype() and
     ldap_msgid() return -1 on error.

SEE ALSO

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

ACKNOWLEDGEMENTS

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

OpenLDAP 2.3.27      Last change: 2006/08/19                    2