The LDAP::Conn object is used to perform LDAP searches, updates, adds and
deletes. All such functions works on LDAP::Entry objects only. All
modifications and additions you'll do to an LDAP entry, will be done
through this object class.
The LDAP::Entry object class is built on top of the Tie::Hash standard
object class. This gives us several powerful features, the main one being
to keep track of what is changing in the LDAP entry. This makes it very
easy to write LDAP clients that needs to update/modify entries, since
you'll just do the changes, and this object class will take care of the
rest.
We define local functions for STORE, FETCH, DELETE, EXISTS, FIRSTKEY and
NEXTKEY in this object class, and inherit the rest from the super class.
Overloading these specific functions is how we can keep track of what is
changing in the entry, which turns out to be very convenient. We can also
easily ``loop'' over the attribute types, ignoring internal data, or
deleted attributes.
Most of the methods here either return the requested LDAP value, or a
status code. The status code (either 0 or 1) indicates the failure or
success of a certain operation. 0 (False) meaning the operation failed, and
a return code of 1 (True) means complete success.
One thing to remember is that in LDAP, attribute names are case
insensitive. All methods in this class are aware of this, and will convert
all attribute name arguments to lower case before performing any
operations. This does not mean that the values are case insensitive. On the
contrary, all values are considered case sensitive by this module, even if
the LDAP server itself treats it as a CIS attribute.
The LDAP::Entry class implements many methods you can use to access and
modify LDAP entries. It is strongly recommended that you use this API as
much as possible, and avoid using the internals of the class directly.
Failing to do so may actually break the functionality.
This is the minimum requirements for an LDAP entry. It must have a DN, and
it must have at least one objectclass. As it turns out, by adding the
person and inetOrgPerson classes, we also must provide some more attributes, like CN and SN. This is because the object classes have these attributes marked as
``required'', and we'd get a schema violation without those values.
In the example above we use both native API methods to add values, and
setting an attribute entire value set directly. Note that the value set is
a pointer to an array, and not the array itself. In the example above, the
object classes are set using an anonymous array, which the API handles
properly. It's important to be aware that the attribute value list is
indeed a pointer.
Finally, as you can see there's only only one way to add new LDAP entries,
and it's called add(). It normally takes an LDAP::Entry object
instance as argument, but it can also be called with a regular hash array
if so desired.
Add a value to an attribute. If the attribute value already exists, or we
couldn't add the value for any other reason, we'll return FALSE (0),
otherwise we return TRUE (1). The first two arguments are the attribute
name, and the value to add.
The optional third argument is a flag, indicating that we want to add the
attribute without checking for duplicates. This is useful if you know the
values are unique already, or if you perhaps want to allow duplicates for a
particular attribute. To add a CN to an existing entry/attribute, do:
This is an internal function, that can be used to force the API to consider
an attribute (value) to have been modified. The only argument is the name
of the attribute. In almost all situation, you never, ever, should call
this. If you do, please contact the developers, and as us to fix the API.
Example
Copy the value of one attribute to another. Requires at least two
arguments. The first argument is the name of the attribute to copy, and the
second argument is the name of the new attribute to copy to. The new
attribute can not currently exist in the entry, else the copy will fail.
There is an optional third argument (a boolean flag), which, when set to 1,
will force an override and copy to the new attribute even if it already
exists. Returns TRUE if the copy was successful.
Return TRUE if the specified attribute is defined in the LDAP entry. This
is useful to know if an entry has a particular attribute, regardless of the
value. For instance:
if ($entry->exists("jpegphoto")) { # do something special }
Return TRUE or FALSE if the attribute has the specified value. A typical
usage is to see if an entry is of a certain object class, e.g.
if ($entry->hasValue("objectclass", "person", 1)) { # do something }
The (optional) third argument indicates if the string comparison should be
case insensitive or not, and the (optional) fourth argument indicats wheter
we should normalize the string as if it was a DN. The first two arguments
are the name and value of the attribute, respectively.
This method can be used to decide if an attribute name really is a valid
LDAP attribute in the current entry. Use of this method is fairly limited,
but could potentially be useful. Usage is like previous examples, like
if ($entry->isAttr("cn")) { # do something }
The code section will only be executed if these criterias are true:
1. The name of the attribute is a non-empty string.
2. The name of the attribute does not begin, and end, with an
underscore character (_).
2. The attribute has one or more values in the entry.
This is a somewhat more useful method, which will return the internal
modification status of a particular attribute. The argument is the name of
the attribute, and the return value is True or False. If the attribute has
been modified, in any way, we return True (1), otherwise we return False
(0). For example:
This is very similar to hasValue, except it does a regular expression match instead of a full string match.
It takes the same arguments, including the optional third argument to
specify case insensitive matching. The usage is identical to the example
for hasValue, e.g.
if ($entry->matchValue("objectclass", "pers", 1)) { # do something }
This will remove the entire attribute, including all it's values, from the
entry. The only argument is the name of the attribute to remove. Let's say
you want to nuke all mailAlternateAddress values (i.e. the entire attribute should be removed from the entry):
Remove a value from an attribute, if it exists. Of course, if the attribute
has no such value, we won't try to remove it, and instead return a False
(0) status code. The arguments are the name of the attribute, and the
particular value to remove. Note that values are considered case sensitive,
so make sure you preserve case properly. An example is:
This is almost identical to removeValue, except it will normalize the attribute values before trying to remove
them. This is useful if you know that the attribute is a DN value, but
perhaps the values are not cosistent in all LDAP entries. For example
Set the DN to the specified value. Only do this on new entries, it will not
work well if you try to do this on an existing entry. If you wish to rename
an entry, use the Mozilla::Conn::modifyRDN method instead. Eventually we'll
provide a complete ``rename'' method. To set the DN for a newly created
entry, we can do
There is an optional third argument, a boolean flag, indicating that we
should normalize the DN before setting it. This will assure a consistent
format of your DNs.
Set the specified attribute to the new value (or values), overwriting
whatever old values it had before. This is a little dangerous, since you
can lose attribute values you didn't intend to remove. Therefore, it's
usually recommended to use removeValue() and setValues(). If you know exactly what the new values should be like, you can use this
method like
$entry->setValues("cn", "Leif Hedstrom", "The Swede");
$entry->setValues("mail", @mailAddresses);
To delete an LDAP entry from the LDAP server, you have to use the
delete method from the Mozilla::LDAP::Conn module. It will actually delete any
entry, if you provide an legitimate DN.
Again, there's no functionality in this object class to rename the entry
(i.e. changing it's DN). For now, there is a way to modify the RDN
component of a DN through the Mozilla::LDAP::Conn module, with
modifyRDN. Eventually we hope to have a complete rename method, which should be capable of renaming any entry, in any way,
including moving it to a different part of the DIT (Directory Information
Tree).