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 dump ( [ FILEHANDLE ] )
187 Dump the entry to the given filehandle.
188 This method is intended for debugging purposes and does not treat
190 binary attributes specially.
191 See Net::LDAP::LDIF on how to generate LDIF output.
193 If "FILEHANDLE" is omitted "STDOUT" is used by default.
195 exists ( ATTR )
197 Returns "TRUE" if the entry has an attribute called "ATTR".
198 get_value ( ATTR, OPTIONS )
200 Get the values for the attribute "ATTR". In a list context returns
201 all values for the given attribute, or the empty list if the
202 attribute does not exist. In a scalar context returns the first
203 value for the attribute or undef if the attribute does not exist.
204 alloptions => 1
206 The result will be a hash reference. The keys of the hash will
207 be the options and the hash value will be the values for those
208 attributes. For example if an entry had:
209 name: Graham Barr
211 name;en-us: Bob
212 Then a get for attribute "name" with alloptions set to a true
214 value
215 $ref = $entry->get_value ( 'name', alloptions => 1 );
217 will return a hash reference that would be like
219 {
221 '' => [ 'Graham Barr' ],
222 ';en-us' => [ 'Bob' ]
223 }
224 If alloptions is not set or is set to false only the attribute
226 values for the exactly matching name are returned.
227 asref => 1
229 The result will be a reference to an array containing all the
230 values for the attribute, or "undef" if the attribute does not
231 exist.
232 $scalar = $entry->get_value ( 'name' );
234 $scalar will be the first value for the "name" attribute, or
236 "undef" if the entry does not contain a "name" attribute.
237 $ref = $entry->get_value ( 'name', asref => 1 );
239 $ref will be a reference to an array, which will have all the
241 values for the "name" attribute. If the entry does not have an
242 attribute called "name" then $ref will be "undef".
243 NOTE: In the interest of performance the array references returned
245 by "get_value" are references to structures held inside the entry
246 object. These values and thier contents should NOT be modified
247 directly.
248 replace ( ATTR => VALUE, ... )
250 Similar to "add", except that the values given will replace any
251 values that already exist for the given attributes.
252 NOTE: these changes are local to the client and will not appear on
254 the directory server until the "update" method is called.
255 update ( CLIENT [, OPTIONS ] )
257 Update the directory server with any changes that have been made
258 locally to the attributes of this entry. This means any calls that
259 have been made to add, replace or delete since the last call to
260 changetype or update was made.
261 This method can also be used to modify the DN of the entry on the
263 server, by specifying moddn or modrdn as the changetype, and set‐
264 ting the entry attributes newrdn, deleteoldrdn, and (optionally)
265 newsuperior.
266 "CLIENT" is a "Net::LDAP" object where the update will be sent to.
268 "OPTIONS" may be options to the "Net::LDAP" actions on CLIENT cor‐
270 responding to the entry's changetype.
271 The result will be an object of type Net::LDAP::Message as returned
273 by the add, modify or delete method called on CLIENT.
274
276 Net::LDAP, Net::LDAP::LDIF
277
279 Graham Barr <gbarr@pobox.com>.
280 Please report any bugs, or post any suggestions, to the perl-ldap mail‐
282 ing list <perl-ldap@perl.org>.
283
285 Copyright (c) 1997-2004 Graham Barr. All rights reserved. This program
286 is free software; you can redistribute it and/or modify it under the
287 same terms as Perl itself.
288perl v5.8.8 2007-02-10 Net::LDAP::Entry(3)