NAME¶
Net::LDAP::Entry - An LDAP entry object
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->dn($dn);
$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
$entry2 = $entry->clone; # copies entry
# new alternate syntax
$entry = Net::LDAP::Entry->new ( $dn
, attr1 => 'value1'
, attr2 => [ qw(value1 value2) ]
)->add(
attr3 => 'value'
)->update( $ldap );
DESCRIPTION¶
The
Net::LDAP::Entry object represents a single entry in the directory.
It is a container for attribute-value pairs.
A
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
Net::LDAP::LDIF module.
CONSTRUCTORS¶
- new ( )
- Create a new entry object with the changetype set to 'add'.
Optionally, you can provide a DN and a list of arguments passed to the add
method.
Net::LDAP::Entry->new()
# or
Net::LDAP::Entry->new( $dn )
# or
Net::LDAP::Entry->new( $dn ,
objectClass => [qw( top posixAccount )] , uid => 'admin'
)
- clone ( )
- Returns a copy of the Net::LDAP::Entry object.
METHODS¶
- add ( ATTR => VALUE, ... )
- Add more attributes or values to the entry and returns the
entry itself. Each "VALUE" should be a string if only a single
value is wanted in the attribute, or a reference to an array of strings if
multiple values are wanted. 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' ] );
NOTE: these changes are local to the client and will not appear on
the directory server until the "update" method is called. As
"add" returns the entry, you can write something like.
$entry->add ( 'sn' => 'Barr' )->update( $ldap );
- attributes ( OPTIONS )
- Return a list of attributes in this entry
- nooptions => 1
- 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
- changetype ( )
- Returns the type of operation that would be performed when
the update method is called.
- changetype ( TYPE )
- Set the type of operation that will be performed when the
update method is called to "TYPE". Returns the entry itself.
Possible values for "TYPE" are
- 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.
- 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.
$entry->delete->update( $ldap )
- 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.
- 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.
- delete ( )
- Delete the entry from the server on the next call to
"update".
- delete ( ATTR => [ VALUE, ... ], ... )
- Delete the values of given attributes from the entry.
Values are references to arrays; passing a reference to an empty array is
the same as passing "undef", and will result in the entire
attribute being deleted. For example:
$entry->delete ( 'mail' => [ 'foo.bar@example.com' ] );
$entry->delete ( 'description' => [ ], 'streetAddress' => [ ] );
NOTE: these changes are local to the client and will not appear on
the directory server until the "update" method is called.
- dn ( )
- Get the DN of the entry.
- dn ( DN )
- Set the DN for the entry, and return the previous value.
NOTE: these changes are local to the client and will not appear on
the directory server until the "update" method is called.
- ldif ( OPTION => VALUE, ... )
- Returns the entry as an LDIF string. Possible options
are
- change => VALUE
- If given a true value then the LDIF will be generated as a
change record. If false, then the LDIF generated will represent the entry
content. If unspecified then it will default to true if the entry has
changes and false if no changes have been applied to the entry.
- dump ( [ FILEHANDLE ] )
- Dump the entry to the given filehandle.
This method is intended for debugging purposes and does not treat binary
attributes specially.
See Net::LDAP::LDIF on how to generate LDIF output.
If "FILEHANDLE" is omitted "STDOUT" is used by
default.
- exists ( ATTR )
- Returns "TRUE" if the entry has an attribute
called "ATTR".
- 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.
- alloptions => 1
- 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' ]
}
If alloptions is not set or is set to false only the attribute values for
the exactly matching name are returned.
- asref => 1
- 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 "name" attribute, or
"undef" if the entry does not contain a "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
"name" attribute. If the entry does not have an attribute called
"name" then $ref will be "undef".
NOTE: In the interest of performance the array references returned by
"get_value" are references to structures held inside the entry
object. These values and thier contents should
NOT be modified
directly.
- replace ( ATTR => VALUE, ... )
- Similar to "add", except that the values given
will replace any values that already exist for the given attributes.
NOTE: these changes are local to the client and will not appear on
the directory server until the "update" method is called.
- update ( CLIENT [, OPTIONS ] )
- 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 "Net::LDAP" object where the update will
be sent to.
"OPTIONS" may be options to the "Net::LDAP" actions on
CLIENT corresponding to the entry's changetype.
The result will be an object of type Net::LDAP::Message as returned by the
add, modify or delete method called on CLIENT.
SEE ALSO¶
Net::LDAP, Net::LDAP::LDIF
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) 1997-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.