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                 jpeg;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 jpeg;binary
127                 nooptions: name jpeg
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
188
189           change => VALUE
190               If given a true value then the LDIF will be generated as a
191               change record.  If flase, then the LDIF generated will
192               represent the entry content. If unspecified then it will
193               fefault to true if the entry has changes and false if no
194               changes have been applied to the entry.
195
196       dump ( [ FILEHANDLE ] )
197           Dump the entry to the given filehandle.
198
199           This method is intended for debugging purposes and does not treat
200           binary attributes specially.
201
202           See Net::LDAP::LDIF on how to generate LDIF output.
203
204           If "FILEHANDLE" is omitted "STDOUT" is used by default.
205
206       exists ( ATTR )
207           Returns "TRUE" if the entry has an attribute called "ATTR".
208
209       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
215           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
220                name: Graham Barr
221                name;en-us: Bob
222
223               Then a get for attribute "name" with alloptions set to a true
224               value
225
226                $ref = $entry->get_value ( 'name', alloptions => 1 );
227
228               will return a hash reference that would be like
229
230                {
231                  ''       => [ 'Graham Barr' ],
232                  ';en-us' => [ 'Bob' ]
233                }
234
235               If alloptions is not set or is set to false only the attribute
236               values for the exactly matching name are returned.
237
238           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
243                $scalar = $entry->get_value ( 'name' );
244
245               $scalar will be the first value for the "name" attribute, or
246               "undef" if the entry does not contain a "name" attribute.
247
248                $ref = $entry->get_value ( 'name', asref => 1 );
249
250               $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
254           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 thier contents should NOT be modified
257           directly.
258
259       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
263           NOTE: these changes are local to the client and will not appear on
264           the directory server until the "update" method is called.
265
266       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
272           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
277           "CLIENT" is a "Net::LDAP" object where the update will be sent to.
278
279           "OPTIONS" may be options to the "Net::LDAP" actions on CLIENT
280           corresponding to the entry's changetype.
281
282           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

SEE ALSO

286       Net::LDAP, Net::LDAP::LDIF
287

AUTHOR

289       Graham Barr <gbarr@pobox.com>.
290
291       Please report any bugs, or post any suggestions, to the perl-ldap
292       mailing list <perl-ldap@perl.org>.
293
295       Copyright (c) 1997-2004 Graham Barr. All rights reserved. This program
296       is free software; you can redistribute it and/or modify it under the
297       same terms as Perl itself.
298
299
300
301perl v5.12.0                      2010-03-12               Net::LDAP::Entry(3)
Impressum