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