external/bsd/openldap/man/ldap_first_message.3

   1 .TH LDAP_FIRST_MESSAGE 3 "2008/07/16" "OpenLDAP 2.4.11"
   2 .\" $OpenLDAP: pkg/ldap/doc/man/man3/ldap_first_message.3,v 1.11.2.3 2008/02/11 23:26:39 kurt Exp $
   3 .\" Copyright 1998-2008 The OpenLDAP Foundation All Rights Reserved.
   4 .\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
   5 .SH NAME
   6 ldap_first_message, ldap_next_message, ldap_count_messages \- Stepping through messages in a result chain
   7 .SH LIBRARY
   8 OpenLDAP LDAP (libldap, -lldap)
   9 .SH SYNOPSIS
  10 .nf
  11 .ft B
  12 #include <ldap.h>
  13 .LP
  14 .ft B
  15 int ldap_count_messages( LDAP *ld, LDAPMessage *result )
  16 .LP
  17 .ft B
  18 LDAPMessage *ldap_first_message( LDAP *ld, LDAPMessage *result )
  19 .LP
  20 .ft B
  21 LDAPMessage *ldap_next_message( LDAP *ld, LDAPMessage *message )
  22 .SH DESCRIPTION
  23 .LP
  24 These routines are used to step through the messages in a result chain
  25 received from
  26 .BR ldap_result (3) .
  27 For search operations, the result chain can contain referral, entry
  28 and result messages. The
  29 .BR ldap_msgtype (3)
  30 function can be used to distinguish between the different message types.
  31 .LP
  32 The
  33 .B ldap_first_message()
  34 routine is used to retrieve the first message in a result chain.
  35 It takes the \fIresult\fP as returned by a call to
  36 .BR ldap_result (3) ,
  37 .BR ldap_search_s (3)
  38 or
  39 .BR ldap_search_st (3)
  40 and returns a pointer to the first message in the result chain.
  41 .LP
  42 This pointer should be supplied on a subsequent call to
  43 .B ldap_next_message()
  44 to get the next message, the result of which should be
  45 supplied to the next call to
  46 .BR ldap_next_message() ,
  47 etc.
  48 .B ldap_next_message()
  49 will return NULL when there are no more messages.
  50 .LP
  51 These functions are useful when using routines like
  52 .BR ldap_parse_result (3)
  53 that only operate on the first result in the chain.
  54 .LP
  55 A count of the number of messages in the result chain can be obtained
  56 by calling
  57 .BR ldap_count_messages() .
  58 It can also be used to count the number of remaining messages in a chain
  59 if called with a message, entry or reference returned by
  60 .B ldap_first_message() ,
  61 .B ldap_next_message() ,
  62 .BR ldap_first_entry (3) ,
  63 .BR ldap_next_entry (3) ,
  64 .BR ldap_first_reference (3) ,
  65 .BR ldap_next_reference (3) .
  66 .SH ERRORS
  67 If an error occurs in
  68 .B ldap_first_message()
  69 or
  70 .BR ldap_next_message() ,
  71 NULL is returned.  If an error occurs in
  72 .BR ldap_count_messages() ,
  73 -1 is returned.
  74 .SH SEE ALSO
  75 .BR ldap (3),
  76 .BR ldap_search (3),
  77 .BR ldap_result (3),
  78 .BR ldap_parse_result (3),
  79 .BR ldap_first_entry (3),
  80 .BR ldap_first_reference (3)
  81 .SH ACKNOWLEDGEMENTS
  82 .\" Shared Project Acknowledgement Text
  83 .B "OpenLDAP Software"
  84 is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>.
  85 .B "OpenLDAP Software"
  86 is derived from University of Michigan LDAP 3.3 Release.