[Summary view] [Print] [Text view]

   1  # Copyright (c) 2000-2004 Graham Barr <gbarr@pobox.com>. 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  
   5  package Net::LDAP::Control::Paged;
   6  
   7  use vars qw(@ISA $VERSION);
   8  use Net::LDAP::Control;
   9  
  10  @ISA = qw(Net::LDAP::Control);
  11  $VERSION = "0.02";
  12  
  13  use Net::LDAP::ASN qw(realSearchControlValue);
  14  use strict;
  15  
  16  sub init {
  17    my($self) = @_;
  18  
  19    delete $self->{asn};
  20  
  21    unless (exists $self->{value}) {
  22      $self->{asn} = {
  23        size   => $self->{size} || 0,
  24        cookie => defined($self->{cookie}) ? $self->{cookie} : ''
  25      };
  26    }
  27  
  28    $self;
  29  }
  30  
  31  sub cookie {
  32    my $self = shift;
  33    $self->{asn} ||= $realSearchControlValue->decode($self->{value});
  34    if (@_) {
  35      delete $self->{value};
  36      return $self->{asn}{cookie} = defined($_[0]) ? $_[0] : '';
  37    }
  38    $self->{asn}{cookie};
  39  }
  40  
  41  sub size {
  42    my $self = shift;
  43    $self->{asn} ||= $realSearchControlValue->decode($self->{value});
  44    if (@_) {
  45      delete $self->{value};
  46      return $self->{asn}{size} = shift || 0;
  47    }
  48    $self->{asn}{size};
  49  }
  50  
  51  sub value {
  52    my $self = shift;
  53  
  54    exists $self->{value}
  55      ? $self->{value}
  56      : $self->{value} = $realSearchControlValue->encode($self->{asn});
  57  }
  58  
  59  1;
  60  
  61  __END__
  62  
  63  =head1 NAME
  64  
  65  Net::LDAP::Control::Paged - LDAPv3 Paged results control object
  66  
  67  =head1 SYNOPSIS
  68  
  69   use Net::LDAP;
  70   use Net::LDAP::Control::Paged;
  71   use Net::LDAP::Constant qw( LDAP_CONTROL_PAGED );
  72  
  73   $ldap = Net::LDAP->new( "ldap.mydomain.eg" );
  74  
  75   $page = Net::LDAP::Control::Paged->new( size => 100 );
  76  
  77   @args = ( base     => "cn=subnets,cn=sites,cn=configuration,$BASE_DN",
  78         scope    => "subtree",
  79         filter   => "(objectClass=subnet)",
  80         callback => \&process_entry, # Call this sub for each entry
  81         control  => [ $page ],
  82   );
  83  
  84   my $cookie;
  85   while(1) {
  86     # Perform search
  87     my $mesg = $ldap->search( @args );
  88  
  89     # Only continue on LDAP_SUCCESS
  90     $mesg->code and last;
  91  
  92     # Get cookie from paged control
  93     my($resp)  = $mesg->control( LDAP_CONTROL_PAGED ) or last;
  94     $cookie    = $resp->cookie or last;
  95  
  96     # Set cookie in paged control
  97     $page->cookie($cookie);
  98   }
  99  
 100   if ($cookie) {
 101     # We had an abnormal exit, so let the server know we do not want any more
 102     $page->cookie($cookie);
 103     $page->size(0);
 104     $ldap->search( @args );
 105   }
 106  
 107  =head1 DESCRIPTION
 108  
 109  C<Net::LDAP::Control::Paged> provides an interface for the creation and manipulation
 110  of objects that represent the C<pagedResultsControl> as described by RFC-2696.
 111  
 112  =head1 CONSTRUCTOR ARGUMENTS
 113  
 114  In addition to the constructor arguments described in
 115  L<Net::LDAP::Control> the following are provided.
 116  
 117  =over 4
 118  
 119  =item cookie
 120  
 121  The value to use as the cookie. This is not normally set when an object is
 122  created, but is set from the cookie value returned by the server. This associates
 123  a search with a previous search, so the server knows to return the page
 124  of entries following the entries it returned the previous time.
 125  
 126  =item size
 127  
 128  The page size that is required. This is the maximum number of entries that the
 129  server will return to the search request.
 130  
 131  =back
 132  
 133  =head1 METHODS
 134  
 135  As with L<Net::LDAP::Control> each constructor argument
 136  described above is also avaliable as a method on the object which will
 137  return the current value for the attribute if called without an argument,
 138  and set a new value for the attribute if called with an argument.
 139  
 140  =head1 SEE ALSO
 141  
 142  L<Net::LDAP>,
 143  L<Net::LDAP::Control>,
 144  http://www.ietf.org/rfc/rfc2696.txt
 145  
 146  =head1 AUTHOR
 147  
 148  Graham Barr E<lt>gbarr@pobox.comE<gt>
 149  
 150  Please report any bugs, or post any suggestions, to the perl-ldap mailing list
 151  E<lt>perl-ldap@perl.orgE<gt>
 152  
 153  =head1 COPYRIGHT
 154  
 155  Copyright (c) 2000-2004 Graham Barr. All rights reserved. This program is
 156  free software; you can redistribute it and/or modify it under the same
 157  terms as Perl itself.
 158  
 159  =cut
 160