295 lines
7.1 KiB
Text
295 lines
7.1 KiB
Text
=head1 NAME
|
|
|
|
Net::LDAP::Entry - An LDAP entry object
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
use Net::LDAP;
|
|
|
|
$ldap = Net::LDAP->new($host);
|
|
$mesg = $ldap->search(@search_args);
|
|
|
|
my $max = $mesg->count;
|
|
for($i = 0 ; $i < $max ; $i++) {
|
|
my $entry = $mesg->entry($i);
|
|
foreach my $attr ($entry->attributes) {
|
|
print join("\n ",$attr, $entry->get_value($attr)),"\n";
|
|
}
|
|
}
|
|
|
|
# or
|
|
|
|
use Net::LDAP::Entry;
|
|
|
|
$entry = Net::LDAP::Entry->new;
|
|
|
|
$entry->add(
|
|
attr1 => 'value1',
|
|
attr2 => [qw(value1 value2)]
|
|
);
|
|
|
|
$entry->delete( 'unwanted' );
|
|
|
|
$entry->replace(
|
|
attr1 => 'newvalue'
|
|
attr2 => [qw(new values)]
|
|
);
|
|
|
|
$entry->update( $ldap ); # update directory server
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
The B<Net::LDAP::Entry> object represents a single entry in the directory.
|
|
It is a container for attribute-value pairs.
|
|
|
|
A B<Net::LDAP::Entry> object can be used in two situations. The first and
|
|
probably most common use is in the result of a search to the directory
|
|
server.
|
|
|
|
The other is where a new object is created locally and then a single
|
|
command is sent to the directory server to add, modify or replace an
|
|
entry. Entries for this purpose can also be created by reading an
|
|
LDIF file with the L<Net::LDAP::LDIF> module.
|
|
|
|
=head1 CONSTRUCTOR
|
|
|
|
=over 4
|
|
|
|
=item new
|
|
|
|
Create a new entry object with the changetype set to C<'add'>
|
|
|
|
=back
|
|
|
|
=head1 METHODS
|
|
|
|
=over 4
|
|
|
|
|
|
|
|
=item add ( ATTR => VALUE [, ATTR2 => VALUE2 ... ] )
|
|
|
|
Add one or more new attributes to the entry. Each value
|
|
must be a scalar variable or a reference to an array. The
|
|
values given will be added to the values which already exist
|
|
for the given attributes.
|
|
|
|
$entry->add( 'sn' => 'Barr');
|
|
|
|
$entry->add( 'street' => [ '1 some road','nowhere']);
|
|
|
|
B<NOTE>: these changes are local to the client and will not
|
|
appear on the directory server until the C<update> method
|
|
is called.
|
|
|
|
|
|
|
|
=item attributes ( [ OPTIONS ] )
|
|
|
|
Return a list of attributes that this entry has.
|
|
|
|
OPTIONS is a list of name/value pairs, valid options are :-
|
|
|
|
=over 4
|
|
|
|
=item nooptions
|
|
|
|
If TRUE, return a list of the attribute names excluding any options. For example for the entry
|
|
|
|
name: Graham Barr
|
|
name;en-us: Bob
|
|
jpeg;binary: **binary data**
|
|
|
|
then
|
|
|
|
@values = $entry->attributes()
|
|
print "default: @values\n";
|
|
|
|
@values = $entry->attributes( nooptions => 1);
|
|
print "nooptions: @values\n";
|
|
|
|
will output
|
|
|
|
default: name name;en-us jpeg;binary
|
|
nooptions: name jpeg
|
|
|
|
=back
|
|
|
|
|
|
|
|
=item changetype ( [ TYPE ] )
|
|
|
|
If called without arguments it returns the type of operation that would
|
|
be performed when the update method is called. If called with an argument
|
|
it will set the changetype to TYPE.
|
|
|
|
Possible values for TYPE are
|
|
|
|
=over 4
|
|
|
|
=item add
|
|
|
|
The update method will call the add method on the client object, which
|
|
will result in the entry being added to the directory server.
|
|
|
|
=item delete
|
|
|
|
The update method will call the delete method on the client object, which
|
|
will result in the entry being removed from the directory server.
|
|
|
|
=item modify
|
|
|
|
The update method will call the modify method on the client object, which
|
|
will result in any changes that have been made locally being made to the
|
|
entry on the directory server.
|
|
|
|
=item moddn/modrdn
|
|
|
|
The update method will call the moddn method on the client object, which
|
|
will result in any DN changes that have been made locally being made
|
|
to the entry on the directory server. These DN changes are specified by
|
|
setting the entry attributes newrdn, deleteoldrdn, and (optionally) newsuperior.
|
|
|
|
=back
|
|
|
|
|
|
|
|
=item delete ( [ ATTR [, ATTR2 ... ]] )
|
|
|
|
Delete the given attributes from the entry. If no attributes
|
|
are passed then the next call to update will cause the entry
|
|
to be deleted from the server.
|
|
|
|
B<NOTE>: these changes are local to the client and will not
|
|
appear on the directory server until the C<update> method
|
|
is called.
|
|
|
|
|
|
|
|
=item dn ( [ DN ] )
|
|
|
|
Set or get the DN for the entry. With no arguments C<dn> will return
|
|
the current DN. If an argument is given then it will change the DN
|
|
for the entry and return the previous value.
|
|
|
|
B<NOTE>: these changes are local to the client and will not
|
|
appear on the directory server until the C<update> method
|
|
is called.
|
|
|
|
|
|
|
|
=item exists ( ATTR )
|
|
|
|
Returns TRUE if the entry has an attribute called ATTR.
|
|
|
|
|
|
|
|
=item get_value ( ATTR [, OPTIONS ] )
|
|
|
|
Get the values for the attribute ATTR. In a list context returns all
|
|
values for the given attribute, or the empty list if the attribute does
|
|
not exist. In a scalar context returns the first value for the attribute
|
|
or undef if the attribute does not exist.
|
|
|
|
The return value may be changed by OPTIONS, which is a list of name => value
|
|
pairs, valid options are :-
|
|
|
|
=over 4
|
|
|
|
=item alloptions
|
|
|
|
If TRUE then the result will be a hash reference. The keys of the hash
|
|
will be the options and the hash value will be the values for those attributes.
|
|
For example if an entry had
|
|
|
|
name: Graham Barr
|
|
name;en-us: Bob
|
|
|
|
Then a get for attribute "name" with alloptions set to a true value
|
|
|
|
$ref = $entry->get_value( 'name', alloptions => 1);
|
|
|
|
will return a hash reference that would be like
|
|
|
|
{
|
|
'' => [ 'Graham Barr' ],
|
|
';en-us' => [ 'Bob' ]
|
|
}
|
|
|
|
=item asref
|
|
|
|
If TRUE then the result will be a reference to an array containing all the
|
|
values for the attribute, or undef if the attribute does not exist.
|
|
|
|
$scalar = $entry->get_value('name');
|
|
|
|
$scalar will be the first value for the C<name> attribute, or C<undef> if the
|
|
entry does not contain a C<name> attribute.
|
|
|
|
$ref = $entry->get_value('name', asref => 1);
|
|
|
|
$ref will be a reference to an array, which will have all the values for
|
|
the C<name> attribute. If the entry does not have an attribute called C<name>
|
|
then $ref will be C<undef>
|
|
|
|
=back
|
|
|
|
B<NOTE>: In the interest of performance the array references returned by C<get_value>
|
|
are references to structures held inside the entry object. These values and
|
|
thier contents should B<NOT> be modified directly.
|
|
|
|
|
|
|
|
=item replace ( ATTR => VALUE [, ATTR2 => VALUE2 ... ] )
|
|
|
|
Similar to add, except that the values given will replace
|
|
any values that already exist for the given attributes.
|
|
|
|
B<NOTE>: these changes are local to the client and will not
|
|
appear on the directory server until the C<update> method
|
|
is called.
|
|
|
|
|
|
|
|
=item update ( CLIENT )
|
|
|
|
Update the directory server with any changes that have been made locally
|
|
to the attributes of this entry. This means any calls that have been
|
|
made to add, replace or delete since the last call to changetype or
|
|
update was made.
|
|
|
|
This method can also be used to modify the DN of the entry on the server,
|
|
by specifying moddn or modrdn as the changetype, and setting the entry
|
|
attributes newrdn, deleteoldrdn, and (optionally) newsuperior.
|
|
|
|
CLIENT is a C<Net::LDAP> object where the update will be sent to.
|
|
|
|
The result will be an object of type
|
|
L<Net::LDAP::Message> as returned by the add, modify
|
|
or delete method called on CLIENT.
|
|
|
|
=back
|
|
|
|
=head1 SEE ALSO
|
|
|
|
L<Net::LDAP>,
|
|
L<Net::LDAP::LDIF>
|
|
|
|
=head1 AUTHOR
|
|
|
|
Graham Barr <gbarr@pobox.com>.
|
|
|
|
Please report any bugs, or post any suggestions, to the perl-ldap mailing list
|
|
<perl-ldap-dev@lists.sourceforge.net>.
|
|
|
|
=head1 COPYRIGHT
|
|
|
|
Copyright (c) 1997-2000 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.
|
|
|
|
=for html <hr>
|
|
|
|
I<$Id$>
|
|
|
|
=cut
|