.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Conn 3pm"
.TH Conn 3pm "2014-08-01" "perl v5.24.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
.Vb 1
\&  Mozilla::LDAP::Conn \- Object Oriented API for the LDAP SDK.
.Ve
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  use Mozilla::LDAP::Conn;
\&  use Mozilla::LDAP::Utils;
.Ve
.SH "ABSTRACT"
.IX Header "ABSTRACT"
This package is the main \s-1API\s0 for using our Perl Object Oriented \s-1LDAP\s0
module. Even though it's certainly possible, and sometimes even necessary,
to call the native \s-1LDAP C SDK\s0 functions, we strongly recommend you use
these object classes.
.PP
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.
.PP
You should read this document in combination with the Mozilla::LDAP::Entry
document. Both modules depend on each other heavily.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
First, this is not meant to be a crash course in how \s-1LDAP\s0 works, if you
have no experience with \s-1LDAP, I\s0 suggest you read some of the literature
that's available out there. The \s-1LDAP\s0 Deployment Book from Netscape, or the
\&\s-1LDAP C SDK\s0 documentation are good starting points.
.PP
This object class basically tracks and manages the \s-1LDAP\s0 connection, it's
current status, and the current search operation (if any). Every time you
call the \fBsearch\fR 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.
.PP
The \fBsearch\fR and \fBnextEntry\fR 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 \s-1LDAP\s0
server. Alternatively, the \fIadd()\fR method will also take a hash array as
argument, to make it easy to create new \s-1LDAP\s0 entries.
.PP
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 \s-1LDAP\s0 server. If there's something missing from
the \s-1API,\s0 please let us know, or even fix it yourself.
.SH "SOME PERLDAP/OO BASICS"
.IX Header "SOME PERLDAP/OO BASICS"
An entry consist of a \s-1DN,\s0 and a hash array of pointers to attribute
values. Each attribute value (except the \s-1DN\s0) 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 \s-1CN\s0 value of an entry, you'd do
.PP
.Vb 1
\&    $cn = $entry\->{cn}[0];
.Ve
.PP
To set the \s-1CN\s0 attribute to a completely new array of values, you'd do
.PP
.Vb 1
\&    $entry\->{cn} = [ "Leif Hedstrom", "The Swede" ];
.Ve
.PP
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 \s-1LDAP\s0 in Perl is surprisingly easy.
.PP
We already mentioned \s-1DN,\s0 which stands for Distinguished Name. Every entry
on an \s-1LDAP\s0 server must have a \s-1DN,\s0 and it's always guaranteed to be unique
within your database. Some typical DNs are
.PP
.Vb 3
\&    uid=leif,ou=people,o=netscape.com
\&    cn=gene\-staff,ou=mailGroup,o=netscape.com
\&    dc=data,dc=netscape,dc=com
.Ve
.PP
There's also a term called \s-1RDN,\s0 which stands for Relative Distinguished
Name. In the above examples, \f(CW\*(C`uid=leif\*(C'\fR, \f(CW\*(C`cn=gene\-staff\*(C'\fR and \f(CW\*(C`dc=data\*(C'\fR
are all RDNs. One particular property for a \s-1RDN\s0 is that they must be
unique within it's sub-tree. Hence, there can only be one user with
\&\f(CW\*(C`uid=leif\*(C'\fR within the \f(CW\*(C`ou=people\*(C'\fR tree, there can never be a name
conflict.
.SH "CREATING A NEW OBJECT INSTANCE"
.IX Header "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 \s-1LDAP\s0 server. As
you probably guessed already, this is done with the \fBnew\fR method:
.PP
.Vb 2
\&    $conn = Mozilla::LDAP::Conn\->new("ldap", "389", $bind, $pswd, $cert, $ver);
\&    die "Couldn\*(Aqt connect to LDAP server ldap" unless  $conn;
.Ve
.PP
The arguments are: Host name, port number, and optionally a bind-DN, it's
password, and a certificate. A recent addition is the \s-1LDAP\s0 protocol version,
which is by default \s-1LDAP\s0 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 \s-1SSL,\s0 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.
.PP
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:
.PP
.Vb 2
\&    %ld = Mozilla::LDAP::Utils::ldapArgs();
\&    $conn = Mozilla::LDAP::Conn\->new(\e%ld);
.Ve
.PP
The components of the hash are:
.PP
.Vb 7
\&    $ld\->{"host"}
\&    $ld\->{"port"}
\&    $ld\->{"base"}
\&    $ld\->{"bind"}
\&    $ld\->{"pswd"}
\&    $ld\->{"cert"}
\&    $ld\->{"vers"}
.Ve
.PP
and (not used in the \fBnew\fR method)
.PP
.Vb 1
\&    $ld\->{"scope"}
.Ve
.PP
New for PerLDAP v1.5 and later are the following:
.PP
.Vb 4
\&    $ld\->{"nspr"}
\&    $ld\->{"timeout"}
\&    $ld\->{"callback"}
\&    $ld\->{"entryclass"}
.Ve
.PP
The \fBnspr\fR flag (1/0) indicates that we wish to use the \s-1NSPR\s0 layer for
the \s-1LDAP\s0 connection. This obviously only works if PerLDAP has been compiled
with \s-1NSPR\s0 support and libraries. The default is for \s-1NSPR\s0 to be disabled.
.PP
For an \s-1NSPR\s0 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 \s-1LDAP\s0 server. You can change
this parameter later using the \fB\f(BIsetNSPRTimeout()\fB\fR method.
.PP
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 (\*(L"self\*(R") and a result structure
as returned by the call to \fB\f(BIldap_result()\fB\fR.
.PP
Finally, you can optionally specify what class the different methods
should use when instantiating \fBEntry\fR result objects. The default is
Mozilla::LDAP::Entry.
.PP
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.
.SH "PERFORMING LDAP SEARCHES"
.IX Header "PERFORMING LDAP SEARCHES"
We assume that you are familiar with the \s-1LDAP\s0 filter syntax already, all
searches performed by this object class uses these filters. You should
also be familiar with \s-1LDAP\s0 URLs, and \s-1LDAP\s0 object classes. There are some
of the few things you actually must know about \s-1LDAP.\s0 Perhaps the simples
filter is
.PP
.Vb 1
\&    (uid=leif)
.Ve
.PP
This matches all entries with the \s-1UID\s0 set to \*(L"leif\*(R". Normally that
would only match one entry, but there is no guarantee for that. To find
everyone with the name \*(L"leif\*(R", you'd instead do
.PP
.Vb 1
\&    (cn=*leif*)
.Ve
.PP
A more complicated search involves logic operators. To find all mail
groups owned by \*(L"leif\*(R" (or actually his \s-1DN\s0), you could do
.PP
.Vb 1
\&    (&(objectclass=mailGroup)(owner=uid=leif,ou=people,o=netscape))
.Ve
.PP
The \fIowner\fR attribute is what's called a \s-1DN\s0 attribute, so to match on it
we have to specify the entire \s-1DN\s0 in the filter above. We could of course
also do a sub string \*(L"wild card\*(R" match, but it's less efficient, and
requires indexes to perform reasonably well.
.PP
Ok, now we are prepared to actually do a real search on the \s-1LDAP\s0 server:
.PP
.Vb 3
\&    $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();
\&          }
\&      }
.Ve
.PP
This is in fact a poor mans implementation of the \fIldapsearch\fR command
line utility. The \fBsearch\fR 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 \fBentry\fR method, until there are no more
entries. The \fBprintLDIF\fR method is a convenient function, requesting the
entry to print itself on \s-1STDOUT,\s0 in \s-1LDIF\s0 format.
.PP
The arguments to the \fBsearch\fR methods are the \fI\s-1LDAP\s0 Base-DN\fR, the
\&\fIscope\fR of the search (\*(L"base\*(R", \*(L"one\*(R" or \*(L"sub\*(R"), and the actual \s-1LDAP
\&\s0\fIfilter\fR. The entry return contains the \s-1DN,\s0 and all attribute values. To
access a specific attribute value, you just have to use the hash array:
.PP
.Vb 1
\&    $cn = $entry\->{cn}[0];
.Ve
.PP
Since many \s-1LDAP\s0 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 \fBsize\fR method:
.PP
.Vb 1
\&    $numVals = $entry\->size("objectclass");
.Ve
.PP
One caveat: Many \s-1LDAP\s0 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 \s-1CIS \s0(Case Insensitive), make sure
you do case insensitive string comparisons.
.PP
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 \s-1LDAP\s0 v3.0) we could also use schema discovery for handling
this even better.
.PP
There is an alternative search method, to use \s-1LDAP\s0 URLs instead of a
filter string. This can be used to easily parse and process URLs, which is
a compact way of storing a \*(L"link\*(R" to some specific \s-1LDAP\s0 information. To
process such a search, you use the \fBsearchURL\fR method:
.PP
.Vb 1
\&    $entry\->searchURL("ldap:///o=netscape.com??sub?(uid=leif)");
.Ve
.PP
As it turns out, the \fBsearch\fR method also supports \s-1LDAP URL\s0 searches. If
the search filter looks like a proper \s-1URL,\s0 we will actually do an \s-1URL\s0
search instead. This is for backward compatibility, and for ease of use.
.PP
To achieve better performance and use less memory, you can limit your
search to only retrieve certain attributes. With the \s-1LDAP\s0 URLs you specify
this as an optional parameter, and with the \fBsearch\fR method you add two
more options, like
.PP
.Vb 1
\&    $entry = $conn\->search($base, "sub", $filter, 0, ("mail", "cn"));
.Ve
.PP
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 \s-1FALSE,\s0 to
retrieve both the attribute names, and all their values. To do this with
the \fBsearchURL\fR method, add a second argument, which should be 0 or 1.
.SH "PERFORMING ASYNCHRONOUS SEARCHES"
.IX Header "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:
.PP
.Vb 12
\&        $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;
\&            }
\&        }
\&    }
.Ve
.SH "MODIFYING AND CREATING NEW LDAP ENTRIES"
.IX Header "MODIFYING AND CREATING NEW LDAP ENTRIES"
Once you have an \s-1LDAP\s0 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 \s-1DN,\s0 like
.PP
.Vb 2
\&    $entry = $conn\->newEntry();
\&    $entry\->setDN("uid=leif,ou=people,o=netscape.com");
.Ve
.PP
alternatively you can still use the \fBnew\fR method on the Entry class, like
.PP
.Vb 1
\&    $entry = Mozilla::LDAP::Entry\->new();
.Ve
.PP
You should not do this for an existing \s-1LDAP\s0 entry, changing the \s-1RDN \s0(or
\&\s-1DN\s0) for such an entry must be done with \fBmodifyRDN\fR. To populate (or
modify) some other attributes, we can do
.PP
.Vb 3
\&    $entry\->{objectclass} = [ "top", "person", "inetOrgPerson" ];
\&    $entry\->{cn} = [ "Leif Hedstrom" ];
\&    $entry\->{mail} = [ "leif@netscape.com" ];
.Ve
.PP
Once you are done modifying your \s-1LDAP\s0 entry, call the \fBupdate\fR method
from the Mozilla::LDAP::Conn object instance:
.PP
.Vb 1
\&    $conn\->update($entry);
.Ve
.PP
Or, if you are creating an entirely new \s-1LDAP\s0 entry, you must call the
\&\fBadd\fR method:
.PP
.Vb 1
\&    $conn\->add($entry);
.Ve
.PP
If all comes to worse, and you have to remove an entry again from the \s-1LDAP\s0
server, just call the \fBdelete\fR method, like
.PP
.Vb 1
\&    $conn\->delete($entry\->getDN());
.Ve
.PP
You can't use native Perl functions like \fIpush()\fR and \fIsplice()\fR 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
.PP
.Vb 3
\&    $entry\->addValue("cn", "The Swede");
\&    $entry\->removeValue("mailAlternateAddress", "leif@mcom.com");
\&    $entry\->remove("seeAlso");
.Ve
.PP
These methods return a \s-1TRUE\s0 or \s-1FALSE\s0 value, depending on the outcome
of the operation. If there was no value to remove, or a value already
exists, we return \s-1FALSE,\s0 otherwise \s-1TRUE.\s0 To check if an attribute has a
certain value, use the \fBhasValue\fR method, like
.PP
.Vb 3
\&    if ($entry\->hasValue("mail", "leif@netscape.com")) {
\&        # Do something
\&    }
.Ve
.PP
There is a similar method, \fBmatchValue\fR, 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.
.SH "OBJECT CLASS METHODS"
.IX Header "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.
.SS "Searching and updating entries"
.IX Subsection "Searching and updating entries"
.IP "\fBadd\fR" 13
.IX Item "add"
Add a new entry to the \s-1LDAP\s0 server. Make sure you use the \fBnew\fR method
for the Mozilla::LDAP::Entry object, to create a proper entry.
.IP "\fBbrowse\fR" 13
.IX Item "browse"
Searches for an \s-1LDAP\s0 entry, but sets some default values to begin with,
such as scope=BASE, filter=(objectclass=*) and so on.  Much like \fBsearch\fR
except for these defaults.  Requires a \s-1DN\s0 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
\&\*(L"attributesOnly\*(R" flag.
.Sp
.Vb 1
\&    $secondEntry = $conn\->browse($entry\->getDN());
.Ve
.IP "\fBclose\fR" 13
.IX Item "close"
Close the \s-1LDAP\s0 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.
.IP "\fBcompare\fR" 13
.IX Item "compare"
Compares an attribute and value to a given \s-1DN\s0 without first doing a
search.  Requires three arguments: a \s-1DN,\s0 the attribute name, and the value
of the attribute. Returns \s-1TRUE\s0 if the attribute/value compared ok.
.Sp
.Vb 2
\&    print "not" unless $conn\->compare($entry\->getDN(), "cn", "Big Swede");
\&    print "ok";
.Ve
.IP "\fBdelete\fR" 13
.IX Item "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 \s-1DN.\s0 If you don't pass it this argument,
\&\fBdelete\fR defaults to delete the current entry, from the last call to
\&\fBsearch\fR or \fBentry\fR. I'd recommend doing a delete with the explicit \s-1DN,\s0
like
.Sp
.Vb 1
\&    $conn\->delete($entry\->getDN());
.Ve
.IP "\fBmodifyRDN\fR" 13
.IX Item "modifyRDN"
This will rename the specified \s-1LDAP\s0 entry, by modifying it's \s-1RDN.\s0 For
example, assuming you have a \s-1DN\s0 of
.Sp
.Vb 1
\&    uid=leif, ou=people, dc=netscape, dc=com
.Ve
.Sp
and you wish to rename to
.Sp
.Vb 1
\&    uid=fiel, ou=people, dc=netscape, dc=com
.Ve
.Sp
you'd do something like
.Sp
.Vb 2
\&    $rdn = "uid=fiel";
\&    $conn\->modifyRDN($rdn, $entry\->getDN());
.Ve
.Sp
Note that this can only be done on the \s-1RDN,\s0 you could not change say
\&\f(CW\*(C`ou=people\*(C'\fR to be \f(CW\*(C`ou=hackers\*(C'\fR 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.
.Sp
The last argument is a boolean (0 or 1), which indicates if the old \s-1RDN\s0
value should be removed from the entry. The default is \s-1TRUE \s0(\*(L"1\*(R").
.IP "\fBnew\fR" 13
.IX Item "new"
This creates and initialized a new \s-1LDAP\s0 connection and object. The
required arguments are host name, port number, bind \s-1DN\s0 and the bind
password. An optional argument is a certificate (public key), which causes
the \s-1LDAP\s0 connection to be established over an \s-1SSL\s0 channel. Currently we do
not support Client Authentication, so you still have to use the simple
authentication method (i.e. with a password).
.Sp
A typical usage could be something like
.Sp
.Vb 2
\&    %ld = Mozilla::LDAP::Utils::ldapArgs();
\&    $conn = Mozilla::LDAP::Conn\->new(\e%ld);
.Ve
.Sp
Also, remember that if you use \s-1SSL,\s0 the port is (usually) 636.
.IP "\fBnewEntry\fR" 13
.IX Item "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 \*(L"tie\*(R"
function when creating the entry. This function takes no arguments, and
returns a pointer to an ::Entry object. For instance
.Sp
.Vb 1
\&    $entry = $conn\->newEntry();
.Ve
.Sp
or
.Sp
.Vb 1
\&    $entry = Mozilla::LDAP::Conn\->newEntry();
.Ve
.IP "\fBnextEntry\fR" 13
.IX Item "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).
.IP "\fBsearch\fR" 13
.IX Item "search"
The \fBsearch\fR method is the main entry point into this module. It requires
at least three arguments: The Base \s-1DN,\s0 the scope, and the search
strings. Two more optional arguments can be given, the first specifies if
only attribute names should be returned (\s-1TRUE\s0 or \s-1FALSE\s0). The second
argument is a list (array) of attributes to return.
.Sp
The last option is very important for performance. If you are only
interested in say the \*(L"mail\*(R" and \*(L"mailHost\*(R" attributes, specifying this in
the search will signficantly reduce the search time. An example of an
efficient search is
.Sp
.Vb 7
\&    @attr = ("cn", "uid", "mail");
\&    $filter = "(uid=*)";
\&    $entry = $conn\->search($base, $scope, $filter, 0, @attr);
\&    while ($entry) {
\&        # do something
\&        $entry = $conn\->nextEntry();
\&    }
.Ve
.IP "\fBsearchURL\fR" 13
.IX Item "searchURL"
This is almost identical to \fBsearch\fR, except this function takes only two
arguments, an \s-1LDAP URL\s0 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 \fBsearch\fR method will actually honor properly formed
\&\s-1LDAP URL\s0's, and use it if appropriate.
.IP "\fBsimpleAuth\fR" 13
.IX Item "simpleAuth"
This method will rebind the \s-1LDAP\s0 connection using new credentials (i.e. a
new user-DN and password). To rebind \*(L"anonymously\*(R", just don't pass a \s-1DN\s0
and password, and it will default to binding as the unprivleged user. For
example:
.Sp
.Vb 4
\&    $user = "leif";
\&    $password = "secret";
\&    $conn = Mozilla::LDAP::Conn\->new($host, $port);     # Anonymous bind
\&    die "Could\*(Aqt 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.
.Ve
.IP "\fBupdate\fR" 13
.IX Item "update"
After modifying an Ldap::Entry entry (see below), use the \fBupdate\fR
method to commit changes to the \s-1LDAP\s0 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 \fBpush\fR or \fBsplice\fR to
modify an entry, the \fBupdate\fR will not recognize such changes.
.Sp
To change the \s-1CN\s0 value for an entry, you could do
.Sp
.Vb 2
\&    $entry\->{cn} = ["Leif Hedstrom"];
\&    $conn\->update($entry);
.Ve
.SS "Other methods"
.IX Subsection "Other methods"
.IP "\fBgetErrorCode\fR" 13
.IX Item "getErrorCode"
Return the error code (numeric) from the last \s-1LDAP API\s0 function
call. Remember that this can only be called \fIafter\fR the successful
creation of a new :Conn object instance. A typical usage could be
.Sp
.Vb 4
\&    if (! $opt_n) {
\&        $conn\->modifyRDN($rdn, $entry\->getDN());
\&        $conn\->printError() if $conn\->getErrorCode();
\&    }
.Ve
.Sp
Which will report any error message as generated by the call to
\&\fBmodifyRDN\fR. Some \s-1LDAP\s0 functions return extra error information, which
can be retrieved like:
.Sp
.Vb 1
\&   $err = getErrorCode(\e$matched, \e$string);
.Ve
.Sp
\&\f(CW$matched\fR will then contain the portion of the matched \s-1DN \s0(if applicable to
the error code), and \f(CW$string\fR will contain any additional error string
returned by the \s-1LDAP\s0 server.
.IP "\fBgetErrorString\fR" 13
.IX Item "getErrorString"
Very much like \fBgetErrorCode\fR, but return a string with a human readable
error message. This can then be used to print a good error message on the
console.
.IP "\fBgetLD\fR" 13
.IX Item "getLD"
Return the (internal) LDAP* connection handle, which you can use
(carefully) to call the native \s-1LDAP API\s0 functions. You shouldn't have to
use this in most cases, unless of course our \s-1OO\s0 layer is seriously flawed.
.IP "\fBgetRes\fR" 13
.IX Item "getRes"
Just like \fBgetLD\fR, except it returns the internal \s-1LDAP\s0 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 \s-1API\s0 functions, like
.Sp
.Vb 3
\&    $cld = $conn\->getLD();
\&    $res = $conn\->getRes();
\&    $count = Mozilla::LDAP::API::ldap_count_entries($cld, $res);
.Ve
.IP "\fBisURL\fR" 13
.IX Item "isURL"
Returns \s-1TRUE\s0 or \s-1FALSE\s0 if the given argument is a properly formed \s-1URL.\s0
.IP "\fBprintError\fR" 13
.IX Item "printError"
Print the last error message on standard output.
.IP "\fBsetRebindProc\fR" 13
.IX Item "setRebindProc"
Tell the \s-1LDAP SDK\s0 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 \s-1DN,\s0 password and authentication method. A typical usage is
.Sp
.Vb 3
\&    sub rebindProc {
\&        return ("uid=ldapadmin", "secret", LDAP_AUTH_SIMPLE);
\&    }
\&
\&    $ld\->setRebindProc(\e&rebindProc);
.Ve
.IP "\fBsetDefaultRebindProc\fR" 13
.IX Item "setDefaultRebindProc"
This is very much like the previous function, except instead of specifying
the function to use, you give it the \s-1DN,\s0 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.
.IP "\fBsetVersion\fR" 13
.IX Item "setVersion"
Change the \s-1LDAP\s0 protocol version on the already initialized connection.
The default is \s-1LDAP\s0 v3 (new for PerLDAP v1.5!), but you can downgrade
the connection to \s-1LDAP\s0 v2 if necessary using this function. Example:
.Sp
.Vb 1
\&    $conn\->setVersion(2);
.Ve
.IP "\fBgetVersion\fR" 13
.IX Item "getVersion"
Return the protocol version currently in used by the connection.
.IP "\fBsetSizelimit\fR" 13
.IX Item "setSizelimit"
Set the sizelimit on a connection, to limit the maximum number of
entries that we want to retrieve. For example:
.Sp
.Vb 1
\&   $conn\->setSizelimit(10);
.Ve
.IP "\fBgetSizelimit\fR" 13
.IX Item "getSizelimit"
Get the current sizelimit on a connection (if any).
.IP "\fBsetOption\fR" 13
.IX Item "setOption"
Set an (integer) \s-1LDAP\s0 option.
.IP "\fBgetOption\fR" 13
.IX Item "getOption"
Get an (integer) \s-1LDAP\s0 option.
.IP "\fBinstallNSPR\fR" 13
.IX Item "installNSPR"
Install \s-1NSPR I/O,\s0 threading, and \s-1DNS\s0 functions so they will be used by
\&'ld'.
.Sp
Pass a non-zero value for the 'shared' parameter if you plan to use
this \s-1LDAP\s0 * handle from more than one thread. This is highly unlikely
since PerLDAP is asynchronous.
.IP "\fBsetNSPRTimeout\fR" 13
.IX Item "setNSPRTimeout"
Set the \s-1TCP\s0 timeout value, in millisecond, for the \s-1NSPR\s0 enabled connection.
It's an error to call this before calling \fIinstallNSPR()\fR, unless you
created the new connection object with the \fBnspr\fR option.
.Sp
This method can also be invoked as a class method, and it will then apply
to all new connections created. Like
.Sp
.Vb 2
\&    Mozilla::LDAP::Conn\->installNSPR(1);
\&    Mozilla::LDAP::Conn\->setNSPRTimeout(1000);
.Ve
.SH "EXAMPLES"
.IX Header "EXAMPLES"
There are plenty of examples to look at, in the examples directory. We are
adding more examples every day (almost).
.SH "INSTALLATION"
.IX Header "INSTALLATION"
Installing this package is part of the Makefile supplied in the
package. See the installation procedures which are part of this package.
.SH "AVAILABILITY"
.IX Header "AVAILABILITY"
This package can be retrieved from a number of places, including:
.PP
.Vb 2
\&    http://www.mozilla.org/directory/
\&    Your local CPAN server
.Ve
.SH "CREDITS"
.IX Header "CREDITS"
Most of this code was developed by Leif Hedstrom, Netscape Communications
Corporation.
.SH "BUGS"
.IX Header "BUGS"
None. :)
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Mozilla::LDAP::Entry, LDAP::Mozilla:Utils LDAP::Mozilla:API and
of course Perl.