[Summary view] [Print] [Text view]

   1  # Copyright (c) 1999-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;
   6  
   7  use vars qw($VERSION);
   8  use strict;
   9  
  10  use Net::LDAP::Constant qw(
  11    LDAP_CONTROL_SORTREQUEST
  12    LDAP_CONTROL_SORTRESULT
  13    LDAP_CONTROL_VLVREQUEST
  14    LDAP_CONTROL_VLVRESPONSE
  15    LDAP_CONTROL_PAGED
  16    LDAP_CONTROL_PROXYAUTHENTICATION
  17    LDAP_CONTROL_MANAGEDSAIT
  18    LDAP_CONTROL_PERSISTENTSEARCH
  19    LDAP_CONTROL_ENTRYCHANGE
  20    LDAP_CONTROL_MATCHEDVALUES
  21    LDAP_CONTROL_PASSWORDPOLICY
  22    LDAP_CONTROL_PREREAD
  23    LDAP_CONTROL_POSTREAD
  24    LDAP_CONTROL_SYNC
  25    LDAP_CONTROL_SYNC_STATE
  26    LDAP_CONTROL_SYNC_DONE
  27  );
  28  
  29  $VERSION = "0.09";
  30  
  31  my %Pkg2Type = (
  32  
  33    'Net::LDAP::Control::Sort'        => LDAP_CONTROL_SORTREQUEST,
  34    'Net::LDAP::Control::SortResult'     => LDAP_CONTROL_SORTRESULT,
  35  
  36    'Net::LDAP::Control::VLV'        => LDAP_CONTROL_VLVREQUEST,
  37    'Net::LDAP::Control::VLVResponse'    => LDAP_CONTROL_VLVRESPONSE,
  38  
  39    'Net::LDAP::Control::Paged'        => LDAP_CONTROL_PAGED,
  40  
  41    'Net::LDAP::Control::ProxyAuth'    => LDAP_CONTROL_PROXYAUTHENTICATION,
  42  
  43    'Net::LDAP::Control::ManageDsaIT'    => LDAP_CONTROL_MANAGEDSAIT,
  44  
  45    'Net::LDAP::Control::PersistentSearch'    => LDAP_CONTROL_PERSISTENTSEARCH,
  46    'Net::LDAP::Control::EntryChange'    => LDAP_CONTROL_ENTRYCHANGE,
  47  
  48    'Net::LDAP::Control::MatchedValues'    => LDAP_CONTROL_MATCHEDVALUES,
  49  
  50    'Net::LDAP::Control::PasswordPolicy'    => LDAP_CONTROL_PASSWORDPOLICY,
  51  
  52    'Net::LDAP::Control::PreRead'        => LDAP_CONTROL_PREREAD,
  53  
  54    'Net::LDAP::Control::PostRead'    => LDAP_CONTROL_POSTREAD,
  55  
  56    'Net::LDAP::Control::SyncRequest'    => LDAP_CONTROL_SYNC,
  57    'Net::LDAP::Control::SyncState'    => LDAP_CONTROL_SYNC_STATE,
  58    'Net::LDAP::Control::SyncDone'    => LDAP_CONTROL_SYNC_DONE,
  59    #
  60    #LDAP_CONTROL_PWEXPIRED
  61    #LDAP_CONTROL_PWEXPIRING
  62    #
  63    #LDAP_CONTROL_REFERRALS
  64  );
  65  
  66  my %Type2Pkg = reverse %Pkg2Type;
  67  
  68  sub register {
  69    my($class,$oid) = @_;
  70  
  71    require Carp and Carp::croak("$oid is already registered to $Type2Pkg{$oid}")
  72      if exists $Type2Pkg{$oid} and $Type2Pkg{$oid} ne $class;
  73  
  74    require Carp and Carp::croak("$class is already registered to $Pkg2Type{$class}")
  75      if exists $Pkg2Type{$class} and $Pkg2Type{$class} ne $oid;
  76  
  77    $Type2Pkg{$oid} = $class;
  78    $Pkg2Type{$class} = $oid;
  79  }
  80  
  81  sub new {
  82    my $self = shift;
  83    my $pkg  = ref($self) || $self;
  84    my $oid  = (@_ & 1) ? shift : undef;
  85    my %args = @_;
  86  
  87    $args{'type'} ||= $oid || $Pkg2Type{$pkg} || '';
  88  
  89    unless ($args{type} =~ /^\d+(?:\.\d+)+$/) {
  90      $args{error} = 'Invalid OID';
  91      return bless \%args;
  92    }
  93  
  94    if ($pkg eq __PACKAGE__ and exists $Type2Pkg{$args{type}}) {
  95      $pkg = $Type2Pkg{$args{type}};
  96      eval "require $pkg" or die $@;
  97    }
  98  
  99    delete $args{error};
 100  
 101    bless(\%args, $pkg)->init;
 102  }
 103  
 104  
 105  sub from_asn {
 106    my $self = shift;
 107    my $asn = shift;
 108    my $class = ref($self) || $self;
 109  
 110    if ($class eq __PACKAGE__ and exists $Type2Pkg{$asn->{type}}) {
 111      $class = $Type2Pkg{$asn->{type}};
 112      eval "require $class" or die $@;
 113    }
 114  
 115    delete $asn->{error};
 116  
 117    bless($asn, $class)->init;
 118  }
 119  
 120  sub to_asn {
 121    my $self = shift;
 122    $self->value; # Ensure value is there
 123    delete $self->{critical} unless $self->{critical};
 124    $self;
 125  }
 126  
 127  sub critical {
 128    my $self = shift;
 129    $self->{critical} = shift if @_;
 130    $self->{critical} || 0;
 131  }
 132  
 133  sub value    {
 134    my $self = shift;
 135    $self->{value} = shift if @_;
 136    $self->{value} || undef
 137  }
 138  
 139  sub type  { shift->{type} }
 140  sub valid { ! exists shift->{error} }
 141  sub error { shift->{error} }
 142  sub init  { shift }
 143  
 144  1;
 145  
 146  __END__
 147  
 148  
 149  =head1 NAME
 150  
 151  Net::LDAP::Control - LDAPv3 control object base class
 152  
 153  =head1 SYNOPSIS
 154  
 155   use Net::LDAP::Control;
 156   use Net::LDAP::Constant qw( LDAP_CONTROL_MATCHEDVALS );
 157  
 158   $ctrl = Net::LDAP::Control->new(
 159     type     => "1.2.3.4",
 160     value    => "help",
 161     critical => 0
 162   );
 163  
 164   $mesg = $ldap->search( @args, control => [ $ctrl ]);
 165  
 166   $ctrl = Net::LDAP::Control->new( type => LDAP_CONTROL_MATCHEDVALS );
 167  
 168  =head1 DESCRIPTION
 169  
 170  C<Net::LDAP::Control> is a base-class for LDAPv3 control objects.
 171  
 172  =cut
 173  
 174  ##
 175  ## Need more blurb in here about controls
 176  ##
 177  
 178  =head1 CONSTRUCTORS
 179  
 180  =over 4
 181  
 182  =item new ( ARGS )
 183  
 184  ARGS is a list of name/value pairs, valid arguments are:
 185  
 186  =over 4
 187  
 188  =item critical
 189  
 190  A boolean value, if TRUE and the control is unrecognized by the server or
 191  is inappropriate for the requested operation then the server will return
 192  an error and the operation will not be performed.
 193  
 194  If FALSE and the control is unrecognized by the server or
 195  is inappropriate for the requested operation then the server will ignore
 196  the control and perform the requested operation as if the control was
 197  not given.
 198  
 199  If absent, FALSE is assumed.
 200  
 201  =item type
 202  
 203  A dotted-decimal representation of an OBJECT IDENTIFIER which
 204  uniquely identifies the control. This prevents conflicts between
 205  control names.
 206  
 207  This may be ommitted if the contructor is being called on a sub-class of
 208  Net::LDAP::Control which has registered to be associated with an OID.
 209  If the contructor is being called on the Net::LDAP::Control
 210  package, then this argument must be given.  If the given OID has been
 211  registered by a package, then the returned object will be of the type
 212  registered to handle that OID.
 213  
 214  =item value
 215  
 216  Optional information associated with the control. It's format is specific
 217  to the particular control.
 218  
 219  =back
 220  
 221  =item from_asn ( ASN )
 222  
 223  ASN is a HASH reference, normally extracted from a PDU. It will contain
 224  a C<type> element and optionally C<critical> and C<value> elements. On
 225  return ASN will be blessed into a package. If C<type> is a registered
 226  OID, then ASN will be blessed into the registered package, if not then ASN
 227  will be blessed into Net::LDAP::Control.
 228  
 229  This constructor is used internally by Net::LDAP and assumes that HASH
 230  passed contains a valid control. It should be used with B<caution>.
 231  
 232  =back
 233  
 234  =head1 METHODS
 235  
 236  In addition to the methods listed below, each of the named parameters
 237  to C<new> is also avaliable as a method. C<type> will return the OID of
 238  the control object. C<value> and C<critical> are set/get methods and will
 239  return the current value for each attribute if called without arguments,
 240  but may also be called with arguments to set new values.
 241  
 242  =over 4
 243  
 244  =item error ()
 245  
 246  If there has been an error returns a description of the error, otherwise it will
 247  return C<undef>
 248  
 249  =item init ()
 250  
 251  C<init> will be called as the last step in both contructors. What it does will depend
 252  on the sub-class. It must always return the object.
 253  
 254  =item register ( OID )
 255  
 256  C<register> is provided for sub-class implementors. It should be called as a class method
 257  on a sub-class of Net::LDAP::Control with the OID that the class will handle. Net::LDAP::Control
 258  will remember this class and OID pair and use it in the following
 259  situations.
 260  
 261  =over 4
 262  
 263  =item *
 264  
 265  C<new> is called as a class method on the Net::LDAP::Control package and OID is passed
 266  as the type. The returned object will be blessed into the package that registered
 267  the OID.
 268  
 269  =item *
 270  
 271  C<new> is called as a class method on a registered package and the C<type> is not
 272  specified. The C<type> will be set to the OID registered by that package.
 273  
 274  =item *
 275  
 276  C<from_asn> is called to construct an object from ASN. The returned object will be
 277  blessed into the package which was registered to handle the OID in the ASN.
 278  
 279  =back
 280  
 281  =item ( to_asn )
 282  
 283  Returns a structure suitable for passing to Convert::ASN1 for
 284  encoding. This method will be called by L<Net::LDAP> when the
 285  control is used.
 286  
 287  The base class implementation of this method will call the C<value> method
 288  without arguments to allow a sub-class to encode it's value. Sub-classes
 289  should not need to override this method.
 290  
 291  =item valid ()
 292  
 293  Returns true if the object is valid and can be encoded. The default implementation
 294  for this method is to return TRUE if there is no error, but sub-classes may override that.
 295  
 296  =back
 297  
 298  =head1 SEE ALSO
 299  
 300  L<Net::LDAP>
 301  L<Net::LDAP::Control::EntryChange>
 302  L<Net::LDAP::Control::ManageDsaIT>
 303  L<Net::LDAP::Control::Paged>
 304  L<Net::LDAP::Control::PasswordPolicy>
 305  L<Net::LDAP::Control::PersistentSearch>
 306  L<Net::LDAP::Control::PostRead>
 307  L<Net::LDAP::Control::PreRead>
 308  L<Net::LDAP::Control::ProxyAuth>
 309  L<Net::LDAP::Control::Sort>
 310  L<Net::LDAP::Control::SortResult>
 311  L<Net::LDAP::Control::SyncDone>
 312  L<Net::LDAP::Control::SyncRequest>
 313  L<Net::LDAP::Control::SyncState>
 314  L<Net::LDAP::Control::VLV>
 315  L<Net::LDAP::Control::VLVResponse>
 316  
 317  =head1 AUTHOR
 318  
 319  Graham Barr E<lt>gbarr@pobox.comE<gt>
 320  
 321  Please report any bugs, or post any suggestions, to the perl-ldap mailing list
 322  E<lt>perl-ldap@perl.orgE<gt>
 323  
 324  =head1 COPYRIGHT
 325  
 326  Copyright (c) 1999-2004 Graham Barr. All rights reserved. This program is
 327  free software; you can redistribute it and/or modify it under the same
 328  terms as Perl itself.
 329  
 330  =cut