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