1Net::LDAP::Entry(3)   User Contributed Perl Documentation  Net::LDAP::Entry(3)
2
3
4

NAME

6       Net::LDAP::Entry - An LDAP entry object
7

SYNOPSIS

9        use Net::LDAP;
10
11        $ldap = Net::LDAP->new ( $host );
12        $mesg = $ldap->search ( @search_args );
13
14        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
22        # or
23
24        use Net::LDAP::Entry;
25
26        $entry = Net::LDAP::Entry->new;
27
28        $entry->dn($dn);
29
30        $entry->add (
31          attr1 => 'value1',
32          attr2 => [ qw(value1 value2) ]
33        );
34
35        $entry->delete ( 'unwanted' );
36
37        $entry->replace (
38          attr1 => 'newvalue',
39          attr2 => [ qw(new values) ]
40        );
41
42        $entry->update ( $ldap ); # update directory server
43
44        $entry2 = $entry->clone; # copies entry
45
46        # new alternate syntax
47
48        $entry = Net::LDAP::Entry->new ( $dn,
49          attr1 => 'value1',
50          attr2 => [ qw(value1 value2) ]
51        )->add(
52          attr3   => 'value'
53        )->update( $ldap );
54

DESCRIPTION

56       The Net::LDAP::Entry object represents a single entry in the directory.
57       It is a container for attribute-value pairs.
58
59       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
63       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

CONSTRUCTORS

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
74            Net::LDAP::Entry->new()
75
76            # or
77            Net::LDAP::Entry->new( $dn )
78
79            # or
80            Net::LDAP::Entry->new( $dn ,
81             objectClass => [qw( top posixAccount )] , uid => 'admin'
82            )
83
84       clone ( )
85           Returns a copy of the Net::LDAP::Entry object.
86

METHODS

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
95            $entry->add ( 'sn' => 'Barr' );
96
97            $entry->add ( 'street' => [ '1 some road','nowhere' ] );
98
99           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
103            $entry->add ( 'sn' => 'Barr' )->update( $ldap );
104
105       attributes ( OPTIONS )
106           Return a list of attributes in this entry
107
108           nooptions => 1
109               Return a list of the attribute names excluding any options. For
110               example for the entry
111
112                 name: Graham Barr
113                 name;en-us: Bob
114                 jpegPhoto;binary: **binary data**
115
116               then
117
118                 @values = $entry->attributes;
119                 print "default: @values\n";
120
121                 @values = $entry->attributes ( nooptions => 1 );
122                 print "nooptions: @values\n";
123
124               will output
125
126                 default: name name;en-us jpegPhoto;binary
127                 nooptions: name jpegPhoto
128
129       changetype ( )
130           Returns the type of operation that would be performed when the
131           update method is called.
132
133       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
137           Possible values for "TYPE" are
138
139           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
143           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
148                $entry->delete->update( $ldap )
149
150           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
155           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
162       delete ( )
163           Delete the entry from the server on the next call to "update".
164
165       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
171            $entry->delete ( 'mail' => [ 'foo.bar@example.com' ] );
172            $entry->delete ( 'description' => [ ], 'streetAddress' => [ ] );
173
174           NOTE: these changes are local to the client and will not appear on
175           the directory server until the "update" method is called.
176
177       dn ( )
178           Get the DN of the entry.
179
180       dn ( DN )
181           Set the DN for the entry, and return the previous value.
182
183           NOTE: these changes are local to the client and will not appear on
184           the directory server until the "update" method is called.
185
186       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
191           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
198           version => VALUE
199               No matter what value is passed, it will be ignored, and treated
200               as if 0 were given.
201
202       dump ( [ FILEHANDLE ] )
203           Dump the entry to the given filehandle.
204
205           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
209           See Net::LDAP::LDIF on how to generate LDIF output.
210
211           If "FILEHANDLE" is omitted "STDOUT" is used by default.
212
213       exists ( ATTR )
214           Returns "TRUE" if the entry has an attribute called "ATTR".
215
216       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
222           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
227                name: Graham Barr
228                name;en-us: Bob
229
230               Then a get for attribute "name" with alloptions set to a true
231               value
232
233                $ref = $entry->get_value ( 'name', alloptions => 1 );
234
235               will return a hash reference that would be like
236
237                {
238                  ''       => [ 'Graham Barr' ],
239                  ';en-us' => [ 'Bob' ]
240                }
241
242               If alloptions is not set or is set to false only the attribute
243               values for the exactly matching name are returned.
244
245           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
250                @array = $entry->get_value ( 'name', nooptions => 1 );
251
252               will yield
253
254                ( 'Graham Barr', 'Bob' )
255
256               The name of this option has neen chosen for consistency with
257               the equally named option in the attributes method.
258
259           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
264                $scalar = $entry->get_value ( 'name' );
265
266               $scalar will be the first value for the "name" attribute, or
267               "undef" if the entry does not contain a "name" attribute.
268
269                $ref = $entry->get_value ( 'name', asref => 1 );
270
271               $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
275           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
280       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
284           NOTE: these changes are local to the client and will not appear on
285           the directory server until the "update" method is called.
286
287       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
293           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
298           "CLIENT" is a "Net::LDAP" object where the update will be sent to.
299
300           "OPTIONS" may be options to the "Net::LDAP" actions on CLIENT
301           corresponding to the entry's changetype.
302
303           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
306           Alternatively "CLIENT" can also be a "Net::LDAP::LDIF" object, that
307           must be an LDIF file opened for writing.
308
309           In this case, the entry, together with any "OPTIONS" is passed as
310           arguments to the "write_entry" method of the "CLIENT" object.
311
312           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

SEE ALSO

317       Net::LDAP, Net::LDAP::LDIF
318

AUTHOR

320       Graham Barr <gbarr@pobox.com>.
321
322       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.
329
330
331
332perl v5.36.0                      2023-01-24               Net::LDAP::Entry(3)
Impressum