.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "LDAPapi 3pm"
.TH LDAPapi 3pm "2018-11-02" "perl v5.28.0" "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"
Net::LDAPapi \- Perl5 Module Supporting LDAP API
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Net::LDAPapi;
\&
\&  See individual items and Example Programs for Usage
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
.Vb 2
\&  This module allows Perl programmers to access and manipulate an LDAP
\&  based Directory.
\&
\&  Versions beginning with 1.40 support both the original "C API" and
\&  new "Perl OO" style interface methods.  With version 1.42, I\*(Aqve added
\&  named arguments.
.Ve
.SH "THE INTIAL CONNECTION"
.IX Header "THE INTIAL CONNECTION"
.Vb 3
\&  All connections to the LDAP server are started by creating a new
\&  "blessed object" in the Net::LDAPapi class.  This can be done quite
\&  easily by the following type of statement.
\&
\&  $ld = new Net::LDAPapi($hostname);
\&
\&  Where $hostname is the name of your LDAP server.  If you are not using
\&  the standard LDAP port (389), you will also need to supply the
\&  portnumber.
\&
\&  $ld = new Net::LDAPapi($hostname, 15555);
\&
\&  The new method can also be called with named arguments.
\&
\&  $ld = new Net::LDAPapi(\-host=>$hostname, \-port=>15389);
\&
\&  Instead of the above mentioned argumens \-url can be used in the
\&  following form
\&
\&  $ld = new Net::LDAPapi(\-url=>"ldap://host:port");
\&
\&  Setting \-debug=>"TRUE" will enable more verbose error messages.
\&
\&  Note that with named arguments, the order of the arguments is
\&  insignificant.
.Ve
.SH "CONTROLS"
.IX Header "CONTROLS"
.Vb 9
\&  In LDAP v3 controls are an additional piece of data, which can be
\&  submitted with most of the requests to the server and returned back
\&  attached to the result.  Controls, passed to the call, are separated
\&  in two types.  The client side controls, which are not passed to the
\&  server and are of not much use.  They are denoted by \-cctrls named
\&  parameter.  The server side controls, denoted by \-sctrls named
\&  parameter are actually passed to the server and may affect its
\&  operation or returned results.  Each entry of the result may have
\&  controls attached to it as well ( see parse_entry(...) call ).
\&
\&  \-cctrls and \-sctrls must be reference to array of controls.
\&
\&  To create control call create_control(...) method. Bellow is an
\&  example of creating valsort control.
\&
\&  my $asn = Convert::ASN1\->new;
\&  $asn\->prepare(\*(AqSEQUENCE { b BOOLEAN }\*(Aq);
\&  my $berval = $asn\->encode(b=>1); # or 1
\&
\&  my $ctrl =
\&    $ld\->create_control(\-oid=>Net::LDAPapi::LDAP_CONTROL_VALSORT,
\&                        \-berval=>$berval,
\&                        \-critical=>Net::LDAPapi::CRITICAL);
\&
\&  The control is to be freed by calling free_control($ctrl).
\&
\&  If contol is attached to results entry, it can be retrieved by
\&  calling parse_result($entry). If no entry is passed to
\&  parse_result(...) then current entry is used. It returns hash
\&  with following keys
\&
\&  Key           Value
\&  \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\&  matcheddn     string
\&  errmsg        string
\&  referrals     array reference
\&  serverctrls   array reference
\&
\&  You can look into content of the control by using get_contol_XXX
\&  functions like this:
\&
\&  local %parsed = $ld\->parse_result($entry);
\&  local $serverctrls = $parsed{"serverctrls"};
\&  local @sctrls = @$serverctrls;
\&  if( scalar(@sctrls) > 0 ) {
\&    foreach $ctrl (@sctrls) {
\&      print "\enreceived control\en";
\&      print "oid = ".$ld\->get_control_oid($ctrl)."\en";
\&      print "berval = ".$ld\->get_control_berval($ctrl)."\en";
\&      print "critical = ".$ld\->get_control_critical($ctrl)."\en";
\&    }
\&  }
.Ve
.SH "BINDING"
.IX Header "BINDING"
.Vb 3
\&  After creating a connection to the LDAP server, you may need to
\&  bind to the server prior to performing any LDAP related functions.
\&  This can be done with the \*(Aqbind\*(Aq methods.
\&
\&  An anonymous bind can be performed without arguments:
\&
\&  $status = $ld\->bind_s;
\&
\&  A simple bind can be performed by specifying the DN and PASSWORD of
\&  the user you are authenticating as:
\&
\&  $status = $ld\->bind_s($dn, $password);
\&
\&  Note that if $password above was "", you would be doing a reference
\&  bind, which would return success even if the password in the
\&  directory was non\-null.  Thus if you were using the bind to check a
\&  password entered with one in the directory, you should first check
\&  to see if $password was NULL.
\&
\&  To perform SASL bind fill in appropriate parameters calling
\&  sasl_params(...) and call
\&
\&  $status = $ld\->bind_s(\-type=>LDAP_AUTH_SASL)
\&
\&  Bellow is an example of GSSAPI K5 bind parameters.
\&
\&  $ld\->sasl_parms(\-mech=>"GSSAPI", \-realm=>"domain.name.com",
\&                  \-authzid=>"",    \-secprops=>"",
\&                  \-flags=>LDAP_SASL_QUIET);
\&
\&  For all of the above operations, you could compare $status to
\&  LDAP_SUCCESS to see if the operation was successful.
\&
\&  Additionally, you could use \*(Aqbind\*(Aq rather than \*(Aqbind_s\*(Aq if you wanted
\&  to use the Asynchronous LDAP routines.  The asynchronous routines
\&  would return a MSGID rather than a status.  To find the status of an
\&  Asynchronous bind, you would need to first obtain the result with a
\&  call to $ld\->result.  See the entry for result later in the man page,
\&  as well as the \*(Aqldapwalk.pl\*(Aq example for further information on
\&  obtaining results from Asynchronous operations.
\&
\&  The bind operations can also accept named arguments.
\&
\&  $status = $ld\->bind_s(\-dn=>$dn,
\&                        \-password=>$password,
\&                        \-type=>LDAP_AUTH_SIMPLE);
\&
\&  As with all other commands that support named arguments, the order of
\&  the arguments makes no difference.
.Ve
.SH "GENERATING AN ADD/MODIFY HASH"
.IX Header "GENERATING AN ADD/MODIFY HASH"
.Vb 2
\&  For the add and modify routines you will need to generate
\&  a list of attributes and values.
\&
\&  You will do this by creating a HASH table.  Each attribute in the
\&  hash contains associated values.  These values can be one of three
\&  things.
\&
\&    \- SCALAR VALUE    (ex. "Clayton Donley")
\&    \- ARRAY REFERENCE (ex. ["Clayton Donley","Clay Donley"])
\&    \- HASH REFERENCE  (ex. {"r",["Clayton Donley"]}
\&         note:  the value inside the HASH REFERENCE must currently
\&             be an ARRAY REFERENCE.
\&
\&  The key inside the HASH REFERENCE must be one of the following for a
\&  modify operation:
\&    \- "a" for LDAP_MOD_ADD (Add these values to the attribute)
\&    \- "r" for LDAP_MOD_REPLACE (Replace these values in the attribute)
\&    \- "d" for LDAP_MOD_DELETE (Delete these values from the attribute)
\&
\&  Additionally, in add and modify operations, you may specify "b" if the
\&  attributes you are adding are BINARY (ex. "rb" to replace binary).
\&
\&  Currently, it is only possible to do one operation per add/modify
\&  operation, meaning you can\*(Aqt do something like:
\&
\&     {"d",["Clayton"],"a",["Clay"]}   <\-\- WRONG!
\&
\&  Using any combination of the above value types, you can do things like:
\&
\&  %ldap_modifications = (
\&     "cn", "Clayton Donley",                    # Replace \*(Aqcn\*(Aq values
\&     "givenname", ["Clayton","Clay"],           # Replace \*(Aqgivenname\*(Aq values
\&     "mail", {"a",["donley\e@cig.mcel.mot.com"],  #Add \*(Aqmail\*(Aq values
\&     "jpegphoto", {"rb",[$jpegphotodata]},      # Replace Binary jpegPhoto
\&  );
\&
\&  Then remember to call the add or modify operations with a REFERENCE to
\&  this HASH.  Something like:
\&
\&  $ld\->modify_s($modify_dn,\e%ldap_modifications);
.Ve
.SH "GETTING/SETTING LDAP INTERNAL VALUES"
.IX Header "GETTING/SETTING LDAP INTERNAL VALUES"
.Vb 2
\&  The following methods exist to obtain internal values within a
\&  Net::LDAPapi object:
\&
\&  o errno \- The last error\-number returned by the LDAP library for this
\&    connection.
\&          ex:  print "Error Number: " . $ld\->errno . "\en";
\&
\&  o errstring \- The string equivalent of \*(Aqerrno\*(Aq.
\&          ex:  print "Error: " . $ld\->errstring . "\en";
\&
\&  o ld \- Reference to the actual internal LDAP structure.  Only useful if
\&    you needed to obtain this pointer for use in non\-OO routines.
\&          ex:  $ldptr = $ld\->ld;
\&
\&  o entry \- Reference to the current entry.  Not typically needed, but method
\&    supplied, just in case.
\&          ex:  $entry = $ld\->entry;
\&
\&  o msgid \- Get msgid from an LDAP Result.
\&          ex:  $msgid = $ld\->msgid;  #  msgid of current result
\&          ex:  $msgid = $ld\->msgid($result) # msgid of $result
\&
\&  o msgtype \- Get msgtype from an LDAP Result.
\&      ex:  $msgtype = $ld\->msgtype;  # msgtype of current result
\&          ex:  $msgtype = $ld\->msgtype($result) # msgtype of $result
\&
\&  These methods are only useful for GETTING internal information, not setting
\&  it.  No methods are currently available for SETTING these internal values.
.Ve
.SH "GETTING AND SETTING LDAP SESSION OPTIONS"
.IX Header "GETTING AND SETTING LDAP SESSION OPTIONS"
.Vb 2
\&  The get_option and set_option methods can be used to get and set LDAP
\&  session options.
\&
\&  The following LDAP options can be set or gotten with these methods:
\&    LDAP_OPT_DEREF \- Dereference
\&    LDAP_OPT_SIZELIMIT \- Maximum Number of Entries to Return
\&    LDAP_OPT_TIMELIMIT \- Timeout for LDAP Operations
\&    LDAP_OPT_REFERRALS \- Follow Referrals
\&
\&  For both get and set operations, the first argument is the relivant
\&  option.  In get, the second argument is a reference to a scalar variable
\&  that will contain the current value of the option.  In set, the second
\&  argument is the value at which to set this option.
\&
\&  Examples:
\&    $ld\->set_option(LDAP_OPT_SIZELIMIT,50);
\&    $ld\->get_option(LDAP_OPT_SIZELIMIT,\e$size);
\&
\&  When setting LDAP_OPT_REFERRALS, the second argument is either LDAP_OPT_ON
\&  or LDAP_OPT_OFF.  Other options require a number.
\&
\&  Both get_option and set_option return 0 on success and non\-zero otherwise.
.Ve
.SH "SSL SUPPORT"
.IX Header "SSL SUPPORT"
.Vb 3
\&  When compiled with the Mozilla SDK, this module now supports SSL.
\&  I do not have an SSL capable server, but I\*(Aqm told this works.  The
\&  functions available are:
\&
\&  o ssl \- Turn on SSL for this connection.
\&    Install I/O routines to make SSL over LDAP possible
\&  o ssl_client_init($certdbpath,$certdbhandle)
\&    Initialize the secure parts (called only once)
\&
\&  Example:
\&    $ld = new Net::LDAPapi("host",LDAPS_PORT);
\&    $ld\->ssl_client_init($certdbpath,$certdbhandle);
\&    $ld\->ssl;
.Ve
.SH "SETTING REBIND PROCESS"
.IX Header "SETTING REBIND PROCESS"
.Vb 1
\&  As of version 1.42, rebinding now works properly.
\&
\&  The set_rebind_proc method is used to set a PERL function to supply DN,
\&  PASSWORD, and AUTHTYPE for use when the server rebinds (for referals,
\&  etc...).
\&
\&  Usage should be something like:
\&    $rebind_ref = \e&my_rebind_proc;
\&    $ld\->set_rebind_proc($rebind_ref);
\&
\&  You can then create the procedure specified.  It should return 3 values.
\&
\&  Example:
\&    sub my_rebind_proc
\&    {
\&       return($dn,$pass,LDAP_AUTH_SIMPLE);
\&    }
.Ve
.SH "EXTENDED OPERATIONS"
.IX Header "EXTENDED OPERATIONS"
.Vb 1
\&  Extended operations are supported.
\&  
\&  The extended_operation and extended_operation_s methods are used to
\&  invoke extended operations.
\&  
\&  Example (WHOAMI):
\&  
\&    %result = ();
\&  
\&    if ($ld\->extended_operation_s(\-oid => "1.3.6.1.4.1.4203.1.11.3", \-result => \e%result) != LDAP_SUCCESS)
\&    {
\&      $ld\->perror("ldap_extended_operation_s");
\&      exit \-1;
\&    }
\&  
\&  Note that WHOAMI is already natively implemented via whoami and whoami_s 
\&  methods.
.Ve
.SH "SUPPORTED METHODS"
.IX Header "SUPPORTED METHODS"
.IP "abandon \s-1MSGID SCTRLS CCTRLS\s0" 4
.IX Item "abandon MSGID SCTRLS CCTRLS"
.Vb 2
\&  This cancels an asynchronous LDAP operation that has not completed.  It
\&  returns an LDAP STATUS code upon completion.
\&
\&  Example:
\&
\&    $status = ldap_abandon($ld, $msgid); # XXX fix this
.Ve
.IP "add \s-1DN ATTR SCTRLS CCTRLS\s0" 4
.IX Item "add DN ATTR SCTRLS CCTRLS"
.Vb 2
\&  Begins an an asynchronous LDAP Add operation.  It returns a MSGID or undef
\&  upon completion.
\&
\&  Example:
\&
\&    %attributes = (
\&       "cn", ["Clayton Donley","Clay Donley"] #Add Multivalue cn
\&       "sn", "Donley",                #Add sn
\&       "telephoneNumber", "+86\-10\-65551234",  #Add telephoneNumber
\&       "objectClass", ["person","organizationalPerson"],
\&                        # Add Multivalue objectClass
\&       "jpegphoto", {"b",[$jpegphoto]},  # Add Binary jpegphoto
\&    );
\&
\&    $entrydn = "cn=Clayton Donley, o=Motorola, c=US";
\&
\&    $msgid = $ld\->add($entrydn, \e%attributes);
\&
\&  Note that in most cases, you will need to be bound to the LDAP server
\&  as an administrator in order to add users.
.Ve
.IP "add_s \s-1DN ATTR SCTRLS CCTRLS\s0" 4
.IX Item "add_s DN ATTR SCTRLS CCTRLS"
.Vb 3
\&  Synchronous version of the \*(Aqadd\*(Aq method.  Arguments are identical
\&  to the \*(Aqadd\*(Aq method, but this operation returns an LDAP STATUS,
\&  not a MSGID.
\&
\&  Example:
\&
\&    $ld\->add_s($entrydn, \e%attributes);
\&
\&  See the section on creating the modify structure for more information
\&  on populating the ATTRIBUTES field for Add and Modify operations.
.Ve
.IP "bind \s-1DN PASSWORD TYPE SCTRLS CCTRLS\s0" 4
.IX Item "bind DN PASSWORD TYPE SCTRLS CCTRLS"
.Vb 2
\&  Asynchronous method for binding to the LDAP server.  It returns a
\&  MSGID.
\&
\&  Examples:
\&
\&    $msgid = $ld\->bind;
\&    $msgid = $ld\->bind("cn=Clayton Donley, o=Motorola, c=US", "abc123");
.Ve
.IP "bind_s \s-1DN PASSWORD TYPE SCTRLS CCTRLS\s0" 4
.IX Item "bind_s DN PASSWORD TYPE SCTRLS CCTRLS"
.Vb 2
\&  Synchronous method for binding to the LDAP server.  It returns
\&  an LDAP STATUS.
\&
\&  Examples:
\&
\&    $status = $ld\->bind_s;
\&    $status = $ld\->bind_s("cn=Clayton Donley, o=Motorola, c=US", "abc123");
.Ve
.IP "compare \s-1DN ATTR VALUE SCTRLS CCTRLS\s0" 4
.IX Item "compare DN ATTR VALUE SCTRLS CCTRLS"
.Vb 2
\&  Asynchronous method for comparing a value with the value contained
\&  within DN.  Returns a MSGID or undef.
\&
\&  Example:
\&
\&    $msgid = $ld\->compare("cn=Clayton Donley, o=Motorola, c=US", \e
\&        $type, $value);
.Ve
.IP "compare_s \s-1DN ATTR VALUE SCTRLS CCTRLS\s0" 4
.IX Item "compare_s DN ATTR VALUE SCTRLS CCTRLS"
.Vb 2
\&  Synchronous method for comparing a value with the value contained
\&  within DN.  Returns an LDAP_COMPARE_TRUE, LDAP_COMPARE_FALSE or an error code.
\&
\&  Example:
\&
\&    $status = $ld\->compare_s("cn=Clayton Donley, o=Motorola, c=US", \e
\&        $type, $value);
.Ve
.IP "count_entries" 4
.IX Item "count_entries"
.Vb 1
\&  Returns the number of entries in an LDAP result chain.
\&
\&  Example:
\&
\&    $number = $ld\->count_entries;
.Ve
.IP "count_references \s-1MSG\s0" 4
.IX Item "count_references MSG"
.Vb 1
\&  Return number of references in a given/current message.
\&
\&  Example:
\&
\&    $number = $ld\->count_references
.Ve
.IP "delete \s-1DN\s0" 4
.IX Item "delete DN"
.Vb 1
\&  Asynchronous method to delete DN.  Returns a MSGID or \-1 if error.
\&
\&  Example:
\&
\&    $msgid = $ld\->delete("cn=Clayton Donley, o=Motorola, c=US");
.Ve
.IP "delete_s \s-1DN\s0" 4
.IX Item "delete_s DN"
.Vb 1
\&  Synchronous method to delete DN.  Returns an LDAP STATUS.
\&
\&  Example:
\&
\&    $status = $ld\->delete_s("cn=Clayton Donley, o=Motorola, c=US");
.Ve
.IP "dn2ufn \s-1DN\s0" 4
.IX Item "dn2ufn DN"
.Vb 2
\&  Converts a Distinguished Name (DN) to a User Friendly Name (UFN).
\&  Returns a string with the UFN.
\&
\&  Since this operation doesn\*(Aqt require an LDAP object to work, you
\&  could technically access the function directly as \*(Aqldap_dn2ufn\*(Aq rather
\&  that the object oriented form.
\&
\&  Example:
\&
\&    $ufn = $ld\->dn2ufn("cn=Clayton Donley, o=Motorola, c=US");
.Ve
.IP "explode_dn \s-1DN NOTYPES\s0" 4
.IX Item "explode_dn DN NOTYPES"
.Vb 3
\&  Splits the DN into an array comtaining the separate components of
\&  the DN.  Returns an Array.  NOTYPES is a 1 to remove attribute
\&  types and 0 to retain attribute types.
\&
\&  Can also be accessed directly as \*(Aqldap_explode_dn\*(Aq if no session is
\&  initialized and you don\*(Aqt want the object oriented form.
\&
\&  In OpenLDAP this call is depricated.
\&
\&  Example:
\&
\&    @components = $ld\->explode_dn($dn, 0);
.Ve
.IP "explode_rdn \s-1RDN NOTYPES\s0" 4
.IX Item "explode_rdn RDN NOTYPES"
.Vb 4
\&  Same as explode_dn, except that the first argument is a
\&  Relative Distinguished Name.  NOTYPES is a 1 to remove attribute
\&  types and 0 to retain attribute types.  Returns an array with
\&  each component.
\&
\&  Can also be accessed directly as \*(Aqldap_explode_rdn\*(Aq if no session is
\&  initialized and you don\*(Aqt want the object oriented form.
\&
\&  In OpenLDAP this call is depricated.
\&
\&  Example:
\&
\&    @components = $ld\->explode_rdn($rdn, 0);
.Ve
.IP "extended_operation \s-1OID BERVAL SCTRLS CCTRLS\s0" 4
.IX Item "extended_operation OID BERVAL SCTRLS CCTRLS"
.Vb 1
\&  Asynchronous method for invoking an extended operation. 
\&  
\&  Returns a non\-negative MSGID upon success.
\&  
\&  Examples:
\&  
\&    $msgid = $ld\->extended_operation("1.3.6.1.4.1.4203.1.11.3");
.Ve
.IP "extended_operation_s \s-1OID BERVAL SCTRLS CCTRLS RESULT\s0" 4
.IX Item "extended_operation_s OID BERVAL SCTRLS CCTRLS RESULT"
.Vb 1
\&  Synchronous method for invoking an extended operation. 
\&  
\&  Returns LDAP_SUCCESS upon success.
\&      
\&  Examples:
\&  
\&    $status = $ld\->extended_operation_s(\-oid => "1.3.6.1.4.1.4203.1.11.3", \e
\&        \-result => \e%result);
.Ve
.IP "first_attribute" 4
.IX Item "first_attribute"
.Vb 3
\&  Returns pointer to first attribute name found in the current entry.
\&  Note that this only returning attribute names (ex: cn, mail, etc...).
\&  Returns a string with the attribute name.
\&
\&  Returns an empty string when no attributes are available.
\&
\&  Example:
\&
\&    $attr = $ld\->first_attribute;
.Ve
.IP "first_entry" 4
.IX Item "first_entry"
.Vb 2
\&  Sets internal pointer to the first entry in a chain of results.  Returns
\&  an empty string when no entries are available.
\&
\&  Example:
\&
\&    $entry = $ld\->first_entry;
.Ve
.IP "first_message" 4
.IX Item "first_message"
.Vb 5
\&   Return the first message in a chain of result returned by the search
\&   operation. LDAP search operations return LDAPMessage, which is a head
\&   in chain of messages accessable to the user. Not all all of them are
\&   entries though. Type of the message can be obtained by calling
\&   msgtype(...) function.
.Ve
.IP "get_all_entries \s-1RESULT\s0" 4
.IX Item "get_all_entries RESULT"
.Vb 4
\&  Returns result of the search operation in the following format
\&    (HASH)
\&    dn \-> (HASH)
\&          key \-> (ARRAY)
\&
\&  Example:
\&    my $all_entries_ref = $ld\->get_all_entries;
\&    my %all_entries = %$all_entries_ref;
\&
\&    foreach (keys %all_entries) {
\&        print "<$_> \-> <".$all_entries{$_}.">\en";
\&        $entry = $all_entries{$_};
\&
\&        local %entry_h = %$entry;
\&        foreach $k (keys %entry_h) {
\&            $values = $entry_h{$k};
\&
\&            print "  <$k> \->\en";
\&            foreach $val (@$values) {
\&                print "     <$val>\en";
\&            }
\&        }
\&    }
.Ve
.IP "get_dn \s-1MSG\s0" 4
.IX Item "get_dn MSG"
.Vb 3
\&  Returns a string containing the DN for the specified message or an
\&  empty string if an error occurs. If no message is specified then
\&  then default entry is used.
\&
\&  Example:
\&
\&    $dn = $ld\->get_dn;
.Ve
.IP "get_entry_controls \s-1MSG\s0" 4
.IX Item "get_entry_controls MSG"
.Vb 2
\&  Returns an array of controls returned with the given entry. If not MSG
\&  is given as a paramater then current message/entry is used.
\&
\&  Example:
\&
\&    my @sctrls = $ld\->get_entry_controls($msg);
\&    foreach $ctrl (@sctrls) {
\&        print "control oid is ".$self\->get_control_oid($ctrl)."\en";
\&    }
.Ve
.IP "get_values \s-1ATTR\s0" 4
.IX Item "get_values ATTR"
.Vb 2
\&  Obtain a list of all values associated with a given attribute.
\&  Returns an empty list if none are available.
\&
\&  Example:
\&
\&    @values = $ld\->get_values("cn");
\&
\&  This would put all the \*(Aqcn\*(Aq values for $entry into the array @values.
.Ve
.IP "get_values_len \s-1ATTR\s0" 4
.IX Item "get_values_len ATTR"
.Vb 1
\&  Retrieves a set of binary values for the specified attribute.
\&
\&  Example:
\&
\&    @values = $ld\->get_values_len("jpegphoto");
\&
\&  This would put all the \*(Aqjpegphoto\*(Aq values for $entry into the array @values.
\&  These could then be written to a file, or further processed.
.Ve
.IP "is_ldap_url \s-1URL\s0" 4
.IX Item "is_ldap_url URL"
.Vb 2
\&  Checks to see if a specified URL is a valid LDAP Url.  Returns 0 on false
\&  and 1 on true.
\&
\&  Example:
\&
\&    $isurl = $ld\->is_ldap_url("ldap://x500.my.org/o=Org,c=US");
.Ve
.IP "listen_for_changes \s-1BASEDN SCOPE FILTER ATTRS ATTRSONLY TIMEOUT SIZELIMIT COOKIE\s0" 4
.IX Item "listen_for_changes BASEDN SCOPE FILTER ATTRS ATTRSONLY TIMEOUT SIZELIMIT COOKIE"
.Vb 7
\&  Experimental function which implements syncrepl API in
\&  refreshAndPersist mode. All but one arguments are the same as in search
\&  function. Argument \*(Aqcookie\*(Aq is the special one here. It must be specified
\&  and is a file name in which cookie is to be stored. On a subsequent
\&  restart of the seach only the newer results will be returned than those
\&  indicated by the stored cookie. To refresh all entries, one would have to
\&  remove that file.
\&
\&  This function is to be used in conjunction with next_changed_entries(...),
\&  there you will also find example of its usage.
.Ve
.IP "msgfree" 4
.IX Item "msgfree"
.Vb 1
\&  Frees the current LDAP result.  Returns the type of message freed.
\&
\&  Example:
\&
\&    $type = $ld\->msgfree;
.Ve
.IP "msgtype \s-1MSG\s0" 4
.IX Item "msgtype MSG"
.Vb 6
\&  Returns the numeric id of a given message. If no MSG is given as a parameter
\&  then current message is used. Following types are recognized: LDAP_RES_BIND,
\&  LDAP_RES_SEARCH_ENTRY, LDAP_RES_SEARCH_REFERENCE, LDAP_RES_SEARCH_RESULT,
\&  LDAP_RES_MODIFY, LDAP_RES_ADD, LDAP_RES_DELETE, LDAP_RES_MODDN,
\&  LDAP_RES_COMPARE, LDAP_RES_EXTENDED, LDAP_RES_INTERMEDIATE, LDAP_RES_ANY,
\&  LDAP_RES_UNSOLICITED.
\&
\&  Example:
\&
\&    $type = $ld\->msgtype
.Ve
.IP "msgtype2str \s-1TYPE\s0" 4
.IX Item "msgtype2str TYPE"
.Vb 1
\&  Returns string representation of a given numeric message type.
\&
\&  Example:
\&    print "type = ".$ld\->msgtype2str($ld\->msgtype)."\en";
.Ve
.IP "modify \s-1DN MOD\s0" 4
.IX Item "modify DN MOD"
.Vb 4
\&  Asynchronous method to modify an LDAP entry.  DN is the DN to
\&  modify and MOD contains a hash\-table of attributes and values.  If
\&  multiple values need to be passed for a specific attribute, a
\&  reference to an array must be passed.
\&
\&  Returns the MSGID of the modify operation.
\&
\&  Example:
\&
\&    %mods = (
\&      "telephoneNumber", "",     #remove telephoneNumber
\&      "sn", "Test",              #set SN to TEST
\&      "mail", ["me\e@abc123.com","me\e@second\-home.com"],  #set multivalue \*(Aqmail\*(Aq
\&      "pager", {"a",["1234567"]},  #Add a Pager Value
\&      "jpegphoto", {"rb",[$jpegphoto]},  # Replace Binary jpegphoto
\&    );
\&
\&    $msgid = $ld\->modify($entrydn,\e%mods);
\&
\&  The above would remove the telephoneNumber attribute from the entry
\&  and replace the "sn" attribute with "Test".  The value in the "mail"
\&  attribute for this entry would be replaced with both addresses
\&  specified in @mail.  The "jpegphoto" attribute would be replaced with
\&  the binary data in $jpegphoto.
.Ve
.IP "modify_s \s-1DN MOD\s0" 4
.IX Item "modify_s DN MOD"
.Vb 3
\&  Synchronous version of modify method.  Returns an LDAP STATUS.  See the
\&  modify method for notes and examples of populating the MOD
\&  parameter.
\&
\&  Example:
\&
\&    $status = $ld\->modify_s($entrydn,\e%mods);
.Ve
.IP "modrdn2 \s-1DN NEWRDN DELETE\s0" 4
.IX Item "modrdn2 DN NEWRDN DELETE"
.Vb 1
\&  No longer available. Use function \*(Aqrename\*(Aq.
.Ve
.IP "modrdn2_s \s-1DN NEWRDN DELETE\s0" 4
.IX Item "modrdn2_s DN NEWRDN DELETE"
.Vb 1
\&  No longer available. Use function \*(Aqrename_s\*(Aq.
.Ve
.IP "next_attribute" 4
.IX Item "next_attribute"
.Vb 3
\&  Similar to first_attribute, but obtains next attribute.
\&  Returns a string comtaining the attribute name.  An empty string
\&  is returned when no further attributes exist.
\&
\&  Example:
\&
\&    $attr = $ld\->next_attribute;
.Ve
.IP "next_changed_entries \s-1MSGID ALL TIMEOUT\s0" 4
.IX Item "next_changed_entries MSGID ALL TIMEOUT"
.Vb 5
\& This function is too be used together with listen_for_changes(...) (see above).
\& It returns an array of Entries, which has just changed. Each element in this
\& array is a hash reference with two key value pairs, \*(Aqentry\*(Aq which contains usual
\& entry and \*(Aqstate\*(Aq which contain one of the following strings \*(Aqpresent\*(Aq, \*(Aqadd\*(Aq,
\& \*(Aqmodify\*(Aq or \*(Aqdelete\*(Aq.
\&
\& Example:
\&
\&    my $msgid = $ld\->listen_for_changes(\*(Aq\*(Aq, LDAP_SCOPE_SUBTREE, "(cn=Dm*)", NULL, NULL,
\&                                    NULL, NULL, $cookie);
\&
\&    while(1) {
\&        while( @entries = $ld\->next_changed_entries($msgid, 0, \-1) ) {
\&            foreach $entry (@entries) {
\&                print "entry dn is <".$ld\->get_dn($entry\->{\*(Aqentry\*(Aq})."> ".
\&                    $entry\->{\*(Aqstate\*(Aq}."\en";
\&            }
\&        }
\&    }
.Ve
.IP "next_entry" 4
.IX Item "next_entry"
.Vb 1
\&  Moves internal pointer to the next entry in a chain of search results.
\&
\&  Example:
\&
\&    $entry = $ld\->next_entry;
.Ve
.IP "next_message" 4
.IX Item "next_message"
.Vb 1
\&  Moves internal pointer to the next message in a chain of search results.
\&
\&  Example:
\&
\&    $msg = $ld\->next_message;
.Ve
.IP "parse_result \s-1MSG FREEMSG\s0" 4
.IX Item "parse_result MSG FREEMSG"
.Vb 8
\&  This function is used to retrieve auxiliary data associated with the
\&  message. The return value is a hashtable containing following kevalue
\&  pairs.
\&    \*(Aqerrcode\*(Aq     \-> numeric
\&    \*(Aqmatcheddn\*(Aq   \-> string
\&    \*(Aqerrmsg\*(Aq      \-> string
\&    \*(Aqreferrals\*(Aq   \-> array reference
\&    \*(Aqserverctrls\*(Aq \-> array reference
\&
\&  The FREEMSG parameter determines whether the parsed message is freed
\&  or not after the extraction. Any non\-zero value will make it free the
\&  message. The msgfree() routine can also be used to free the message
\&  later.
.Ve
.IP "perror \s-1MSG\s0" 4
.IX Item "perror MSG"
.Vb 3
\&  If an error occurs while performing an LDAP function, this procedure
\&  will display it.  You can also use the err and errstring methods to
\&  manipulate the error number and error string in other ways.
\&
\&  Note that this function does NOT terminate your program.  You would
\&  need to do any cleanup work on your own.
\&
\&  Example:
\&
\&    $ld\->perror("add_s");
.Ve
.IP "rename \s-1DN NEWRDN NEWSUPER DELETE SCTRLS CCTRLS\s0" 4
.IX Item "rename DN NEWRDN NEWSUPER DELETE SCTRLS CCTRLS"
.Vb 4
\&  Asynchronous method to change the name of an entry. NEWSUPER is a new
\&  parent (superior entry).  If set to NULL then only the RDN is changed.
\&  Set DELETE to non\-zero if you wish to remove the attribute values from the
\&  old name.  Returns a MSGID.
\&
\&  Example:
\&
\&    $msgid = $ld\->rename("cn=Clayton Donley, o=Motorola, c=US", \e
\&        "cn=Clay Donley", NULL, 0);
.Ve
.IP "rename_s \s-1DN NEWRDN NEWSUPER DELETE SCTRLS CCTRLS\s0" 4
.IX Item "rename_s DN NEWRDN NEWSUPER DELETE SCTRLS CCTRLS"
.Vb 4
\&  Synchronous method to change the name of an entry. NEWSUPER is a new
\&  parent (superior entry).  If set to NULL then only the RDN is changed.
\&  Set DELETE to non\-zero if you wish to remove the attribute values from the
\&  old name.  Returns a LDAP STATUS.
\&
\&  Example:
\&
\&    $status = $ld\->rename("cn=Clayton Donley, o=Motorola, c=US", \e
\&        "cn=Clay Donley", NULL, 0);
.Ve
.IP "result \s-1MSGID ALL TIMEOUT\s0" 4
.IX Item "result MSGID ALL TIMEOUT"
.Vb 5
\&  Retrieves the result of an operation initiated using an asynchronous LDAP
\&  call.  It calls internally ldap_result function.  Returns LDAP message or
\&  undef if error. Return value of ldap_result call stored in $ld\->{"status"}
\&  and is set \-1 if something wrong happened, 0 if specified timeout was
\&  exceeded or type of the returned message.
\&
\&  MSGID is the MSGID returned by the Asynchronous LDAP call.  Set ALL to
\&  0 to receive entries as they arrive, or non\-zero to receive all entries
\&  before returning.  Set TIMEOUT to the number of seconds to wait for the
\&  result, or \-1 for no timeout.
\&
\&  Example:
\&
\&    $entry = $ld\->result($msgid, 0, 1);
\&    print "msgtype = ".$ld\->msgtype2str($ld\->{"status"})."\en";
.Ve
.IP "result_entry" 4
.IX Item "result_entry"
.Vb 2
\&  This function is a shortcut for moving pointer along the chain of entries
\&  in the result. It is used instead of first_entry and next_entry functions.
\&
\&  Example
\&    while( $entry = $ld\->result_entry ) {
\&        print "dn = ".$ld\->get_dn($entry)."\en";
\&    }
.Ve
.IP "result_message" 4
.IX Item "result_message"
.Vb 2
\&  This function is a shortcut for moving pointer along the chain of messages
\&  in the result. It is used instead of first_message and next_message functions.
\&
\&  Example
\&    while( $msg = $ld\->result_message ) {
\&        $msgtype = $self\->msgtype($msg);
\&    }
.Ve
.IP "search \s-1BASE SCOPE FILTER ATTRS ATTRSONLY\s0" 4
.IX Item "search BASE SCOPE FILTER ATTRS ATTRSONLY"
.Vb 6
\&  Begins an asynchronous LDAP search.  Returns a MSGID or \-1 if an
\&  error occurs.  BASE is the base object for the search operation.
\&  FILTER is a string containing an LDAP search filter.  ATTRS is a
\&  reference to an array containing the attributes to return.  An
\&  empty array would return all attributes.  ATTRSONLY set to non\-zero
\&  will only obtain the attribute types without values.
\&
\&  SCOPE is one of the following:
\&        LDAP_SCOPE_BASE
\&        LDAP_SCOPE_ONELEVEL
\&        LDAP_SCOPE_SUBTREE
\&
\&  Example:
\&
\&    @attrs = ("cn","sn");    # Return specific attributes
\&    @attrs = ();             # Return all Attributes
\&
\&    $msgid = $ld\->search("o=Motorola, c=US", LDAP_SCOPE_SUBTREE, \e
\&        "(sn=Donley), \e@attrs, 0);
.Ve
.IP "search_s \s-1BASE SCOPE FILTER ATTRS ATTRSONLY\s0 (rewrite \s-1XXX\s0)" 4
.IX Item "search_s BASE SCOPE FILTER ATTRS ATTRSONLY (rewrite XXX)"
.Vb 6
\&  Performs a synchronous LDAP search.  Returns an LDAP STATUS.  BASE
\&  is the base object for the search operation.  FILTER is a string
\&  containing an LDAP search filter.  ATTRS is a reference to an array
\&  containing the attributes to return.  An empty array would return all
\&  attributes.  ATTRSONLY set to non\-zero will only obtain the attribute
\&  types without values.
\&
\&  SCOPE is one of the following:
\&        LDAP_SCOPE_BASE
\&        LDAP_SCOPE_ONELEVEL
\&        LDAP_SCOPE_SUBTREE
\&
\&  Example:
\&
\&    @attrs = ("cn","sn");    # Return specific attributes
\&    @attrs = ();             # Return all attributes
\&
\&    $status = $ld\->search_s("o=Motorola, c=US",LDAP_SCOPE_SUBTREE, \e
\&        "(sn=Donley)",\e@attrs,0);
.Ve
.IP "search_st \s-1BASE SCOPE FILTER ATTRS ATTRSONLY TIMEOUT\s0 (rewrite/remove \s-1XXX\s0)" 4
.IX Item "search_st BASE SCOPE FILTER ATTRS ATTRSONLY TIMEOUT (rewrite/remove XXX)"
.Vb 4
\&  Performs a synchronous LDAP search with a TIMEOUT.  See search_s
\&  for a description of parameters.  Returns an LDAP STATUS.  Results are
\&  put into RESULTS.  TIMEOUT is a number of seconds to wait before giving
\&  up, or \-1 for no timeout.
\&
\&  Example:
\&
\&    $status = $ld\->search_st("o=Motorola, c=US",LDAP_SCOPE_SUBTREE, \e
\&        "(sn=Donley),[],0,3);
.Ve
.IP "unbind \s-1SCTRLS CCTRLS\s0" 4
.IX Item "unbind SCTRLS CCTRLS"
.Vb 1
\&  Unbind LDAP connection with specified SESSION handler.
\&
\&  Example:
\&
\&    $ld\->unbind;
.Ve
.IP "url_parse \s-1URL\s0" 4
.IX Item "url_parse URL"
.Vb 2
\&  Parses an LDAP URL into separate components.  Returns a HASH reference
\&  with the following keys, if they exist in the URL:
\&
\&  host      \- LDAP Host
\&  port      \- LDAP Port
\&  dn        \- LDAP Base DN
\&  attr      \- LDAP Attributes to Return (ARRAY Reference)
\&  filter    \- LDAP Search Filter
\&  scope     \- LDAP Search Scope
\&  options   \- Mozilla key specifying LDAP over SSL
\&
\&  Example:
\&
\&    $urlref = $ld\->url_parse("ldap://ldap.my.org/o=My,c=US");
.Ve
.IP "url_search \s-1URL ATTRSONLY\s0" 4
.IX Item "url_search URL ATTRSONLY"
.Vb 5
\&  Perform an asynchronous search using an LDAP URL.  URL is the LDAP
\&  URL to search on.  ATTRSONLY determines whether we are returning
\&  the values for each attribute (0) or only returning the attribute
\&  names (1).  Results are retrieved and parsed identically to a call
\&  to the search method.
\&
\&  Returns a non\-negative MSGID upon success.
\&
\&  Example:
\&
\&    $msgid = $ld\->url_search($my_ldap_url, 0);
.Ve
.IP "url_search_s \s-1URL ATTRSONLY\s0" 4
.IX Item "url_search_s URL ATTRSONLY"
.Vb 2
\&  Synchronous version of the url_search method.  Results are retrieved
\&  and parsed identically to a call to the search_s method.
\&
\&  Returns LDAP_SUCCESS upon success.
\&
\&  Example:
\&
\&    $status = $ld\->url_search_s($my_ldap_url, 0);
.Ve
.IP "url_search_st \s-1URL ATTRSONLY TIMEOUT\s0" 4
.IX Item "url_search_st URL ATTRSONLY TIMEOUT"
.Vb 4
\&  Similar to the url_search_s method, except that it allows a timeout
\&  to be specified.  The timeout is specified as seconds.  A timeout of
\&  0 specifies an unlimited timeout.  Results are retrieved and parsed
\&  identically to a call to the search_st method.
\&
\&  Returns LDAP_SUCCESS upon success.
\&
\&  Example:
\&
\&    $status = $ld\->url_search_s($my_ldap_url,0,2);
.Ve
.IP "whoami \s-1SCTRLS CCTRLS\s0" 4
.IX Item "whoami SCTRLS CCTRLS"
.Vb 1
\&  Asynchronous method for invoking an LDAP whoami extended operation. 
\&
\&  Returns a non\-negative MSGID upon success.
\&      
\&  Examples:
\&  
\&    $msgid = $ld\->whoami();
.Ve
.IP "whoami_s \s-1AUTHZID SCTRLS CCTRLS\s0" 4
.IX Item "whoami_s AUTHZID SCTRLS CCTRLS"
.Vb 1
\&  Synchronous method for invoking an LDAP whoami extended operation.
\&  
\&  Returns LDAP_SUCCESS upon success.
\&    
\&  Examples:
\&  
\&    $status = $ld\->whoami_s(\e$authzid);
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Clayton Donley, donley@wwa.com
http://miso.wwa.com/~donley/
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBperl\fR\|(1).