Provided by: libmozilla-ldap-perl_1.5.3-3build6_amd64 bug

NAME

         Mozilla::LDAP::Conn - Object Oriented API for the LDAP SDK.

SYNOPSIS

         use Mozilla::LDAP::Conn;
         use Mozilla::LDAP::Utils;

ABSTRACT

       This package is the main API for using our Perl Object Oriented LDAP module. Even though
       it's certainly possible, and sometimes even necessary, to call the native LDAP C SDK
       functions, we strongly recommend you use these object classes.

       It's not required to use our Mozilla::LDAP::Utils.pm package, but it's convenient and good
       for portability if you use as much as you can from that package as well. This implies
       using the LdapConf package as well, even though you usually don't need to use it directly.

       You should read this document in combination with the Mozilla::LDAP::Entry document. Both
       modules depend on each other heavily.

DESCRIPTION

       First, this is not meant to be a crash course in how LDAP works, if you have no experience
       with LDAP, I suggest you read some of the literature that's available out there. The LDAP
       Deployment Book from Netscape, or the LDAP C SDK documentation are good starting points.

       This object class basically tracks and manages the LDAP connection, it's current status,
       and the current search operation (if any). Every time you call the search method of an
       object instance, you'll reset it's internal state. It depends heavily on the ::Entry
       class, which are used to retrieve, modify and update a single entry.

       The search and nextEntry methods returns Mozilla::LDAP::Entry objects, or an appropriately
       subclass of it. You also have to instantiate (and modify) a new ::Entry object when you
       want to add new entries to an LDAP server. Alternatively, the add() method will also take
       a hash array as argument, to make it easy to create new LDAP entries.

       To assure that changes to an entry are updated properly, we strongly recommend you use the
       native methods of the ::Entry object class. Even though you can modify certain elements
       directly, it could cause changes not to be committed to the LDAP server. If there's
       something missing from the API, please let us know, or even fix it yourself.

SOME PERLDAP/OO BASICS

       An entry consist of a DN, and a hash array of pointers to attribute values. Each attribute
       value (except the DN) is an array, but you have to remember the hash array in the entry
       stores pointers to the array, not the array. So, to access the first CN value of an entry,
       you'd do

           $cn = $entry->{cn}[0];

       To set the CN attribute to a completely new array of values, you'd do

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

       As long as you remember this, and try to use native Mozilla::LDAP::Entry methods, this
       package will take care of most the work. Once you master this, working with LDAP in Perl
       is surprisingly easy.

       We already mentioned DN, which stands for Distinguished Name. Every entry on an LDAP
       server must have a DN, and it's always guaranteed to be unique within your database. Some
       typical DNs are

           uid=leif,ou=people,o=netscape.com
           cn=gene-staff,ou=mailGroup,o=netscape.com
           dc=data,dc=netscape,dc=com

       There's also a term called RDN, which stands for Relative Distinguished Name. In the above
       examples, "uid=leif", "cn=gene-staff" and "dc=data" are all RDNs. One particular property
       for a RDN is that they must be unique within it's sub-tree. Hence, there can only be one
       user with "uid=leif" within the "ou=people" tree, there can never be a name conflict.

