Net::LDAP::Entry - phpMan

Che Dong
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
              jpegPhoto;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 jpegPhoto;binary
              nooptions: name jpegPhoto

    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 AT 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:

        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.

        version => VALUE
            No matter what value is passed, it will be ignored, and treated
            as if 0 were given.

    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.

        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.

        nooptions => 1
            Instead of only returning the values of the exactly matching
            attribute name, get the attribute values of all attributes with
            the base name given. I.e. in the example above, calling

             @array = $entry->get_value ( 'name', nooptions => 1 );

            will yield

             ( 'Graham Barr', 'Bob' )

            The name of this option has neen chosen for consistency with the
            equally named option in the attributes method.

        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" may be references to structures held inside the entry
        object. These values and their 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.

        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
    Net::LDAP, Net::LDAP::LDIF

AUTHOR
    Graham Barr <gbarr AT pobox.com>.

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