Net::LDAP::Control(3pmUser Contributed Perl DocumentatiNet::LDAP::Control(3pm)
NAME
Net::LDAP::Control - LDAPv3 control object base class
SYNOPSIS
use Net::LDAP::Control;
use Net::LDAP::Constant qw( LDAP_CONTROL_MANAGEDSAIT );
my $req_ctrl1 = Net::LDAP::Control->new( type => LDAP_CONTROL_MANAGEDSAIT );
my $req_ctrl2 = Net::LDAP::Control->new(
type => "1.2.3.4",
value => "help",
critical => 0
);
$mesg = $ldap->search( @args, control => [ $req_ctrl1, $req_ctrl2 ]);
my @res_ctrls = $mesg->control();
DESCRIPTION
"Net::LDAP::Control" is the base-class for LDAPv3 control objects.
Controls provide a mechanism that allows one to extend the semantics
and arguments of LDAP operations. Controls may be attached to LDAP
operations, and only affect the semantics of the operation they are
attached to.
Controls sent by clients are termed request controls, and are set using
the "control" option of the respective LDAP operations. Controls sent
by servers are called response controls, they can be found using the
"control()" method of the response message objects.
Servers announce the controls they support in the attribute
"supportedControls" in their RootDSE.
CONSTRUCTORS
new ( ARGS )
ARGS is a list of name/value pairs, valid arguments are:
critical
A Boolean value, if TRUE and the control is unrecognized by the
server or is inappropriate for the requested operation then the
server will return an error and the operation will not be
performed.
If FALSE and the control is unrecognized by the server or is
inappropriate for the requested operation then the server will
ignore the control and perform the requested operation as if
the control was not given.
If absent, FALSE is assumed.
type
A dotted-decimal representation of an OBJECT IDENTIFIER which
uniquely identifies the control. This prevents conflicts
between control names.
This may be omitted if the constructor is being called on a
sub-class of Net::LDAP::Control which has registered to be
associated with an OID. If the constructor is being called on
the Net::LDAP::Control package, then this argument must be
given. If the given OID has been registered by a package, then
the returned object will be of the type registered to handle
that OID.
value
Optional information associated with the control. Its format is
specific to the particular control.
from_asn ( ASN )
ASN is a HASH reference, normally extracted from a PDU. It will
contain a "type" element and optionally "critical" and "value"
elements. On return ASN will be blessed into a package. If "type"
is a registered OID, then ASN will be blessed into the registered
package, if not then ASN will be blessed into Net::LDAP::Control.
This constructor is used internally by Net::LDAP and assumes that
HASH passed contains a valid control. It should be used with
caution.
METHODS
In addition to the methods listed below, each of the named parameters
to "new" is also available as a method. "type" will return the OID of
the control object. "value" and "critical" are set/get methods and will
return the current value for each attribute if called without
arguments, but may also be called with arguments to set new values.
error ()
If there has been an error returns a description of the error,
otherwise it will return "undef"
init ()
"init" will be called as the last step in both constructors. What
it does will depend on the sub-class. It must always return the
object.
register ( OID )
"register" is provided for sub-class implementors. It should be
called as a class method on a sub-class of Net::LDAP::Control with
the OID that the class will handle. Net::LDAP::Control will
remember this class and OID pair and use it in the following
situations.
• "new" is called as a class method on the Net::LDAP::Control
package and OID is passed as the type. The returned object will
be blessed into the package that registered the OID.
• "new" is called as a class method on a registered package and
the "type" is not specified. The "type" will be set to the OID
registered by that package.
• "from_asn" is called to construct an object from ASN. The
returned object will be blessed into the package which was
registered to handle the OID in the ASN.
( to_asn )
Returns a structure suitable for passing to Convert::ASN1 for
encoding. This method will be called by Net::LDAP when the control
is used.
The base class implementation of this method will call the "value"
method without arguments to allow a sub-class to encode it's value.
Sub-classes should not need to override this method.
valid ()
Returns true if the object is valid and can be encoded. The default
implementation for this method is to return TRUE if there is no
error, but sub-classes may override that.
SEE ALSO
Net::LDAP, Net::LDAP::RootDSE, Net::LDAP::Control::Assertion,
Net::LDAP::Control::DontUseCopy, Net::LDAP::Control::EntryChange,
Net::LDAP::Control::ManageDsaIT, Net::LDAP::Control::MatchedValues,
Net::LDAP::Control::Paged, Net::LDAP::Control::PasswordPolicy,
Net::LDAP::Control::PersistentSearch, Net::LDAP::Control::PostRead,
Net::LDAP::Control::PreRead, Net::LDAP::Control::ProxyAuth,
Net::LDAP::Control::Relax, Net::LDAP::Control::Sort,
Net::LDAP::Control::SortResult, Net::LDAP::Control::SyncDone,
Net::LDAP::Control::SyncRequest, Net::LDAP::Control::SyncState,
Net::LDAP::Control::TreeDelete, Net::LDAP::Control::VLV,
Net::LDAP::Control::VLVResponse
AUTHOR
Graham Barr <gbarr@pobox.com>
Please report any bugs, or post any suggestions, to the perl-ldap
mailing list <perl-ldap@perl.org>
COPYRIGHT
Copyright (c) 1999-2004 Graham Barr. All rights reserved. This program
is free software; you can redistribute it and/or modify it under the
same terms as Perl itself.
perl v5.32.0 2021-01-03 Net::LDAP::Control(3pm)
Generated by dwww version 1.15 on Mon Jun 24 09:17:03 CEST 2024.