[ Index ] |
PHP Cross Reference of Unnamed Project |
[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
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
Generated: Tue Mar 17 22:47:18 2015 | Cross-referenced by PHPXref 0.7.1 |