1Entry(3) User Contributed Perl Documentation Entry(3)
2
6 Mozilla::LDAP::Entry.pm - Object class to hold one LDAP entry.
7
9 use Mozilla::LDAP::Conn;
10 use Mozilla::LDAP::Entry;
11
13 The LDAP::Conn object is used to perform LDAP searches, updates, adds
14 and deletes. All such functions works on LDAP::Entry objects only. All
15 modifications and additions you'll do to an LDAP entry, will be done
16 through this object class.
17
19 The LDAP::Entry object class is built on top of the Tie::Hash standard
20 object class. This gives us several powerful features, the main one
21 being to keep track of what is changing in the LDAP entry. This makes
22 it very easy to write LDAP clients that needs to update/modify entries,
23 since you'll just do the changes, and this object class will take care
24 of the rest.
25 We define local functions for STORE, FETCH, DELETE, EXISTS, FIRSTKEY
27 and NEXTKEY in this object class, and inherit the rest from the super
28 class. Overloading these specific functions is how we can keep track of
29 what is changing in the entry, which turns out to be very convenient.
30 We can also easily "loop" over the attribute types, ignoring internal
31 data, or deleted attributes.
32 Most of the methods here either return the requested LDAP value, or a
34 status code. The status code (either 0 or 1) indicates the failure or
35 success of a certain operation. 0 (False) meaning the operation failed,
36 and a return code of 1 (True) means complete success.
37 One thing to remember is that in LDAP, attribute names are case insen‐
39 sitive. All methods in this class are aware of this, and will convert
40 all attribute name arguments to lower case before performing any opera‐
41 tions. This does not mean that the values are case insensitive. On the
42 contrary, all values are considered case sensitive by this module, even
43 if the LDAP server itself treats it as a CIS attribute.
44
46 The LDAP::Entry class implements many methods you can use to access and
47 modify LDAP entries. It is strongly recommended that you use this API
48 as much as possible, and avoid using the internals of the class
49 directly. Failing to do so may actually break the functionality.
50 Creating a new entry
52 To create a completely new entry, use the new method, for instance
54 $entry = Mozilla::LDAP::Entry->new()
56 $entry->setDN("uid=leif,ou=people,dc=netscape,dc=com");
57 $entry->{objectclass} = [ "top", "person", "inetOrgPerson" ];
58 $entry->addValue("cn", "Leif Hedstrom");
59 $entry->addValue("sn", "Hedstrom");
60 $entry->addValue("givenName", "Leif");
61 $entry->addValue("mail", "leif@netscape.com);
62 $conn->add($entry);
64 This is the minimum requirements for an LDAP entry. It must have a DN,
66 and it must have at least one objectclass. As it turns out, by adding
67 the person and inetOrgPerson classes, we also must provide some more
68 attributes, like CN and SN. This is because the object classes have
69 these attributes marked as "required", and we'd get a schema violation
70 without those values.
71 In the example above we use both native API methods to add values, and
73 setting an attribute entire value set directly. Note that the value set
74 is a pointer to an array, and not the array itself. In the example
75 above, the object classes are set using an anonymous array, which the
76 API handles properly. It's important to be aware that the attribute
77 value list is indeed a pointer.
78 Finally, as you can see there's only only one way to add new LDAP
80 entries, and it's called add(). It normally takes an LDAP::Entry object
81 instance as argument, but it can also be called with a regular hash
82 array if so desired.
83 Adding and removing attributes and values
85 This is the main functionality of this module. Use these methods to do
87 any modifications and updates to your LDAP entries.
88 addValue Add a value to an attribute. If the attribute value
90 already exists, or we couldn't add the value for any other
91 reason, we'll return FALSE (0), otherwise we return TRUE
92 (1). The first two arguments are the attribute name, and
93 the value to add.
94 The optional third argument is a flag, indicating that we
96 want to add the attribute without checking for duplicates.
97 This is useful if you know the values are unique already,
98 or if you perhaps want to allow duplicates for a particu‐
99 lar attribute. The fourth argument (again optional) is a
100 flag indicating that we want to perform DN normalization
101 on the attribute. The final, fifth, optional argument
102 indicates that the attribute values are case insensitive
103 (CIS).
104 To add a CN to an existing entry/attribute, do:
106 $entry->addValue("cn", "Leif Hedstrom");
108 addDNValue Just like addValue, except this method assume the value is
110 a DN attribute, and will enforce DN normalization. For
111 instance
112 $dn = "uid=Leif, dc=Netscape, dc=COM";
114 $entry->addDNValue("uniqueMember", $dn);
115 will only add the DN for "uid=leif" if it does not exist
117 as a DN in the uniqueMember attribute.
118 attrModified This is an internal function, that can be used to force
120 the API to consider an attribute (value) to have been mod‐
121 ified. The only argument is the name of the attribute. In
122 almost all situation, you never, ever, should call this.
123 If you do, please contact the developers, and as us to fix
124 the API. Example
125 $entry->attrModified("cn");
127 copy Copy the value of one attribute to another. Requires at
129 least two arguments. The first argument is the name of
130 the attribute to copy, and the second argument is the name
131 of the new attribute to copy to. The new attribute can
132 not currently exist in the entry, else the copy will fail.
133 There is an optional third argument (a boolean flag),
134 which, when set to 1, will force an override and copy to
135 the new attribute even if it already exists. Returns TRUE
136 if the copy was successful.
137 $entry->copy("cn", "description");
139 exists Return TRUE if the specified attribute is defined in the
141 LDAP entry. This is useful to know if an entry has a par‐
142 ticular attribute, regardless of the value. For instance:
143 if ($entry->exists("jpegphoto")) { # do something special }
145 getDN Return the DN for the entry. For instance
147 print "The DN is: ", $entry->getDN(), "\n";
149 Just like setDN, this method also has an optional argu‐
151 ment, which indicates we should normalize the DN before
152 returning it to the caller.
153 getValues Returns an entire array of values for the attribute speci‐
155 fied. Note that this returns an array, and not a pointer
156 to an array. In a scalar context, this returns the first
157 value. This is different - this method used to always
158 return an array, which meant the array size in a scalar
159 context. If you need to get the array size, use the size
160 method described below.
161 @someArray = $entry->getValues("description");
163 $scalval = $entry->getValues("cn");
164 hasValue Return TRUE or FALSE if the attribute has the specified
166 value. A typical usage is to see if an entry is of a cer‐
167 tain object class, e.g.
168 if ($entry->hasValue("objectclass", "person", 1)) { # do something }
170 The (optional) third argument indicates if the string com‐
172 parison should be case insensitive or not, and the
173 (optional) fourth argument indicats wheter we should nor‐
174 malize the string as if it was a DN. The first two argu‐
175 ments are the name and value of the attribute, respec‐
176 tively.
177 hasDNValue Exactly like hasValue, except we assume the attribute val‐
179 ues are DN attributes.
180 isAttr This method can be used to decide if an attribute name
182 really is a valid LDAP attribute in the current entry. Use
183 of this method is fairly limited, but could potentially be
184 useful. Usage is like previous examples, like
185 if ($entry->isAttr("cn")) { # do something }
187 The code section will only be executed if these criterias
189 are true:
190 1. The name of the attribute is a non-empty string.
192 2. The name of the attribute does not begin, and end, with an
193 underscore character (_).
194 2. The attribute has one or more values in the entry.
195 isDeleted This is almost identical to isModified, except it tests if
197 an attribute has been deleted. You use it the same way as
198 above, like
199 if (! $entry->isDeleted("cn")) { # do something }
201 isModified This is a somewhat more useful method, which will return
203 the internal modification status of a particular
204 attribute. The argument is the name of the attribute, and
205 the return value is True or False. If the attribute has
206 been modified, in any way, we return True (1), otherwise
207 we return False (0). For example:
208 if ($entry->isModified("cn")) { # do something }
210 isEntryModified
212 This is a wrapper over isModified(), and it will check if
213 any attribute in the entry object has been modified or
214 deleted.
215 matchValue This is very similar to hasValue, except it does a regular
217 expression match instead of a full string match. It takes
218 the same arguments, including the optional third argument
219 to specify case insensitive matching. The usage is identi‐
220 cal to the example for hasValue, e.g.
221 if ($entry->matchValue("objectclass", "pers", 1)) { # do something }
223 matchDNValue Like matchValue, except the attribute values are consid‐
225 ered being DNs.
226 move Identical to the copy method, except the original
228 attribute is deleted once the move to the new attribute is
229 complete.
230 $entry->move("cn", "sn");
232 printLDIF Print the entry in a format called LDIF (LDAP Data Inter‐
234 change Format, RFC xxxx). An example of an LDIF entry is:
235 dn: uid=leif,ou=people,dc=netscape,dc=com
237 objectclass: top
238 objectclass: person
239 objectclass: inetOrgPerson
240 uid: leif
241 cn: Leif Hedstrom
242 mail: leif@netscape.com
243 The above would be the result of
245 $entry->printLDIF();
247 If you need to write to a file, open and then select() it.
249 For more useful LDIF functionality, check out the
250 Mozilla::LDAP::LDIF.pm module.
251 remove This will remove the entire attribute, including all it's
253 values, from the entry. The only argument is the name of
254 the attribute to remove. Let's say you want to nuke all
255 mailAlternateAddress values (i.e. the entire attribute
256 should be removed from the entry):
257 $entry->remove("mailAlternateAddress");
259 removeValue Remove a value from an attribute, if it exists. Of course,
261 if the attribute has no such value, we won't try to remove
262 it, and instead return a False (0) status code. The argu‐
263 ments are the name of the attribute, and the particular
264 value to remove. Note that values are considered case sen‐
265 sitive, so make sure you preserve case properly. An exam‐
266 ple is:
267 $entry->removeValue("objectclass", "nscpPerson");
269 removeDNValue
271 This is almost identical to removeValue, except it will
272 normalize the attribute values before trying to remove
273 them. This is useful if you know that the attribute is a
274 DN value, but perhaps the values are not cosistent in all
275 LDAP entries. For example
276 $dn = "uid=Leif, dc=Netscape, dc=COM";
278 $entry->removeDNValue("owner", $dn);
279 will remove the owner "uid=leif,dc=netscape,dc=com", no
281 matter how it's capitalized and formatted in the entry.
282 setDN Set the DN to the specified value. Only do this on new
284 entries, it will not work well if you try to do this on an
285 existing entry. If you wish to rename an entry, use the
286 Mozilla::Conn::modifyRDN method instead. Eventually we'll
287 provide a complete "rename" method. To set the DN for a
288 newly created entry, we can do
289 $entry->setDN("uid=leif,ou=people,dc=netscape,dc=com");
291 There is an optional third argument, a boolean flag, indi‐
293 cating that we should normalize the DN before setting it.
294 This will assure a consistent format of your DNs.
295 setValues Set the specified attribute to the new value (or values),
297 overwriting whatever old values it had before. This is a
298 little dangerous, since you can lose attribute values you
299 didn't intend to remove. Therefore, it's usually recom‐
300 mended to use removeValue() and setValues(). If you know
301 exactly what the new values should be like, you can use
302 this method like
303 $entry->setValues("cn", "Leif Hedstrom", "The Swede");
305 $entry->setValues("mail", @mailAddresses);
306 or if it's a single value attribute,
308 $entry->setValues("uidNumber", "12345");
310 size Return the number of values for a particular attribute.
312 For instance
313 $entry->{cn} = [ "Leif Hedstrom", "The Swede" ];
315 $numVals = $entry->size("cn");
316 This will set $numVals to two (2). The only argument is
318 the name of the attribute, and the return value is the
319 size of the value array.
320 Deleting entries
322 To delete an LDAP entry from the LDAP server, you have to use the
324 delete method from the Mozilla::LDAP::Conn module. It will actually
325 delete any entry, if you provide an legitimate DN.
326 Renaming entries
328 Again, there's no functionality in this object class to rename the
330 entry (i.e. changing it's DN). For now, there is a way to modify the
331 RDN component of a DN through the Mozilla::LDAP::Conn module, with mod‐
332 ifyRDN. Eventually we hope to have a complete rename method, which
333 should be capable of renaming any entry, in any way, including moving
334 it to a different part of the DIT (Directory Information Tree).
335
337 There are plenty of examples to look at, in the examples directory. We
338 are adding more examples every day (almost).
339
341 Installing this package is part of the Makefile supplied in the pack‐
342 age. See the installation procedures which are part of this package.
343
345 This package can be retrieved from a number of places, including:
346 http://www.mozilla.org/directory/
348 Your local CPAN server
349
351 Most of this code was developed by Leif Hedstrom, Netscape Communica‐
352 tions Corporation.
353
355 None. :)
356
358 Mozilla::LDAP::Conn, Mozilla::LDAP::API, and of course Perl.
359perl v5.8.8 2007-06-14 Entry(3)