]> git.sur5r.net Git - openldap/blob - doc/man/man3/ldap_first_message.3
Merge remote-tracking branch 'origin/mdb.master'
[openldap] / doc / man / man3 / ldap_first_message.3
1 .TH LDAP_FIRST_MESSAGE 3 "RELEASEDATE" "OpenLDAP LDVERSION"
2 .\" $OpenLDAP$
3 .\" Copyright 1998-2014 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 .so ../Project