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

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