unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (Debian-5.0)
Page:
Section:
Apropos / Subsearch:
optional field

Net::LDAP::Entry(3pm) User Contributed Perl DocumentationNet::LDAP::Entry(3pm)



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.barATexample.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.

       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 <gbarrATpobox.com>.

       Please report any bugs, or post any suggestions, to the perl-ldap
       mailing list <perl-ldapATperl.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.



perl v5.10.0                      2008-04-21             Net::LDAP::Entry(3pm)