1# Copyright (c) 2004 Peter Marschall <peter@adpm.de>. All rights reserved.
2# This program is free software; you can redistribute it and/or
3# modify it under the same terms as Perl itself.
4
5package Net::LDAP::Control::PersistentSearch;
6
7use vars qw(@ISA $VERSION);
8use Net::LDAP::Control;
9
10@ISA = qw(Net::LDAP::Control);
11$VERSION = "0.01";
12
13use Net::LDAP::ASN qw(PersistentSearch);
14use strict;
15
16sub init {
17  my($self) = @_;
18
19  delete $self->{asn};
20
21  unless (exists $self->{value}) {
22    $self->{asn} = {
23      changeTypes => $self->{changeTypes} || '15',
24      changesOnly => $self->{changesOnly} || '0',
25      returnECs   => $self->{returnECs} || '0',
26    };
27  }
28
29  $self;
30}
31
32sub changeTypes {
33  my $self = shift;
34  $self->{asn} ||= $PersistentSearch->decode($self->{value});
35  if (@_) {
36    delete $self->{value};
37    return $self->{asn}{changeTypes} = shift || 0;
38  }
39  $self->{asn}{changeTypes};
40}
41
42sub changesOnly {
43  my $self = shift;
44  $self->{asn} ||= $PersistentSearch->decode($self->{value});
45  if (@_) {
46    delete $self->{value};
47    return $self->{asn}{changesOnly} = shift || 0;
48  }
49  $self->{asn}{changesOnly};
50}
51
52sub returnECs {
53  my $self = shift;
54  $self->{asn} ||= $PersistentSearch->decode($self->{value});
55  if (@_) {
56    delete $self->{value};
57    return $self->{asn}{returnECs} = shift || 0;
58  }
59  $self->{asn}{returnECs};
60}
61
62sub value {
63  my $self = shift;
64
65  exists $self->{value}
66    ? $self->{value}
67    : $self->{value} = $PersistentSearch->encode($self->{asn});
68}
69
701;
71
72__END__
73
74=head1 NAME
75
76Net::LDAP::Control::PersistentSearch - LDAPv3 Persistent Search control object
77
78=head1 SYNOPSIS
79
80 use Net::LDAP;
81 use Net::LDAP::Control::PersistentSearch;
82
83 $ldap = Net::LDAP->new( "ldap.mydomain.eg" );
84
85 $persist = Net::LDAP::Control::PersistentSearch->new( changeTypes => 15,
86                                                       changesOnly => 1,
87                                                       returnECs => 1 );
88
89 $srch = $ldap->search( base     => "cn=People,dc=mydomain,dc=eg",
90                        filter   => "(objectClass=person)",
91                        callback => \&process_entry, # call for each entry
92                        control  => [ $persist ] );
93
94 die "error: ",$srch->code(),": ",$srch->error()  if ($srch->code());
95
96 sub process_entry {
97   my $message = shift;
98   my $entry = shift;
99
100   print $entry->dn()."\n";
101 }
102
103
104=head1 DESCRIPTION
105
106C<Net::LDAP::Control::PersistentSearch> provides an interface for the creation
107and manipulation of objects that represent the C<PersistentSearch> control as
108described by draft-smith-psearch-ldap-01.txt.
109
110=head1 CONSTRUCTOR ARGUMENTS
111
112In addition to the constructor arguments described in
113L<Net::LDAP::Control> the following are provided.
114
115=over 4
116
117=item changeTypes
118
119An integer value determining the types of changes to look out for.
120It is the bitwise OR of the following values (which represent the LDAP
121operations indicated next to them):
122
123=over 4
124
125=item 1 = add
126
127=item 2 = delete
128
129=item 4 = modify
130
131=item 8 = modDN
132
133=back
134
135If it is not given it defaults to 15 meaning all changes.
136
137=item changesOnly
138
139A boolean value telling whether the server may return
140entries that match the search criteria.
141
142If C<TRUE> the server must not return return any existing
143entries that match the search criteria.  Entries are only
144returned when they are changed (added, modified, deleted, or
145subject to a modifyDN operation)
146
147=item returnECs
148
149If C<TRUE>, the server must return an Entry Change Notification
150control with each entry returned as the result of changes.
151
152See L<Net::LDAP::Control::EntryChange> for details.
153
154=back
155
156=head1 METHODS
157
158As with L<Net::LDAP::Control> each constructor argument
159described above is also available as a method on the object which will
160return the current value for the attribute if called without an argument,
161and set a new value for the attribute if called with an argument.
162
163=head1 SEE ALSO
164
165L<Net::LDAP>,
166L<Net::LDAP::Control>,
167L<Net::LDAP::Control::EntryChange>
168
169=head1 AUTHOR
170
171Peter Marschall E<lt>peter@adpm.deE<gt>, based on Net::LDAP::Control::Page
172from Graham Barr E<lt>gbarr@pobox.comE<gt> and the preparatory work
173of Don Miller E<lt>donm@uidaho.eduE<gt>.
174
175Please report any bugs, or post any suggestions, to the perl-ldap
176mailing list E<lt>perl-ldap@perl.orgE<gt>
177
178=head1 COPYRIGHT
179
180Copyright (c) 2004 Peter Marschall. All rights reserved. This program is
181free software; you can redistribute it and/or modify it under the same
182terms as Perl itself.
183
184=cut
185
186