CREATING A NEW OBJECT INSTANCE

       Before you can do anything with PerLDAP, you'll need to instantiate at least one
       Mozilla::LDAP::Conn object, and connect it to an LDAP server. As you probably guessed
       already, this is done with the new method:

           $conn = Mozilla::LDAP::Conn->new("ldap", "389", $bind, $pswd, $cert, $ver);
           die "Couldn't connect to LDAP server ldap" unless  $conn;

       The arguments are: Host name, port number, and optionally a bind-DN, it's password, and a
       certificate. A recent addition is the LDAP protocol version, which is by default LDAP v3.
       If there is no bind-DN, the connection will be bound as the anonymous user. If the
       certificate file is specified, the connection will be over SSL, and you should then
       probably connect to port 636. You have to check that the object was created properly, and
       take proper actions if you couldn't get a connection.

       There's one convenient alternative call method to this function. Instead of providing each
       individual argument, you can provide one hash array (actually, a pointer to a hash). For
       example:

           %ld = Mozilla::LDAP::Utils::ldapArgs();
           $conn = Mozilla::LDAP::Conn->new(\%ld);

       The components of the hash are:

           $ld->{"host"}
           $ld->{"port"}
           $ld->{"base"}
           $ld->{"bind"}
           $ld->{"pswd"}
           $ld->{"cert"}
           $ld->{"vers"}

       and (not used in the new method)

           $ld->{"scope"}

       New for PerLDAP v1.5 and later are the following:

           $ld->{"nspr"}
           $ld->{"timeout"}
           $ld->{"callback"}
           $ld->{"entryclass"}

       The nspr flag (1/0) indicates that we wish to use the NSPR layer for the LDAP connection.
       This obviously only works if PerLDAP has been compiled with NSPR support and libraries.
       The default is for NSPR to be disabled.

       For an NSPR enabled connection, you can also provide an optional timeout parameter, which
       will be used during the lifetime of the connection. This includes the initial setup and
       connection to the LDAP server. You can change this parameter later using the
       setNSPRTimeout() method.

       During the bind process, you can provide a callback function to be called when the
       asynchronus bind has completed. The callback should take two arguments, a reference to the
       ::Conn object ("self") and a result structure as returned by the call to ldap_result().

       Finally, you can optionally specify what class the different methods should use when
       instantiating Entry result objects. The default is Mozilla::LDAP::Entry.

       Once a connection is established, the package will take care of the rest. If for some
       reason the connection is lost, the object should reconnect on it's own, automatically.
       [Note: This doesn't work now... ]. You can use the Mozilla::LDAP:Conn object for any
       number of operations, but since everything is currently done synchronously, you can only
       have one operation active at any single time. You can of course have multiple
       Mozilla::LDAP::Conn instanced active at the same time.

PERFORMING LDAP SEARCHES

       We assume that you are familiar with the LDAP filter syntax already, all searches
       performed by this object class uses these filters. You should also be familiar with LDAP
       URLs, and LDAP object classes. There are some of the few things you actually must know
       about LDAP. Perhaps the simples filter is

           (uid=leif)

       This matches all entries with the UID set to "leif". Normally that would only match one
       entry, but there is no guarantee for that. To find everyone with the name "leif", you'd
       instead do

           (cn=*leif*)

       A more complicated search involves logic operators. To find all mail groups owned by
       "leif" (or actually his DN), you could do

           (&(objectclass=mailGroup)(owner=uid=leif,ou=people,o=netscape))

       The owner attribute is what's called a DN attribute, so to match on it we have to specify
       the entire DN in the filter above. We could of course also do a sub string "wild card"
       match, but it's less efficient, and requires indexes to perform reasonably well.

       Ok, now we are prepared to actually do a real search on the LDAP server:

           $base = "o=netscape.com";
           $conn = Mozilla::LDAP::Conn->new("ldap", "389", "", ""); die "No LDAP
           connection" unless $conn;

           $entry = $conn->search($base, "subtree", "(uid=leif)");
           if (! $entry)
             { # handle this event, no entries found, dude!
             }
           else
             {
               while ($entry)
                 {
                   $entry->printLDIF();
                   $entry = $conn->nextEntry();
                 }
             }

       This is in fact a poor mans implementation of the ldapsearch command line utility. The
       search method returns an Mozilla::LDAP::Entry object (or derived subclass), which holds
       the first entry from the search, if any. To get the second and subsequent entries you call
       the entry method, until there are no more entries. The printLDIF method is a convenient
       function, requesting the entry to print itself on STDOUT, in LDIF format.

       The arguments to the search methods are the LDAP Base-DN, the scope of the search ("base",
       "one" or "sub"), and the actual LDAP filter. The entry return contains the DN, and all
       attribute values. To access a specific attribute value, you just have to use the hash
       array:

           $cn = $entry->{cn}[0];

       Since many LDAP attributes can have more than one value, value of the hash array is
       another array (or actually a pointer to an array). In many cases you can just assume the
       value is in the first slot (indexed by [0]), but for some attributes you have to support
       multiple values. To find out how many values a specific attribute has, you'd call the size
       method:

           $numVals = $entry->size("objectclass");

       One caveat: Many LDAP attributes are case insensitive, but the methods in the
       Mozilla::LDAP::Entry package are not aware of this. Hence, if you compare values with case
       sensitivity, you can experience weird behavior. If you know an attribute is CIS (Case
       Insensitive), make sure you do case insensitive string comparisons.

       Unfortunately some methods in this package can't do this, and by default will do case
       sensitive comparisons. We are working on this, and in a future release some of the methods
       will handle this more gracefully. As an extension (for LDAP v3.0) we could also use schema
       discovery for handling this even better.

       There is an alternative search method, to use LDAP URLs instead of a filter string. This
       can be used to easily parse and process URLs, which is a compact way of storing a "link"
       to some specific LDAP information. To process such a search, you use the searchURL method:

           $entry->searchURL("ldap:///o=netscape.com??sub?(uid=leif)");

       As it turns out, the search method also supports LDAP URL searches. If the search filter
       looks like a proper URL, we will actually do an URL search instead. This is for backward
       compatibility, and for ease of use.

       To achieve better performance and use less memory, you can limit your search to only
       retrieve certain attributes. With the LDAP URLs you specify this as an optional parameter,
       and with the search method you add two more options, like

           $entry = $conn->search($base, "sub", $filter, 0, ("mail", "cn"));

       The last argument specifies an array of attributes to retrieve, the fewer the attributes,
       the faster the search will be. The second to last argument is a boolean value indicating
       if we should retrieve only the attribute names (and no values). In most cases you want
       this to be FALSE, to retrieve both the attribute names, and all their values. To do this
       with the searchURL method, add a second argument, which should be 0 or 1.

PERFORMING ASYNCHRONOUS SEARCHES

       Conn also supports an async_search method that takes the same arguments as the search
       method but returns an instance of SearchIter instead of Entry.  As its name implies, the
       SearchIter is used to iterate through the search results.  The nextEntry method works just
       like the nextEntry method of Conn.  The abandon method should be called if search result
       processing is aborted before the last result is received, to allow the client and server
       to release resources.  Example:

               $iter = $conn->async_search($base, $scope, $filter, ...);
           if ($rc = $iter->getResultCode()) {
                   # process error condition
               } else {
                   while (my $entry = $iter->nextEntry) {
                               # process entry
                   if (some abort condition) {
                       $iter->abandon;
                       last;
                   }
               }
           }

MODIFYING AND CREATING NEW LDAP ENTRIES

       Once you have an LDAP entry, either from a search, or created directly to get a new empty
       object, you are ready to modify it. If you are creating a new entry, the first thing to
       set it it's DN, like

           $entry = $conn->newEntry();
           $entry->setDN("uid=leif,ou=people,o=netscape.com");

       alternatively you can still use the new method on the Entry class, like

           $entry = Mozilla::LDAP::Entry->new();

       You should not do this for an existing LDAP entry, changing the RDN (or DN) for such an
       entry must be done with modifyRDN. To populate (or modify) some other attributes, we can
       do

           $entry->{objectclass} = [ "top", "person", "inetOrgPerson" ];
           $entry->{cn} = [ "Leif Hedstrom" ];
           $entry->{mail} = [ "leif@netscape.com" ];

       Once you are done modifying your LDAP entry, call the update method from the
       Mozilla::LDAP::Conn object instance:

           $conn->update($entry);

       Or, if you are creating an entirely new LDAP entry, you must call the add method:

           $conn->add($entry);

       If all comes to worse, and you have to remove an entry again from the LDAP server, just
       call the delete method, like

           $conn->delete($entry->getDN());

       You can't use native Perl functions like push() and splice() on attribute values, since
       they won't update the ::Entry instance state properly.  Instead use one of the methods
       provided by the Mozilla::LDAP::Entry object class, for instance

           $entry->addValue("cn", "The Swede");
           $entry->removeValue("mailAlternateAddress", "leif@mcom.com");
           $entry->remove("seeAlso");

       These methods return a TRUE or FALSE value, depending on the outcome of the operation. If
       there was no value to remove, or a value already exists, we return FALSE, otherwise TRUE.
       To check if an attribute has a certain value, use the hasValue method, like

           if ($entry->hasValue("mail", "leif@netscape.com")) {
               # Do something
           }

       There is a similar method, matchValue, which takes a regular expression to match against,
       instead of the entire string. For more information this and other methods in the Entry
       class, see below.

OBJECT CLASS METHODS

       We have already described the fundamentals of this class earlier. This is a summary of all
       available methods which you can use. Be careful not to use any undocumented features or
       heaviour, since the internals in this module is likely to change.

   Searching and updating entries
       add          Add a new entry to the LDAP server. Make sure you use the new method for the
                    Mozilla::LDAP::Entry object, to create a proper entry.

       browse       Searches for an LDAP entry, but sets some default values to begin with, such
                    as scope=BASE, filter=(objectclass=*) and so on.  Much like search except for
                    these defaults.  Requires a DN value as an argument. An optional second
                    argument is an array of which attributes to return from the entry.  Note that
                    this does not support the "attributesOnly" flag.

                        $secondEntry = $conn->browse($entry->getDN());

       close        Close the LDAP connection, and clean up the object. If you don't call this
                    directly, the destructor for the object instance will do the job for you.

       compare      Compares an attribute and value to a given DN without first doing a search.
                    Requires three arguments: a DN, the attribute name, and the value of the
                    attribute. Returns TRUE if the attribute/value compared ok.

                        print "not" unless $conn->compare($entry->getDN(), "cn", "Big Swede");
                        print "ok";

       delete       This will delete the current entry, or possibly an entry as specified with
                    the optional argument. You can use this function to delete any entry you
                    like, by passing it an explicit DN. If you don't pass it this argument,
                    delete defaults to delete the current entry, from the last call to search or
                    entry. I'd recommend doing a delete with the explicit DN, like

                        $conn->delete($entry->getDN());

       modifyRDN    This will rename the specified LDAP entry, by modifying it's RDN. For
                    example, assuming you have a DN of

                        uid=leif, ou=people, dc=netscape, dc=com

                    and you wish to rename to

                        uid=fiel, ou=people, dc=netscape, dc=com

                    you'd do something like

                        $rdn = "uid=fiel";
                        $conn->modifyRDN($rdn, $entry->getDN());

                    Note that this can only be done on the RDN, you could not change say
                    "ou=people" to be "ou=hackers" in the example above. To do that, you have to
                    add a new entry (a copy of the old one), and then remove the old entry.

                    The last argument is a boolean (0 or 1), which indicates if the old RDN value
                    should be removed from the entry. The default is TRUE ("1").

       new          This creates and initialized a new LDAP connection and object. The required
                    arguments are host name, port number, bind DN and the bind password. An
                    optional argument is a certificate (public key), which causes the LDAP
                    connection to be established over an SSL channel. Currently we do not support
                    Client Authentication, so you still have to use the simple authentication
                    method (i.e. with a password).

                    A typical usage could be something like

                        %ld = Mozilla::LDAP::Utils::ldapArgs();
                        $conn = Mozilla::LDAP::Conn->new(\%ld);

                    Also, remember that if you use SSL, the port is (usually) 636.

       newEntry     This will create an empty Mozilla::LDAP::Entry object, which is properly tied
                    into the appropriate objectclass. Use this method instead of manually
                    creating new Entry objects, or at least make sure that you use the "tie"
                    function when creating the entry. This function takes no arguments, and
                    returns a pointer to an ::Entry object. For instance

                        $entry = $conn->newEntry();

                    or

                        $entry = Mozilla::LDAP::Conn->newEntry();

       nextEntry    This method will return the next entry from the search result, and can
                    therefore only be called after a successful search has been initiated. If
                    there are no more entries to retrieve, it returns nothing (empty string).

       search       The search method is the main entry point into this module. It requires at
                    least three arguments: The Base DN, the scope, and the search strings. Two
                    more optional arguments can be given, the first specifies if only attribute
                    names should be returned (TRUE or FALSE). The second argument is a list
                    (array) of attributes to return.

                    The last option is very important for performance. If you are only interested
                    in say the "mail" and "mailHost" attributes, specifying this in the search
                    will signficantly reduce the search time. An example of an efficient search
                    is

                        @attr = ("cn", "uid", "mail");
                        $filter = "(uid=*)";
                        $entry = $conn->search($base, $scope, $filter, 0, @attr);
                        while ($entry) {
                            # do something
                            $entry = $conn->nextEntry();
                        }

       searchURL    This is almost identical to search, except this function takes only two
                    arguments, an LDAP URL and an optional flag to specify if we only want the
                    attribute names to be returned (and no values). This function isn't very
                    useful, since the search method will actually honor properly formed LDAP
                    URL's, and use it if appropriate.

       simpleAuth   This method will rebind the LDAP connection using new credentials (i.e. a new
                    user-DN and password). To rebind "anonymously", just don't pass a DN and
                    password, and it will default to binding as the unprivleged user. For
                    example:

                        $user = "leif";
                        $password = "secret";
                        $conn = Mozilla::LDAP::Conn->new($host, $port);     # Anonymous bind
                        die "Could't connect to LDAP server $host" unless $conn;

                        $entry = $conn->search($base, $scope, "(uid=$user)", 0, (uid));
                        exit (-1) unless $entry;

                        $ret = $conn->simpleAuth($entry->getDN(), $password);
                        exit (-1) unless $ret;

                        $ret = $conn->simpleAuth();         # Bind as anon again.

       update       After modifying an Ldap::Entry entry (see below), use the update method to
                    commit changes to the LDAP server. Only attributes that has been changed will
                    be updated, assuming you have used the appropriate methods in the Entry
                    object. For instance, do not use push or splice to modify an entry, the
                    update will not recognize such changes.

                    To change the CN value for an entry, you could do

                        $entry->{cn} = ["Leif Hedstrom"];
                        $conn->update($entry);

   Other methods
       getErrorCode Return the error code (numeric) from the last LDAP API function call.
                    Remember that this can only be called after the successful creation of a new
                    :Conn object instance. A typical usage could be

                        if (! $opt_n) {
                            $conn->modifyRDN($rdn, $entry->getDN());
                            $conn->printError() if $conn->getErrorCode();
                        }

                    Which will report any error message as generated by the call to modifyRDN.
                    Some LDAP functions return extra error information, which can be retrieved
                    like:

                       $err = getErrorCode(\$matched, \$string);

                    $matched will then contain the portion of the matched DN (if applicable to
                    the error code), and $string will contain any additional error string
                    returned by the LDAP server.

       getErrorString
                    Very much like getErrorCode, but return a string with a human readable error
                    message. This can then be used to print a good error message on the console.

       getLD        Return the (internal) LDAP* connection handle, which you can use (carefully)
                    to call the native LDAP API functions. You shouldn't have to use this in most
                    cases, unless of course our OO layer is seriously flawed.

       getRes       Just like getLD, except it returns the internal LDAP return message
                    structure. Again, use this very carefully, and be aware that this might break
                    in future releases of PerLDAP. These two methods can be used to call some
                    useful API functions, like

                        $cld = $conn->getLD();
                        $res = $conn->getRes();
                        $count = Mozilla::LDAP::API::ldap_count_entries($cld, $res);

       isURL        Returns TRUE or FALSE if the given argument is a properly formed URL.

       printError   Print the last error message on standard output.

       setRebindProc
                    Tell the LDAP SDK to call the provided Perl function when it has to follow
                    referrals. The Perl function should return an array of three elements, the
                    new Bind DN, password and authentication method. A typical usage is

                        sub rebindProc {
                            return ("uid=ldapadmin", "secret", LDAP_AUTH_SIMPLE);
                        }

                        $ld->setRebindProc(\&rebindProc);

       setDefaultRebindProc
                    This is very much like the previous function, except instead of specifying
                    the function to use, you give it the DN, password and Auth method. Then we'll
                    use a default rebind procedure (internal in C) to handle the rebind
                    credentials. This was a solution for the Windows/NT problem/bugs we have with
                    rebind procedures written in Perl.

       setVersion   Change the LDAP protocol version on the already initialized connection.  The
                    default is LDAP v3 (new for PerLDAP v1.5!), but you can downgrade the
                    connection to LDAP v2 if necessary using this function. Example:

                        $conn->setVersion(2);

       getVersion   Return the protocol version currently in used by the connection.

       setSizelimit Set the sizelimit on a connection, to limit the maximum number of entries
                    that we want to retrieve. For example:

                       $conn->setSizelimit(10);

       getSizelimit Get the current sizelimit on a connection (if any).

       setOption    Set an (integer) LDAP option.

       getOption    Get an (integer) LDAP option.

       installNSPR  Install NSPR I/O, threading, and DNS functions so they will be used by 'ld'.

                    Pass a non-zero value for the 'shared' parameter if you plan to use this LDAP
                    * handle from more than one thread. This is highly unlikely since PerLDAP is
                    asynchronous.

       setNSPRTimeout
                    Set the TCP timeout value, in millisecond, for the NSPR enabled connection.
                    It's an error to call this before calling installNSPR(), unless you created
                    the new connection object with the nspr option.

                    This method can also be invoked as a class method, and it will then apply to
                    all new connections created. Like

                        Mozilla::LDAP::Conn->installNSPR(1);
                        Mozilla::LDAP::Conn->setNSPRTimeout(1000);

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::Entry, LDAP::Mozilla:Utils LDAP::Mozilla:API and of course Perl.