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 jpeg;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 jpeg;binary
127 nooptions: name jpeg
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
188 change => VALUE
190 If given a true value then the LDIF will be generated as a
191 change record. If false, then the LDIF generated will
192 represent the entry content. If unspecified then it will
193 default to true if the entry has changes and false if no
194 changes have been applied to the entry.
195 dump ( [ FILEHANDLE ] )
197 Dump the entry to the given filehandle.
198 This method is intended for debugging purposes and does not treat
200 binary attributes specially.
201 See Net::LDAP::LDIF on how to generate LDIF output.
203 If "FILEHANDLE" is omitted "STDOUT" is used by default.
205 exists ( ATTR )
207 Returns "TRUE" if the entry has an attribute called "ATTR".
208 get_value ( ATTR, OPTIONS )
210 Get the values for the attribute "ATTR". In a list context returns
211 all values for the given attribute, or the empty list if the
212 attribute does not exist. In a scalar context returns the first
213 value for the attribute or undef if the attribute does not exist.
214 alloptions => 1
216 The result will be a hash reference. The keys of the hash will
217 be the options and the hash value will be the values for those
218 attributes. For example if an entry had:
219 name: Graham Barr
221 name;en-us: Bob
222 Then a get for attribute "name" with alloptions set to a true
224 value
225 $ref = $entry->get_value ( 'name', alloptions => 1 );
227 will return a hash reference that would be like
229 {
231 '' => [ 'Graham Barr' ],
232 ';en-us' => [ 'Bob' ]
233 }
234 If alloptions is not set or is set to false only the attribute
236 values for the exactly matching name are returned.
237 asref => 1
239 The result will be a reference to an array containing all the
240 values for the attribute, or "undef" if the attribute does not
241 exist.
242 $scalar = $entry->get_value ( 'name' );
244 $scalar will be the first value for the "name" attribute, or
246 "undef" if the entry does not contain a "name" attribute.
247 $ref = $entry->get_value ( 'name', asref => 1 );
249 $ref will be a reference to an array, which will have all the
251 values for the "name" attribute. If the entry does not have an
252 attribute called "name" then $ref will be "undef".
253 NOTE: In the interest of performance the array references returned
255 by "get_value" are references to structures held inside the entry
256 object. These values and their contents should NOT be modified
257 directly.
258 replace ( ATTR => VALUE, ... )
260 Similar to "add", except that the values given will replace any
261 values that already exist for the given attributes.
262 NOTE: these changes are local to the client and will not appear on
264 the directory server until the "update" method is called.
265 update ( CLIENT [, OPTIONS ] )
267 Update the directory server with any changes that have been made
268 locally to the attributes of this entry. This means any calls that
269 have been made to add, replace or delete since the last call to
270 changetype or update was made.
271 This method can also be used to modify the DN of the entry on the
273 server, by specifying moddn or modrdn as the changetype, and
274 setting the entry attributes newrdn, deleteoldrdn, and (optionally)
275 newsuperior.
276 "CLIENT" is a "Net::LDAP" object where the update will be sent to.
278 "OPTIONS" may be options to the "Net::LDAP" actions on CLIENT
280 corresponding to the entry's changetype.
281 The result will be an object of type Net::LDAP::Message as returned
283 by the add, modify or delete method called on CLIENT.
284 Alternatively "CLIENT" can also be a "Net::LDAP::LDIF" object, that
286 must be an LDIF file opened for writing.
287 In this case, "OPTIONS" my be options that the method "write_entry"
289 of "Net::LDAP::LDIF" takes.
290 Here too, the result is an object class "Net::LDAP::Message". On
292 error, the error code is "LDAP_OTHER" with the LDIF error message
293 in the error text.
294
296 Net::LDAP, Net::LDAP::LDIF
297
299 Graham Barr <gbarr@pobox.com>.
300 Please report any bugs, or post any suggestions, to the perl-ldap
302 mailing list <perl-ldap@perl.org>.
303
305 Copyright (c) 1997-2004 Graham Barr. All rights reserved. This program
306 is free software; you can redistribute it and/or modify it under the
307 same terms as Perl itself.
308perl v5.16.3 2018-10-30 Net::LDAP::Entry(3)