git.sur5r.net Git - openldap/blob - doc/man/man3/ldap_result.3

   1 .TH LDAP_RESULT 3 "22 September 1998" "OpenLDAP LDVERSION"
   2 .SH NAME
   3 ldap_result \- Wait for the result of an LDAP operation
   4 .SH SYNOPSIS
   5 .nf
   6 .ft B
   7 #include <lber.h>
   8 #include <ldap.h>
   9 .LP
  10 .ft B
  11 int ldap_result(ld, msgid, all, timeout, result)
  12 .ft
  13 LDAP *ld;
  14 int msgid, all;
  15 struct timeval *timeout;
  16 LDAPMessage **result;
  17 .LP
  18 .ft B
  19 int ldap_msgfree(msg)
  20 .ft
  21 LDAPMessage *msg;
  22 .LP
  23 .ft B
  24 int ldap_msgtype(msg)
  25 .ft
  26 LDAPMessage *msg;
  27 .LP
  28 .ft B
  29 int ldap_msgid(msg)
  30 .ft
  31 LDAPMessage *msg;
  32 .SH DESCRIPTION
  33 The
  34 .B ldap_result()
  35 routine is used to wait for and return the result of
  36 an operation previously initiated by one of the LDAP asynchronous
  37 operation routines (e.g.,
  38 .BR ldap_search (3),
  39 .BR ldap_modify (3),
  40 etc.).  Those routines all return -1 in case of error, and an
  41 invocation identifier upon successful initiation of the operation. The
  42 invocation identifier is picked by the library and is guaranteed to be
  43 unique across the LDAP session.  It can be used to request the result
  44 of a specific operation from
  45 .B ldap_result()
  46 through the \fImsgid\fP parameter.
  47 .LP
  48 The
  49 .B ldap_result()
  50 routine will block or not, depending upon the setting
  51 of the \fItimeout\fP parameter.
  52 If timeout is not a NULL pointer,  it  specifies  a  maximum
  53 interval  to wait for the selection to complete.  If timeout
  54 is a NULL  pointer,  the  select  blocks  indefinitely.   To
  55 effect  a  poll,  the  timeout argument should be a non-NULL
  56 pointer, pointing to a zero-valued timeval structure.  See
  57 .BR select (2)
  58 for further details.
  59 .LP
  60 If the result of a specific operation is required, \fImsgid\fP should
  61 be set to the invocation identifier returned when the operation was
  62 initiated, otherwise LDAP_RES_ANY should be supplied.  The \fIall\fP
  63 parameter only has meaning for search responses and is used to select
  64 whether a single entry of the search response should be returned, or
  65 all results of the search should be returned.
  66 .LP
  67 A search response is made up of zero or
  68 more search entries followed by a search result.  If \fIall\fP is set
  69 to 0, search entries will be returned one at a time as they come in,
  70 via separate calls to
  71 .BR ldap_result() .
  72 If it's set to 1, the search
  73 response will only be returned in its entirety, i.e., after all entries
  74 and the final search result have been received.
  75 .LP
  76 Upon success, the type of the result received is returned and the
  77 \fIresult\fP parameter will contain the result of the operation.  This
  78 result should be passed to the LDAP parsing routines,
  79 .BR ldap_first_entry (3)
  80 and friends, for interpretation.
  81 .LP
  82 The possible result types returned are:
  83 .LP
  84 .nf
  85         #define LDAP_RES_BIND                   0x61L
  86         #define LDAP_RES_SEARCH_ENTRY           0x64L
  87         #define LDAP_RES_SEARCH_RESULT          0x65L
  88         #define LDAP_RES_MODIFY                 0x67L
  89         #define LDAP_RES_ADD                    0x69L
  90         #define LDAP_RES_DELETE                 0x6bL
  91         #define LDAP_RES_MODRDN                 0x6dL
  92         #define LDAP_RES_COMPARE                0x6fL
  93 .fi
  94 .LP
  95 The
  96 .B ldap_msgfree()
  97 routine is used to free the memory allocated for
  98 a result by
  99 .B ldap_result()
 100 or
 101 .BR ldap_search_s (3)
 102 and friends.  It takes
 103 a pointer to the result to be freed and returns the type of the
 104 message it freed.
 105 .LP
 106 The
 107 .B ldap_msgtype()
 108 routine returns the type of a message.
 109 .LP
 110 The
 111 .B ldap_msgid()
 112 routine returns the message id of a message.
 113 .SH ERRORS
 114 .B ldap_result()
 115 returns -1 if something bad happens, and zero if the
 116 timeout specified was exceeded.
 117 .B ldap_msgtype()
 118 and
 119 .B ldap_msgid()
 120 return -1 on error.
 121 .SH NOTES
 122 This routine mallocs memory for results that it receives.  The memory
 123 can be freed by calling
 124 .BR ldap_msgfree .
 125 .SH SEE ALSO
 126 .BR ldap (3),
 127 .BR ldap_search (3),
 128 .BR select (2)
 129 .SH ACKNOWLEDGEMENTS
 130 .B      OpenLDAP
 131 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
 132 .B      OpenLDAP
 133 is derived from University of Michigan LDAP 3.3 Release.