← Back to branch summary

~ubuntu-branches/ubuntu/oneiric/likewise-open/oneiric

« back to all changes in this revision

Viewing changes to openldap/doc/man/man3/ldap_first_message.3

  • Committer: Bazaar Package Importer
  • Author(s): Scott Salley
  • Date: 2010-11-22 12:06:00 UTC
  • mfrom: (1.1.6 upstream)
  • Revision ID: james.westby@ubuntu.com-20101122120600-8lba1fpceot71wlb
Tags: 6.0.0.53010-1
Likewise Open 6.0

Show diffs side-by-side

added added

removed removed

Lines of Context:
openldap/doc/man/man3/ldap_first_message.3
 
1
.TH LDAP_FIRST_MESSAGE 3 "RELEASEDATE" "OpenLDAP LDVERSION"
 
2
.\" $OpenLDAP: pkg/ldap/doc/man/man3/ldap_first_message.3,v 1.11.2.4 2009/01/22 00:00:49 kurt Exp $
 
3
.\" Copyright 1998-2009 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