[Summary view] [Print] [Text view]

   1  # Copyright (c) 2008 Mathieu Parent <math.parent@gmail.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::Intermediate;
   6  
   7  use vars qw($VERSION);
   8  use strict;
   9  
  10  use Net::LDAP::Constant qw(
  11    LDAP_SYNC_INFO
  12  );
  13  
  14  $VERSION = "0.02";
  15  
  16  my %Class2ResponseName = (
  17  
  18    'Net::LDAP::Intermediate::SyncInfo'        => LDAP_SYNC_INFO,
  19  );
  20  
  21  my %ResponseName2Class = reverse %Class2ResponseName;
  22  
  23  sub register {
  24    my($class,$responseName) = @_;
  25  
  26    require Carp and Carp::croak("$responseName is already registered to $ResponseName2Class{$responseName}")
  27      if exists $ResponseName2Class{$responseName} and $ResponseName2Class{$responseName} ne $class;
  28  
  29    require Carp and Carp::croak("$class is already registered to $Class2ResponseName{$class}")
  30      if exists $Class2ResponseName{$class} and $Class2ResponseName{$class} ne $responseName;
  31  
  32    $ResponseName2Class{$responseName} = $class;
  33    $Class2ResponseName{$class} = $responseName;
  34  }
  35  
  36  sub new {
  37    my $self = shift;
  38    my $class  = ref($self) || $self;
  39    my $responseName  = (@_ & 1) ? shift : undef;
  40    my %args = @_;
  41  
  42    $args{'responseName'} ||= $responseName || $Class2ResponseName{$class} || '';
  43  
  44    unless ($args{responseName} =~ /^\d+(?:\.\d+)+$/) {
  45      $args{error} = 'Invalid responseName';
  46      return bless \%args;
  47    }
  48  
  49    if ($class eq __PACKAGE__ and exists $ResponseName2Class{$args{responseName}}) {
  50      $class = $ResponseName2Class{$args{responseName}};
  51      eval "require $class" or die $@;
  52    }
  53  
  54    delete $args{error};
  55  
  56    bless(\%args, $class)->init;
  57  }
  58  
  59  
  60  sub from_asn {
  61    my $self = shift;
  62    my $asn = shift;
  63    my $class = ref($self) || $self;
  64  
  65    if ($class eq __PACKAGE__ and exists $ResponseName2Class{$asn->{responseName}}) {
  66      $class = $ResponseName2Class{$asn->{responseName}};
  67      eval "require $class" or die $@;
  68    }
  69  
  70    delete $asn->{error};
  71  
  72    bless($asn, $class)->init;
  73  }
  74  
  75  sub to_asn {
  76    my $self = shift;
  77    $self->responseValue; # Ensure value is there
  78    $self;
  79  }
  80  
  81  sub responseName  { shift->{responseName} }
  82  
  83  sub responseValue    {
  84    my $self = shift;
  85    $self->{responseValue} = shift if @_;
  86    $self->{responseValue} || undef
  87  }
  88  
  89  sub valid { ! exists shift->{error} }
  90  sub error { shift->{error} }
  91  sub init  { shift }
  92  
  93  1;
  94  
  95  __END__
  96  
  97  
  98  =head1 NAME
  99  
 100  Net::LDAP::Intermediate - LDAPv3 intermediate response object base class
 101  
 102  =head1 SYNOPSIS
 103  
 104   use Net::LDAP::Intermediate;
 105  
 106  =head1 DESCRIPTION
 107  
 108  C<Net::LDAP::Intermediate> is a base-class for LDAPv3 intermediate response objects.
 109  
 110  =cut
 111  
 112  ##
 113  ## Need more blurb in here about intermediate responses
 114  ##
 115  
 116  =head1 CONSTRUCTORS
 117  
 118  =over 4
 119  
 120  =item new ( ARGS )
 121  
 122  ARGS is a list of name/value pairs, valid arguments are:
 123  
 124  =over 4
 125  
 126  =item responseName
 127  
 128  A dotted-decimal representation of an OBJECT IDENTIFIER which
 129  uniquely identifies the intermediate response. This prevents conflicts between
 130  intermediate response names.
 131  
 132  =item responseValue
 133  
 134  Optional information associated with the intermediate response. It's format is specific
 135  to the particular intermediate response.
 136  
 137  =back
 138  
 139  =item from_asn ( ASN )
 140  
 141  ASN is a HASH reference, normally extracted from a PDU. It will contain
 142  a C<responseName> element and optionally C<responseValue> element. On
 143  return ASN will be blessed into a package. If C<responseName> is a registered
 144  OID, then ASN will be blessed into the registered package, if not then ASN
 145  will be blessed into Net::LDAP::Intermediate.
 146  
 147  This constructor is used internally by Net::LDAP and assumes that HASH
 148  passed contains a valid intermediate response. It should be used with B<caution>.
 149  
 150  =back
 151  
 152  =head1 METHODS
 153  
 154  In addition to the methods listed below, each of the named parameters
 155  to C<new> is also avaliable as a method. C<responseName> will return the OID of
 156  the intermediate response object. C<responseValue> is set/get methods and will
 157  return the current value for each attribute if called without arguments,
 158  but may also be called with arguments to set new values.
 159  
 160  =over 4
 161  
 162  =item error ()
 163  
 164  If there has been an error returns a description of the error, otherwise it will
 165  return C<undef>
 166  
 167  =item init ()
 168  
 169  C<init> will be called as the last step in both contructors. What it does will depend
 170  on the sub-class. It must always return the object.
 171  
 172  =item register ( OID )
 173  
 174  C<register> is provided for sub-class implementors. It should be called as a class method
 175  on a sub-class of Net::LDAP::Intermediate with the OID that the class will handle. Net::LDAP::Intermediate
 176  will remember this class and OID pair and use it in the following
 177  situations.
 178  
 179  =over 4
 180  
 181  =item *
 182  
 183  C<new> is called as a class method on the Net::LDAP::Intermediate package and OID is passed
 184  as the responseName. The returned object will be blessed into the package that registered
 185  the OID.
 186  
 187  =item *
 188  
 189  C<new> is called as a class method on a registered package and the C<responseName> is not
 190  specified. The C<responseName> will be set to the OID registered by that package.
 191  
 192  =item *
 193  
 194  C<from_asn> is called to construct an object from ASN. The returned object will be
 195  blessed into the package which was registered to handle the OID in the ASN.
 196  
 197  =back
 198  
 199  =item ( to_asn )
 200  
 201  Returns a structure suitable for passing to Convert::ASN1 for
 202  encoding. This method will be called by L<Net::LDAP> when the
 203  intermediate response is used.
 204  
 205  The base class implementation of this method will call the C<responseValue> method
 206  without arguments to allow a sub-class to encode it's value. Sub-classes
 207  should not need to override this method.
 208  
 209  =item valid ()
 210  
 211  Returns true if the object is valid and can be encoded. The default implementation
 212  for this method is to return TRUE if there is no error, but sub-classes may override that.
 213  
 214  =back
 215  
 216  =head1 SEE ALSO
 217  
 218  L<Net::LDAP>
 219  L<Net::LDAP::Extension>
 220  L<Net::LDAP::Search>
 221  L<Net::LDAP::Intermediate::SyncInfo>
 222  
 223  =head1 AUTHOR
 224  
 225  Mathieu Parent E<lt>math.parent@gmail.comE<gt>
 226  
 227  Please report any bugs, or post any suggestions, to the perl-ldap mailing list
 228  E<lt>perl-ldap@perl.orgE<gt>
 229  
 230  =head1 COPYRIGHT
 231  
 232  Copyright (c) 2008 Mathieu Parent. All rights reserved. This program is
 233  free software; you can redistribute it and/or modify it under the same
 234  terms as Perl itself.
 235  
 236  =cut