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

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