1=head1 NAME
2
3Net::LDAP::Search - Object returned by Net::LDAP search method
4
5=head1 SYNOPSIS
6
7 use Net::LDAP;
8
9 $mesg = $ldap->search( @search_args );
10
11 @entries = $mesg->entries;
12
13=head1 DESCRIPTION
14
15A B<Net::LDAP::Search> object is returned from the
16L<search|Net::LDAP/item_search> method of a L<Net::LDAP> object. It is
17a container object which holds the results of the search.
18
19=head1 METHODS
20
21B<Net::LDAP::Search> inherits from L<Net::LDAP::Message>, and so
22supports all methods defined in L<Net::LDAP::Message>.
23
24=over 4
25
26=item as_struct ( )
27
28Returns a reference to a HASH, where the keys are the DNs of the
29results and the values are HASH references. These second level HASHes
30hold the attributes such that the keys are the attribute names, in
31lowercase, and the values are references to an ARRAY holding the
32values.
33
34This method will block until the whole search request has finished.
35
36=item count ( )
37
38Returns the number of entries returned by the server.
39
40This method will block until the whole search request has finished.
41
42=item entry ( INDEX )
43
44Return the N'th entry, which will be a L<Net::LDAP::Entry> object. If
45INDEX is greater than the total number of entries returned then
46C<undef> will be returned.
47
48This method will block until the search request has returned enough
49entries.
50
51=item entries ( )
52
53Return an array of L<Net::LDAP::Entry> objects that were returned from
54the server.
55
56This method will block until the whole search request has finished.
57
58=item pop_entry ( )
59
60Pop an entry from the internal list of L<Net::LDAP::Entry> objects for
61this search. If there are no more entries then C<undef> is returned.
62
63This call will block if the list is empty, until the server returns
64another entry.
65
66=item references ( )
67
68Return a list of references that the server returned. This will be a
69list of L<Net::LDAP::Reference> objects.
70
71=item sorted ( )
72
73Return a list L<Net::LDAP::Entry> objects, sorted by their DNs.
74
75The sorting is done on the client side using Perl's alphanumerical
76sort operator C<cmp>.
77
78=item sorted ( ATTR, ... )
79
80Return a list of L<Net::LDAP::Entry> objects, sorted by the specified
81attributes. The attributes are compared in the order specified, each
82only being compared if all the prior attributes compare equal.
83
84The sorting is done on the client side using Perl's alphanumerical
85sort operator C<cmp>.
86
87=item shift_entry ( )
88
89Shift an entry from the internal list of L<Net::LDAP::Entry> objects
90for this search. If there are no more entries then C<undef> is
91returned.
92
93This call will block if the list is empty, until the server returns
94another entry.
95
96=back
97
98=head1 SEE ALSO
99
100L<Net::LDAP>,
101L<Net::LDAP::Message>,
102L<Net::LDAP::Entry>,
103L<Net::LDAP::Reference>
104
105=head1 ACKNOWLEDGEMENTS
106
107This document is based on a document originally written by Russell
108Fulton E<lt>r.fulton@auckland.ac.nzE<gt>.
109
110=head1 AUTHOR
111
112Graham Barr E<lt>gbarr@pobox.comE<gt>
113
114Please report any bugs, or post any suggestions, to the perl-ldap
115mailing list E<lt>perl-ldap@perl.orgE<gt>.
116
117=head1 COPYRIGHT
118
119Copyright (c) 1997-2004 Graham Barr. All rights reserved. This program
120is free software; you can redistribute it and/or modify it under the
121same terms as Perl itself.
122
123=cut
124