NAME

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

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

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

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 all options "new" in Net::LDAP::LDIF allows, with two being treated special:

dump ( [ FILEHANDLE ] )

Dump the entry to the given filehandle.

This method is intended for debugging purposes and does not treat binary attributes specially. It also does not deal properly with entries resulting from LDIF change records.

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.

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.

Alternatively "CLIENT" can also be a "Net::LDAP::LDIF" object, that must be an LDIF file opened for writing.

In this case, the entry, together with any "OPTIONS" is passed as arguments to the "write_entry" method of the "CLIENT" object.

Here too, the result is an object class "Net::LDAP::Message". On error, the error code is "LDAP_OTHER" with the LDIF error message in the error text.

SEE ALSO

AUTHOR

Please report any bugs, or post any suggestions, to the perl-ldap mailing list <perl-ldap@perl.org>.

COPYRIGHT