[Summary view] [Print] [Text view]

   1  =head1 NAME
   2  
   3  Net::LDAP::Entry - An LDAP entry object
   4  
   5  =head1 SYNOPSIS
   6  
   7   use Net::LDAP;
   8  
   9   $ldap = Net::LDAP->new ( $host );
  10   $mesg = $ldap->search ( @search_args );
  11  
  12   my $max = $mesg->count;
  13   for ( $i = 0 ; $i < $max ; $i++ ) {
  14     my $entry = $mesg->entry ( $i );
  15     foreach my $attr ( $entry->attributes ) {
  16       print join( "\n ", $attr, $entry->get_value( $attr ) ), "\n";
  17     }
  18   }
  19  
  20   # or
  21  
  22   use Net::LDAP::Entry;
  23  
  24   $entry = Net::LDAP::Entry->new;
  25  
  26   $entry->dn($dn);
  27  
  28   $entry->add (
  29     attr1 => 'value1',
  30     attr2 => [ qw(value1 value2) ]
  31   );
  32  
  33   $entry->delete ( 'unwanted' );
  34  
  35   $entry->replace (
  36     attr1 => 'newvalue'
  37     attr2 => [ qw(new values) ]
  38   );
  39  
  40   $entry->update ( $ldap ); # update directory server
  41  
  42   $entry2 = $entry->clone; # copies entry
  43  
  44   # new alternate syntax
  45  
  46   $entry = Net::LDAP::Entry->new ( $dn 
  47     , attr1 => 'value1'
  48     , attr2 => [ qw(value1 value2) ]
  49   )->add(
  50     attr3   => 'value'
  51   )->update( $ldap );
  52  
  53  
  54  
  55  
  56  =head1 DESCRIPTION
  57  
  58  The B<Net::LDAP::Entry> object represents a single entry in the
  59  directory.  It is a container for attribute-value pairs.
  60  
  61  A B<Net::LDAP::Entry> object can be used in two situations. The first
  62  and probably most common use is in the result of a search to the
  63  directory server.
  64  
  65  The other is where a new object is created locally and then a single
  66  command is sent to the directory server to add, modify or replace an
  67  entry. Entries for this purpose can also be created by reading an LDIF
  68  file with the L<Net::LDAP::LDIF> module.
  69  
  70  =head1 CONSTRUCTORS
  71  
  72  =over 4
  73  
  74  =item new ( )
  75  
  76  Create a new entry object with the changetype set to C<'add'>.
  77  Optionally, you can provide a DN and a list of arguments passed to the
  78  add method.
  79  
  80   Net::LDAP::Entry->new()
  81  
  82   # or 
  83   Net::LDAP::Entry->new( $dn )
  84  
  85   # or 
  86   Net::LDAP::Entry->new( $dn ,
  87    objectClass => [qw( top posixAccount )] , uid => 'admin' 
  88   )
  89  
  90  
  91  =item clone ( )
  92  
  93  Returns a copy of the B<Net::LDAP::Entry> object.
  94  
  95  =back
  96  
  97  =head1 METHODS
  98  
  99  =over 4
 100  
 101  =item add ( ATTR =E<gt> VALUE, ... )
 102  
 103  Add more attributes or values to the entry and returns the entry itself. Each
 104  C<VALUE> should be a string if only a single value is wanted in the attribute,
 105  or a reference to an array of strings if multiple values are wanted. The values
 106  given will be added to the values which already exist for the given attributes.
 107  
 108   $entry->add ( 'sn' => 'Barr' );
 109  
 110   $entry->add ( 'street' => [ '1 some road','nowhere' ] );
 111  
 112  B<NOTE>: these changes are local to the client and will not appear on
 113  the directory server until the C<update> method is called. As C<add> returns the
 114  entry, you can write something like.
 115   
 116   $entry->add ( 'sn' => 'Barr' )->update( $ldap );
 117  
 118  
 119  =item attributes ( OPTIONS )
 120  
 121  Return a list of attributes in this entry
 122  
 123  =over 4
 124  
 125  =item nooptions =E<gt> 1
 126  
 127  Return a list of the attribute names excluding any options. For
 128  example for the entry
 129  
 130    name: Graham Barr
 131    name;en-us: Bob
 132    jpeg;binary: **binary data**
 133  
 134  then
 135  
 136    @values = $entry->attributes;
 137    print "default: @values\n";
 138  
 139    @values = $entry->attributes ( nooptions => 1 );
 140    print "nooptions: @values\n";
 141  
 142  will output
 143  
 144    default: name name;en-us jpeg;binary
 145    nooptions: name jpeg
 146  
 147  =back
 148  
 149  =item changetype ( )
 150  
 151  Returns the type of operation that would be performed when the update
 152  method is called.
 153  
 154  =item changetype ( TYPE )
 155  
 156  Set the type of operation that will be performed when the update
 157  method is called to C<TYPE>. Returns the entry itself.
 158  
 159  Possible values for C<TYPE> are
 160  
 161  =over 4
 162  
 163  =item add
 164  
 165  The update method will call the add method on the client object, which
 166  will result in the entry being added to the directory server.
 167  
 168  =item delete
 169  
 170  The update method will call the delete method on the client object,
 171  which will result in the entry being removed from the directory
 172  server.
 173  
 174   $entry->delete->update( $ldap )
 175  
 176  =item modify
 177  
 178  The update method will call the modify method on the client object,
 179  which will result in any changes that have been made locally being
 180  made to the entry on the directory server.
 181  
 182  =item moddn/modrdn
 183  
 184  The update method will call the moddn method on the client object,
 185  which will result in any DN changes that have been made locally being
 186  made to the entry on the directory server. These DN changes are
 187  specified by setting the entry attributes newrdn, deleteoldrdn, and
 188  (optionally) newsuperior.
 189  
 190  =back
 191  
 192  =item delete ( )
 193  
 194  Delete the entry from the server on the next call to C<update>.
 195  
 196  =item delete ( ATTR =E<gt> [ VALUE, ... ], ... )
 197  
 198  Delete the values of given attributes from the entry. Values are
 199  references to arrays; passing a reference to an empty array is the
 200  same as passing C<undef>, and will result in the entire attribute
 201  being deleted. For example:
 202  
 203   $entry->delete ( 'mail' => [ 'foo.bar@example.com' ] );
 204   $entry->delete ( 'description' => [ ], 'streetAddress' => [ ] );
 205  
 206  B<NOTE>: these changes are local to the client and will not appear on
 207  the directory server until the C<update> method is called.
 208  
 209  =item dn ( )
 210  
 211  Get the DN of the entry.
 212  
 213  =item dn ( DN )
 214  
 215  Set the DN for the entry, and return the previous value.
 216  
 217  B<NOTE>: these changes are local to the client and will not appear on
 218  the directory server until the C<update> method is called.
 219  
 220  =item dump ( [ FILEHANDLE ] )
 221  
 222  Dump the entry to the given filehandle. 
 223  
 224  This method is intended for debugging purposes and does not
 225  treat binary attributes specially.
 226  
 227  See L<Net::LDAP::LDIF> on how to generate LDIF output.
 228  
 229  If C<FILEHANDLE> is omitted C<STDOUT> is used by default.
 230  
 231  
 232  =item exists ( ATTR )
 233  
 234  Returns C<TRUE> if the entry has an attribute called C<ATTR>.
 235  
 236  =item get_value ( ATTR, OPTIONS )
 237  
 238  Get the values for the attribute C<ATTR>. In a list context returns
 239  all values for the given attribute, or the empty list if the attribute
 240  does not exist. In a scalar context returns the first value for the
 241  attribute or undef if the attribute does not exist.
 242  
 243  =over 4
 244  
 245  =item alloptions =E<gt> 1
 246  
 247  The result will be a hash reference. The keys of the hash will be the
 248  options and the hash value will be the values for those attributes.
 249  For example if an entry had:
 250  
 251   name: Graham Barr
 252   name;en-us: Bob
 253  
 254  Then a get for attribute "name" with alloptions set to a true value
 255  
 256   $ref = $entry->get_value ( 'name', alloptions => 1 );
 257  
 258  will return a hash reference that would be like
 259  
 260   {
 261     ''       => [ 'Graham Barr' ],
 262     ';en-us' => [ 'Bob' ]
 263   }
 264  
 265  If alloptions is not set or is set to false only the attribute values
 266  for the exactly matching name are returned.
 267  
 268  =item asref =E<gt> 1
 269  
 270  The result will be a reference to an array containing all the values
 271  for the attribute, or C<undef> if the attribute does not exist.
 272  
 273   $scalar = $entry->get_value ( 'name' );
 274  
 275  $scalar will be the first value for the C<name> attribute, or C<undef>
 276  if the entry does not contain a C<name> attribute.
 277  
 278   $ref = $entry->get_value ( 'name', asref => 1 );
 279  
 280  $ref will be a reference to an array, which will have all the values
 281  for the C<name> attribute. If the entry does not have an attribute
 282  called C<name> then $ref will be C<undef>.
 283  
 284  =back
 285  
 286  B<NOTE>: In the interest of performance the array references returned
 287  by C<get_value> are references to structures held inside the entry
 288  object. These values and thier contents should B<NOT> be modified
 289  directly.
 290  
 291  =item replace ( ATTR =E<gt> VALUE, ... )
 292  
 293  Similar to C<add>, except that the values given will replace any
 294  values that already exist for the given attributes.
 295  
 296  B<NOTE>: these changes are local to the client and will not appear on
 297  the directory server until the C<update> method is called.
 298  
 299  =item update ( CLIENT [, OPTIONS ] )
 300  
 301  Update the directory server with any changes that have been made
 302  locally to the attributes of this entry. This means any calls that
 303  have been made to add, replace or delete since the last call to
 304  changetype or update was made.
 305  
 306  This method can also be used to modify the DN of the entry on the
 307  server, by specifying moddn or modrdn as the changetype, and setting
 308  the entry attributes newrdn, deleteoldrdn, and (optionally)
 309  newsuperior.
 310  
 311  C<CLIENT> is a C<Net::LDAP> object where the update will be sent to.
 312  
 313  C<OPTIONS> may be options to the C<Net::LDAP> actions on CLIENT
 314  corresponding to the entry's changetype.
 315  
 316  The result will be an object of type L<Net::LDAP::Message> as returned
 317  by the add, modify or delete method called on CLIENT.
 318  
 319  =back
 320  
 321  =head1 SEE ALSO
 322  
 323  L<Net::LDAP>,
 324  L<Net::LDAP::LDIF>
 325  
 326  =head1 AUTHOR
 327  
 328  Graham Barr E<lt>gbarr@pobox.comE<gt>.
 329  
 330  Please report any bugs, or post any suggestions, to the perl-ldap
 331  mailing list E<lt>perl-ldap@perl.orgE<gt>.
 332  
 333  =head1 COPYRIGHT
 334  
 335  Copyright (c) 1997-2004 Graham Barr. All rights reserved. This program
 336  is free software; you can redistribute it and/or modify it under the
 337  same terms as Perl itself.
 338  
 339  =cut