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
39 insensitive. All methods in this class are aware of this, and will
40 convert all attribute name arguments to lower case before performing
41 any operations. This does not mean that the values are case
42 insensitive. On the contrary, all values are considered case sensitive
43 by this module, even if the LDAP server itself treats it as a CIS
44 attribute.
45
47 The LDAP::Entry class implements many methods you can use to access and
48 modify LDAP entries. It is strongly recommended that you use this API
49 as much as possible, and avoid using the internals of the class
50 directly. Failing to do so may actually break the functionality.
51 Creating a new entry
53 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
86 any modifications and updates to your LDAP entries.
87 addValue Add a value to an attribute. If the attribute value
89 already exists, or we couldn't add the value for any other
90 reason, we'll return FALSE (0), otherwise we return TRUE
91 (1). The first two arguments are the attribute name, and
92 the value to add.
93 The optional third argument is a flag, indicating that we
95 want to add the attribute without checking for duplicates.
96 This is useful if you know the values are unique already,
97 or if you perhaps want to allow duplicates for a
98 particular attribute. The fourth argument (again optional)
99 is a flag indicating that we want to perform DN
100 normalization on the attribute. The final, fifth, optional
101 argument indicates that the attribute values are case
102 insensitive (CIS).
103 To add a CN to an existing entry/attribute, do:
105 $entry->addValue("cn", "Leif Hedstrom");
107 addDNValue Just like addValue, except this method assume the value is
109 a DN attribute, and will enforce DN normalization. For
110 instance
111 $dn = "uid=Leif, dc=Netscape, dc=COM";
113 $entry->addDNValue("uniqueMember", $dn);
114 will only add the DN for "uid=leif" if it does not exist
116 as a DN in the uniqueMember attribute.
117 attrModified This is an internal function, that can be used to force
119 the API to consider an attribute (value) to have been
120 modified. The only argument is the name of the attribute.
121 In almost all situation, you never, ever, should call
122 this. If you do, please contact the developers, and as us
123 to fix the API. Example
124 $entry->attrModified("cn");
126 copy Copy the value of one attribute to another. Requires at
128 least two arguments. The first argument is the name of
129 the attribute to copy, and the second argument is the name
130 of the new attribute to copy to. The new attribute can
131 not currently exist in the entry, else the copy will fail.
132 There is an optional third argument (a boolean flag),
133 which, when set to 1, will force an override and copy to
134 the new attribute even if it already exists. Returns TRUE
135 if the copy was successful.
136 $entry->copy("cn", "description");
138 exists Return TRUE if the specified attribute is defined in the
140 LDAP entry. This is useful to know if an entry has a
141 particular attribute, regardless of the value. For
142 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
151 argument, which indicates we should normalize the DN
152 before returning it to the caller.
153 getValues Returns an entire array of values for the attribute
155 specified. Note that this returns an array, and not a
156 pointer to an array. In a scalar context, this returns
157 the first value. This is different - this method used to
158 always return an array, which meant the array size in a
159 scalar context. If you need to get the array size, use
160 the size 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
167 certain object class, e.g.
168 if ($entry->hasValue("objectclass", "person", 1)) { # do something }
170 The (optional) third argument indicates if the string
172 comparison should be case insensitive or not, and the
173 (optional) fourth argument indicats wheter we should
174 normalize the string as if it was a DN. The first two
175 arguments are the name and value of the attribute,
176 respectively.
177 hasDNValue Exactly like hasValue, except we assume the attribute
179 values 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
220 identical 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
225 considered 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
234 Interchange Format, RFC xxxx). An example of an LDIF entry
235 is:
236 dn: uid=leif,ou=people,dc=netscape,dc=com
238 objectclass: top
239 objectclass: person
240 objectclass: inetOrgPerson
241 uid: leif
242 cn: Leif Hedstrom
243 mail: leif@netscape.com
244 The above would be the result of
246 $entry->printLDIF();
248 If you need to write to a file, open and then select() it.
250 For more useful LDIF functionality, check out the
251 Mozilla::LDAP::LDIF.pm module.
252 remove This will remove the entire attribute, including all it's
254 values, from the entry. The only argument is the name of
255 the attribute to remove. Let's say you want to nuke all
256 mailAlternateAddress values (i.e. the entire attribute
257 should be removed from the entry):
258 $entry->remove("mailAlternateAddress");
260 removeValue Remove a value from an attribute, if it exists. Of course,
262 if the attribute has no such value, we won't try to remove
263 it, and instead return a False (0) status code. The
264 arguments are the name of the attribute, and the
265 particular value to remove. Note that values are
266 considered case sensitive, so make sure you preserve case
267 properly. An example is:
268 $entry->removeValue("objectclass", "nscpPerson");
270 removeDNValue
272 This is almost identical to removeValue, except it will
273 normalize the attribute values before trying to remove
274 them. This is useful if you know that the attribute is a
275 DN value, but perhaps the values are not cosistent in all
276 LDAP entries. For example
277 $dn = "uid=Leif, dc=Netscape, dc=COM";
279 $entry->removeDNValue("owner", $dn);
280 will remove the owner "uid=leif,dc=netscape,dc=com", no
282 matter how it's capitalized and formatted in the entry.
283 setDN Set the DN to the specified value. Only do this on new
285 entries, it will not work well if you try to do this on an
286 existing entry. If you wish to rename an entry, use the
287 Mozilla::Conn::modifyRDN method instead. Eventually we'll
288 provide a complete "rename" method. To set the DN for a
289 newly created entry, we can do
290 $entry->setDN("uid=leif,ou=people,dc=netscape,dc=com");
292 There is an optional third argument, a boolean flag,
294 indicating that we should normalize the DN before setting
295 it. This will assure a consistent format of your DNs.
296 setValues Set the specified attribute to the new value (or values),
298 overwriting whatever old values it had before. This is a
299 little dangerous, since you can lose attribute values you
300 didn't intend to remove. Therefore, it's usually
301 recommended to use removeValue() and setValues(). If you
302 know exactly what the new values should be like, you can
303 use this method like
304 $entry->setValues("cn", "Leif Hedstrom", "The Swede");
306 $entry->setValues("mail", @mailAddresses);
307 or if it's a single value attribute,
309 $entry->setValues("uidNumber", "12345");
311 size Return the number of values for a particular attribute.
313 For instance
314 $entry->{cn} = [ "Leif Hedstrom", "The Swede" ];
316 $numVals = $entry->size("cn");
317 This will set $numVals to two (2). The only argument is
319 the name of the attribute, and the return value is the
320 size of the value array.
321 Deleting entries
323 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
329 entry (i.e. changing it's DN). For now, there is a way to modify the
330 RDN component of a DN through the Mozilla::LDAP::Conn module, with
331 modifyRDN. Eventually we hope to have a complete rename method, which
332 should be capable of renaming any entry, in any way, including moving
333 it to a different part of the DIT (Directory Information Tree).
334
336 There are plenty of examples to look at, in the examples directory. We
337 are adding more examples every day (almost).
338
340 Installing this package is part of the Makefile supplied in the
341 package. See the installation procedures which are part of this
342 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
352 Communications Corporation.
353
355 None. :)
356
358 Mozilla::LDAP::Conn, Mozilla::LDAP::API, and of course Perl.
359perl v5.26.3 2007-06-14 Entry(3)