Unix/Linux Go Back    


CentOS 7.0 - man page for mozilla::ldap::entry (centos section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


Entry(3)		       User Contributed Perl Documentation			 Entry(3)

NAME
	 Mozilla::LDAP::Entry.pm - Object class to hold one LDAP entry.

SYNOPSIS
	 use Mozilla::LDAP::Conn;
	 use Mozilla::LDAP::Entry;

ABSTRACT
       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.

DESCRIPTION
       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.

OBJECT CLASS METHODS
       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.

   Creating a new entry
       To create a completely new entry, use the new method, for instance

	   $entry = Mozilla::LDAP::Entry->new()
	   $entry->setDN("uid=leif,ou=people,dc=netscape,dc=com");
	   $entry->{objectclass} = [ "top", "person", "inetOrgPerson" ];
	   $entry->addValue("cn", "Leif Hedstrom");
	   $entry->addValue("sn", "Hedstrom");
	   $entry->addValue("givenName", "Leif");
	   $entry->addValue("mail", "leif@netscape.com);

	   $conn->add($entry);

       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.

   Adding and removing attributes and values
       This is the main functionality of this module. Use these methods to do any modifications
       and updates to your LDAP entries.

       addValue     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 \fIs0(0),
		    otherwise we return TRUE \fIs0(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. The fourth argument (again optional) is a flag
		    indicating that we want to perform DN normalization on the attribute. The
		    final, fifth, optional argument indicates that the attribute values are case
		    insensitive (CIS).

		    To add a CN to an existing entry/attribute, do:

			$entry->addValue("cn", "Leif Hedstrom");

       addDNValue   Just like addValue, except this method assume the value is a DN attribute,
		    and will enforce DN normalization. For instance

		       $dn = "uid=Leif, dc=Netscape, dc=COM";
		       $entry->addDNValue("uniqueMember", $dn);

		    will only add the DN for "uid=leif" if it does not exist as a DN in the
		    uniqueMember attribute.

       attrModified 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

			$entry->attrModified("cn");

       copy	    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.

			$entry->copy("cn", "description");

       exists	    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 }

       getDN	    Return the DN for the entry. For instance

			print "The DN is: ", $entry->getDN(), "\n";

		    Just like setDN, this method also has an optional argument, which indicates
		    we should normalize the DN before returning it to the caller.

       getValues    Returns an entire array of values for the attribute specified.  Note that
		    this returns an array, and not a pointer to an array.  In a scalar context,
		    this returns the first value.  This is different - this method used to always
		    return an array, which meant the array size in a scalar context.  If you need
		    to get the array size, use the size method described below.

			@someArray = $entry->getValues("description");
			$scalval = $entry->getValues("cn");

       hasValue     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.

       hasDNValue   Exactly like hasValue, except we assume the attribute values are DN
		    attributes.

       isAttr	    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.

       isDeleted    This is almost identical to isModified, except it tests if an attribute has
		    been deleted. You use it the same way as above, like

			if (! $entry->isDeleted("cn")) { # do something }

       isModified   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:

			if ($entry->isModified("cn")) { # do something }

       isEntryModified
		    This is a wrapper over isModified(), and it will check if any attribute in
		    the entry object has been modified or deleted.

       matchValue   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 }

       matchDNValue Like matchValue, except the attribute values are considered being DNs.

       move	    Identical to the copy method, except the original attribute is deleted once
		    the move to the new attribute is complete.

			$entry->move("cn", "sn");

       printLDIF    Print the entry in a format called LDIF (LDAP Data Interchange Format, RFC
		    xxxx). An example of an LDIF entry is:

			dn: uid=leif,ou=people,dc=netscape,dc=com
			objectclass: top
			objectclass: person
			objectclass: inetOrgPerson
			uid: leif
			cn: Leif Hedstrom
			mail: leif@netscape.com

		    The above would be the result of

			$entry->printLDIF();

		    If you need to write to a file, open and then select() it.	For more useful
		    LDIF functionality, check out the Mozilla::LDAP::LDIF.pm module.

       remove	    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):

			$entry->remove("mailAlternateAddress");

       removeValue  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:

			$entry->removeValue("objectclass", "nscpPerson");

       removeDNValue
		    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

		       $dn = "uid=Leif, dc=Netscape, dc=COM";
		       $entry->removeDNValue("owner", $dn);

		    will remove the owner "uid=leif,dc=netscape,dc=com", no matter how it's
		    capitalized and formatted in the entry.

       setDN	    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

			$entry->setDN("uid=leif,ou=people,dc=netscape,dc=com");

		    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.

       setValues    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);

		    or if it's a single value attribute,

			$entry->setValues("uidNumber", "12345");

       size	    Return the number of values for a particular attribute. For instance

			$entry->{cn} = [ "Leif Hedstrom", "The Swede" ];
			$numVals = $entry->size("cn");

		    This will set $numVals to two (2). The only argument is the name of the
		    attribute, and the return value is the size of the value array.

   Deleting entries
       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.

   Renaming entries
       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).

EXAMPLES
       There are plenty of examples to look at, in the examples directory. We are adding more
       examples every day (almost).

INSTALLATION
       Installing this package is part of the Makefile supplied in the package. See the
       installation procedures which are part of this package.

AVAILABILITY
       This package can be retrieved from a number of places, including:

	   http://www.mozilla.org/directory/
	   Your local CPAN server

CREDITS
       Most of this code was developed by Leif Hedstrom, Netscape Communications Corporation.

BUGS
       None. :)

SEE ALSO
       Mozilla::LDAP::Conn, Mozilla::LDAP::API, and of course Perl.

perl v5.16.3				    2007-06-14					 Entry(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 11:12 PM.