1Net::LDAP::Entry(3) User Contributed Perl Documentation Net::LDAP::Entry(3)
2
6 Net::LDAP::Entry - An LDAP entry object
7
9 use Net::LDAP;
10 $ldap = Net::LDAP->new ( $host );
12 $mesg = $ldap->search ( @search_args );
13 my $max = $mesg->count;
15 for ( $i = 0 ; $i < $max ; $i++ ) {
16 my $entry = $mesg->entry ( $i );
17 foreach my $attr ( $entry->attributes ) {
18 print join( "\n ", $attr, $entry->get_value( $attr ) ), "\n";
19 }
20 }
21 # or
23 use Net::LDAP::Entry;
25 $entry = Net::LDAP::Entry->new;
27 $entry->dn($dn);
29 $entry->add (
31 attr1 => 'value1',
32 attr2 => [ qw(value1 value2) ]
33 );
34 $entry->delete ( 'unwanted' );
36 $entry->replace (
38 attr1 => 'newvalue',
39 attr2 => [ qw(new values) ]
40 );
41 $entry->update ( $ldap ); # update directory server
43 $entry2 = $entry->clone; # copies entry
45 # new alternate syntax
47 $entry = Net::LDAP::Entry->new ( $dn,
49 attr1 => 'value1',
50 attr2 => [ qw(value1 value2) ]
51 )->add(
52 attr3 => 'value'
53 )->update( $ldap );
54
56 The Net::LDAP::Entry object represents a single entry in the directory.
57 It is a container for attribute-value pairs.
58 A Net::LDAP::Entry object can be used in two situations. The first and
60 probably most common use is in the result of a search to the directory
61 server.
62 The other is where a new object is created locally and then a single
64 command is sent to the directory server to add, modify or replace an
65 entry. Entries for this purpose can also be created by reading an LDIF
66 file with the Net::LDAP::LDIF module.
67
69 new ( )
70 Create a new entry object with the changetype set to 'add'.
71 Optionally, you can provide a DN and a list of arguments passed to
72 the add method.
73 Net::LDAP::Entry->new()
75 # or
77 Net::LDAP::Entry->new( $dn )
78 # or
80 Net::LDAP::Entry->new( $dn ,
81 objectClass => [qw( top posixAccount )] , uid => 'admin'
82 )
83 clone ( )
85 Returns a copy of the Net::LDAP::Entry object.
86
88 add ( ATTR => VALUE, ... )
89 Add more attributes or values to the entry and returns the entry
90 itself. Each "VALUE" should be a string if only a single value is
91 wanted in the attribute, or a reference to an array of strings if
92 multiple values are wanted. The values given will be added to the
93 values which already exist for the given attributes.
94 $entry->add ( 'sn' => 'Barr' );
96 $entry->add ( 'street' => [ '1 some road','nowhere' ] );
98 NOTE: these changes are local to the client and will not appear on
100 the directory server until the "update" method is called. As "add"
101 returns the entry, you can write something like.
102 $entry->add ( 'sn' => 'Barr' )->update( $ldap );
104 attributes ( OPTIONS )
106 Return a list of attributes in this entry
107 nooptions => 1
109 Return a list of the attribute names excluding any options. For
110 example for the entry
111 name: Graham Barr
113 name;en-us: Bob
114 jpegPhoto;binary: **binary data**
115 then
117 @values = $entry->attributes;
119 print "default: @values\n";
120 @values = $entry->attributes ( nooptions => 1 );
122 print "nooptions: @values\n";
123 will output
125 default: name name;en-us jpegPhoto;binary
127 nooptions: name jpegPhoto
128 changetype ( )
130 Returns the type of operation that would be performed when the
131 update method is called.
132 changetype ( TYPE )
134 Set the type of operation that will be performed when the update
135 method is called to "TYPE". Returns the entry itself.
136 Possible values for "TYPE" are
138 add The update method will call the add method on the client
140 object, which will result in the entry being added to the
141 directory server.
142 delete
144 The update method will call the delete method on the client
145 object, which will result in the entry being removed from the
146 directory server.
147 $entry->delete->update( $ldap )
149 modify
151 The update method will call the modify method on the client
152 object, which will result in any changes that have been made
153 locally being made to the entry on the directory server.
154 moddn/modrdn
156 The update method will call the moddn method on the client
157 object, which will result in any DN changes that have been made
158 locally being made to the entry on the directory server. These
159 DN changes are specified by setting the entry attributes
160 newrdn, deleteoldrdn, and (optionally) newsuperior.
161 delete ( )
163 Delete the entry from the server on the next call to "update".
164 delete ( ATTR => [ VALUE, ... ], ... )
166 Delete the values of given attributes from the entry. Values are
167 references to arrays; passing a reference to an empty array is the
168 same as passing "undef", and will result in the entire attribute
169 being deleted. For example:
170 $entry->delete ( 'mail' => [ 'foo.bar@example.com' ] );
172 $entry->delete ( 'description' => [ ], 'streetAddress' => [ ] );
173 NOTE: these changes are local to the client and will not appear on
175 the directory server until the "update" method is called.
176 dn ( )
178 Get the DN of the entry.
179 dn ( DN )
181 Set the DN for the entry, and return the previous value.
182 NOTE: these changes are local to the client and will not appear on
184 the directory server until the "update" method is called.
185 ldif ( OPTION => VALUE, ... )
187 Returns the entry as an LDIF string. Possible options are all
188 options "new" in Net::LDAP::LDIF allows, with two being treated
189 special:
190 change => VALUE
192 If given a true value then the LDIF will be generated as a
193 change record. If false, then the LDIF generated will
194 represent the entry content. If unspecified then it will
195 default to true if the entry has changes and false if no
196 changes have been applied to the entry.
197 version => VALUE
199 No matter what value is passed, it will be ignored, and treated
200 as if 0 were given.
201 dump ( [ FILEHANDLE ] )
203 Dump the entry to the given filehandle.
204 This method is intended for debugging purposes and does not treat
206 binary attributes specially. It also does not deal properly with
207 entries resulting from LDIF change records.
208 See Net::LDAP::LDIF on how to generate LDIF output.
210 If "FILEHANDLE" is omitted "STDOUT" is used by default.
212 exists ( ATTR )
214 Returns "TRUE" if the entry has an attribute called "ATTR".
215 get_value ( ATTR, OPTIONS )
217 Get the values for the attribute "ATTR". In a list context returns
218 all values for the given attribute, or the empty list if the
219 attribute does not exist. In a scalar context returns the first
220 value for the attribute or undef if the attribute does not exist.
221 alloptions => 1
223 The result will be a hash reference. The keys of the hash will
224 be the options and the hash value will be the values for those
225 attributes. For example if an entry had:
226 name: Graham Barr
228 name;en-us: Bob
229 Then a get for attribute "name" with alloptions set to a true
231 value
232 $ref = $entry->get_value ( 'name', alloptions => 1 );
234 will return a hash reference that would be like
236 {
238 '' => [ 'Graham Barr' ],
239 ';en-us' => [ 'Bob' ]
240 }
241 If alloptions is not set or is set to false only the attribute
243 values for the exactly matching name are returned.
244 nooptions => 1
246 Instead of only returning the values of the exactly matching
247 attribute name, get the attribute values of all attributes with
248 the base name given. I.e. in the example above, calling
249 @array = $entry->get_value ( 'name', nooptions => 1 );
251 will yield
253 ( 'Graham Barr', 'Bob' )
255 The name of this option has neen chosen for consistency with
257 the equally named option in the attributes method.
258 asref => 1
260 The result will be a reference to an array containing all the
261 values for the attribute, or "undef" if the attribute does not
262 exist.
263 $scalar = $entry->get_value ( 'name' );
265 $scalar will be the first value for the "name" attribute, or
267 "undef" if the entry does not contain a "name" attribute.
268 $ref = $entry->get_value ( 'name', asref => 1 );
270 $ref will be a reference to an array, which will have all the
272 values for the "name" attribute. If the entry does not have an
273 attribute called "name" then $ref will be "undef".
274 NOTE: In the interest of performance the array references returned
276 by "get_value" may be references to structures held inside the
277 entry object. These values and their contents should NOT be
278 modified directly.
279 replace ( ATTR => VALUE, ... )
281 Similar to "add", except that the values given will replace any
282 values that already exist for the given attributes.
283 NOTE: these changes are local to the client and will not appear on
285 the directory server until the "update" method is called.
286 update ( CLIENT [, OPTIONS ] )
288 Update the directory server with any changes that have been made
289 locally to the attributes of this entry. This means any calls that
290 have been made to add, replace or delete since the last call to
291 changetype or update was made.
292 This method can also be used to modify the DN of the entry on the
294 server, by specifying moddn or modrdn as the changetype, and
295 setting the entry attributes newrdn, deleteoldrdn, and (optionally)
296 newsuperior.
297 "CLIENT" is a "Net::LDAP" object where the update will be sent to.
299 "OPTIONS" may be options to the "Net::LDAP" actions on CLIENT
301 corresponding to the entry's changetype.
302 The result will be an object of type Net::LDAP::Message as returned
304 by the add, modify or delete method called on CLIENT.
305 Alternatively "CLIENT" can also be a "Net::LDAP::LDIF" object, that
307 must be an LDIF file opened for writing.
308 In this case, the entry, together with any "OPTIONS" is passed as
310 arguments to the "write_entry" method of the "CLIENT" object.
311 Here too, the result is an object class "Net::LDAP::Message". On
313 error, the error code is "LDAP_OTHER" with the LDIF error message
314 in the error text.
315
317 Net::LDAP, Net::LDAP::LDIF
318
320 Graham Barr <gbarr@pobox.com>.
321 Please report any bugs, or post any suggestions, to the perl-ldap
323 mailing list <perl-ldap@perl.org>.
324
326 Copyright (c) 1997-2004 Graham Barr. All rights reserved. This program
327 is free software; you can redistribute it and/or modify it under the
328 same terms as Perl itself.
329perl v5.36.0 2023-01-24 Net::LDAP::Entry(3)