.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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 "Net::LDAP::Examples 3"
.TH Net::LDAP::Examples 3 2024-09-01 "perl v5.40.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::LDAP::Examples \- PERL LDAP by Example
.SH DESCRIPTION
.IX Header "DESCRIPTION"
The following examples are of course PERL code, found to work
with the Net::LDAP modules.
.PP
The intent of this document is to give the reader a \fIcut and paste\fR
jump start to getting an LDAP application working.
.PP
Below you will find snippets of code that should work as-is with only
a small amount of work to correct any variable assignments and LDAP
specifics, e.g. Distinguished Name Syntax, related to the user's
own implementation.
.PP
The \fIS\fRtandard \fIO\fRperating \fIP\fRrocedure that is followed here is:
.IP "1 Package		\- use Net::LDAP" 8
.IX Item "1 Package - use Net::LDAP"
.PD 0
.IP "2 Initialization	\- new" 8
.IX Item "2 Initialization - new"
.IP "3 Binding		\- bind" 8
.IX Item "3 Binding - bind"
.IP "4 Operation	\- add modify moddn search" 8
.IX Item "4 Operation - add modify moddn search"
.IP "4.1 Processing	\- displaying data from a search" 8
.IX Item "4.1 Processing - displaying data from a search"
.IP "5 Error		\- displaying error information" 8
.IX Item "5 Error - displaying error information"
.IP "6 Unbinding	\- unbind" 8
.IX Item "6 Unbinding - unbind"
.PD
.PP
Look to each of these for a snippet of code to meet your needs.
.PP
\&\fBWhat is not covered in these examples at this time:\fR
.IP "\fIabandon\fR and \fIcompare\fR methods" 4
.IX Item "abandon and compare methods"
.PD 0
.IP "\fIcallback\fR subroutines" 4
.IX Item "callback subroutines"
.PD
.SH CODE
.IX Header "CODE"
.SS "PACKAGE \- Definitions"
.IX Subsection "PACKAGE - Definitions"
.Vb 1
\& use Net::LDAP;
.Ve
.SS INITIALIZING
.IX Subsection "INITIALIZING"
.Vb 1
\& $ldap = Net::LDAP\->new ( "yourLDAPhost.yourCompany.com" ) or die "$@";
.Ve
.SS BINDING
.IX Subsection "BINDING"
.Vb 1
\& $mesg = $ldap\->bind ( version => 3 );          # use for searches
\&
\& $mesg = $ldap\->bind ( "$userToAuthenticate",
\&                       password => "$passwd",
\&                       version => 3 );          # use for changes/edits
\&
\& # see your LDAP administrator for information concerning the
\& # user authentication setup at your site.
.Ve
.SS "OPERATION \- Generating a SEARCH"
.IX Subsection "OPERATION - Generating a SEARCH"
.Vb 3
\& sub LDAPsearch
\& {
\&   my ($ldap,$searchString,$attrs,$base) = @_;
\&
\&   # if they don\*(Aqt pass a base... set it for them
\&
\&   if (!$base ) { $base = "o=mycompany, c=mycountry"; }
\&
\&   # if they don\*(Aqt pass an array of attributes...
\&   # set up something for them
\&
\&   if (!$attrs ) { $attrs = [ \*(Aqcn\*(Aq,\*(Aqmail\*(Aq ]; }
\&
\&   my $result = $ldap\->search ( base    => "$base",
\&                                scope   => "sub",
\&                                filter  => "$searchString",
\&                                attrs   =>  $attrs
\&                              );
.Ve
.PP
}
.PP
.Vb 2
\& my @Attrs = ( );               # request all available attributes
\&                                # to be returned.
\&
\& my $result = LDAPsearch ( $ldap, "sn=*", \e@Attrs );
.Ve
.SS "PROCESSING \- Displaying SEARCH Results"
.IX Subsection "PROCESSING - Displaying SEARCH Results"
.Vb 5
\& #\-\-\-\-\-\-\-\-\-\-\-\-
\& #
\& # Accessing the data as if in a structure
\& #  i.e. Using the "as_struct"  method
\& #
\&
\& my $href = $result\->as_struct;
\&
\& # get an array of the DN names
\&
\& my @arrayOfDNs  = keys %$href;        # use DN hashes
\&
\& # process each DN using it as a key
\&
\& foreach ( @arrayOfDNs ) {
\&   print $_, "\en";
\&   my $valref = $$href{$_};
\&
\&   # get an array of the attribute names
\&   # passed for this one DN.
\&   my @arrayOfAttrs = sort keys %$valref; #use Attr hashes
\&
\&   my $attrName;
\&   foreach $attrName (@arrayOfAttrs) {
\&
\&     # skip any binary data: yuck!
\&     next if ( $attrName =~ /;binary$/ );
\&
\&     # get the attribute value (pointer) using the
\&     # attribute name as the hash
\&     my $attrVal =  @$valref{$attrName};
\&     print "\et $attrName: @$attrVal \en";
\&   }
\&   print "#\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\en";
\&   # End of that DN
\& }
\& #
\& #  end of as_struct method
\& #
\& #\-\-\-\-\-\-\-\-
\&
\&
\& #\-\-\-\-\-\-\-\-\-\-\-\-
\& #
\& # handle each of the results independently
\& # ... i.e. using the walk through method
\& #
\& my @entries = $result\->entries;
\&
\& my $entr;
\& foreach $entr ( @entries ) {
\&   print "DN: ", $entr\->dn, "\en";
\&
\&   my $attr;
\&   foreach $attr ( sort $entr\->attributes ) {
\&     # skip binary we can\*(Aqt handle
\&     next if ( $attr =~ /;binary$/ );
\&     print "  $attr : ", $entr\->get_value ( $attr ) ,"\en";
\&   }
\&
\&   print "#\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\en";
\& }
\&
\& #
\& # end of walk through method
\& #\-\-\-\-\-\-\-\-\-\-\-\-
.Ve
.SS "OPERATION \- Modifying entries"
.IX Subsection "OPERATION - Modifying entries"
.Vb 10
\& #
\& #   Modify
\& #
\& #  for each of the modifies below you\*(Aqll need to supply
\& #  a full DN (Distinguished Name) for the $dn variable.
\& #   example:
\& #    cn=Jo User,ou=person,o=mycompany,c=mycountry
\& #
\& #   I would recommend doing a search (listed above)
\& #   then use the dn returned to populate the $dn variable.
\&
\& #
\& #  Do we only have one result returned from the search?
\&
\& if ( $result\->count != 1 ) { exit; }  # Nope.. exit
\&
\& my $dn = $entries[0]\->dn;         # yes.. get the DN
\&
\& #######################################
\& #
\& #   MODIFY using a HASH
\& #
\&
\& my %ReplaceHash = ( keyword => "x", proxy => "x" );
\&
\& my $result = LDAPmodifyUsingHash ( $ldap, $dn, \e%ReplaceHash );
\&
\& sub LDAPmodifyUsingHash
\& {
\&   my ($ldap, $dn, $whatToChange ) = @_;
\&   my $result = $ldap\->modify ( $dn,
\&                                replace => { %$whatToChange }
\&                              );
\&   return $result;
\& }
\&
\& #######################################
\& #
\& #   MODIFY using a ARRAY List
\& #
\&
\& my @ReplaceArrayList = [ \*(Aqkeyword\*(Aq, "xxxxxxxxxx",
\&                          \*(Aqproxy\*(Aq , "yyyyyyyyyy"   ];
\&
\& my $result = LDAPmodifyUsingArrayList ( $ldap, $dn, \e@ReplaceArrayList );
\&
\& sub LDAPmodifyUsingArrayList
\& {
\&   my ($ldap, $dn, $whatToChange ) = @_;
\&   my $result = $ldap\->modify ( $dn,
\&                                changes => [
\&                                  replace => @$whatToChange
\&                                ]
\&                              );
\&   return $result;
\& }
\&
\& #######################################
\& #
\& #   MODIFY using a ARRAY
\& #
\&
\& my @ReplaceArray = ( \*(Aqkeyword\*(Aq, "xxxxxxxxxx" ,
\&                      \*(Aqproxy\*(Aq , "yyyyyyyyyy"   );
\&
\& my $result = LDAPmodifyUsingArray ( $ldap, $dn, \e@ReplaceArray );
\&
\& sub LDAPmodifyUsingArray
\& {
\&   my ($ldap, $dn, $whatToChange ) = @_;
\&   my $result = $ldap\->modify ( $dn,
\&                                changes => [
\&                                  replace => [ @$whatToChange ]
\&                                ]
\&                              );
\&   return $result;
\& }
\&
\& #######################################
\& #
\& #   MODIFY an existing record using \*(AqChanges\*(Aq
\& #    (or combination of add/delete/replace)
\& #
\&
\& my @whatToChange;
\& my @ReplaceArray;
\& my @DeleteArray;
\& my @AddArray;
\&
\& push @AddArray, \*(Aqcn\*(Aq, "me myself";
\& push @ReplaceArray, \*(Aqsn\*(Aq, \*(Aq!@#$%^&*()_\|_+Hello There\*(Aq;
\& push @ReplaceArray, \*(Aqcn\*(Aq, "me myself I";
\& push @DeleteArray, \*(Aqcn\*(Aq, "me myself";
\&
\& if ( $#ReplaceArray > 0 ) {
\&   push @whatToChange, \*(Aqreplace\*(Aq;
\&   push @whatToChange, \e@ReplaceArray;
\& }
\& if ( $#DeleteArray > 0 ) {
\&   push @whatToChange, \*(Aqdelete\*(Aq;
\&   push @whatToChange, \e@DeleteArray;
\& }
\& if ( $#AddArray > 0 ) {
\&   push @whatToChange, \*(Aqadd\*(Aq;
\&   push @whatToChange, \e@AddArray;
\& }
\&
\& $result = LDAPmodify ( $ldap, $dn, \e@whatToChange );
\&
\& sub LDAPmodify
\& {
\&   my ($ldap, $dn, $whatToChange) = @_;
\&
\&   my $result = $ldap\->modify ( $dn,
\&                                changes => [
\&                                  @$whatToChange
\&                                ]
\&                              );
\&   return $result;
\& }
.Ve
.SS "OPERATION \- Changing the RDN"
.IX Subsection "OPERATION - Changing the RDN"
.Vb 1
\& my $newRDN = "cn=Joseph User";
\&
\& my $result = LDAPrdnChange ( $ldap, $dn, $newRDN, "archive" );
\&
\&
\& sub LDAPrdnChange
\& {
\&   my ($ldap,$dn,$whatToChange,$action) = @_;
\&
\&   my $branch;
\&
\&   #
\&   # if the archive action is selected, move this
\&   # entry to another place in the directory.
\&   #
\&   if ( $action =~ /archive/i )  {
\&     $branch = "ou=newbranch, o=mycompany, c=mycountry";
\&   }
\&
\&   #
\&   # use the \*(Aqdeleteoldrdn\*(Aq to keep from getting
\&   # multivalues in the NAMING attribute.
\&   # in most cases that would be the \*(AqCN\*(Aq attribute
\&   #
\&   my $result = $ldap\->moddn ( $dn,
\&                               newrdn => $whatToChange,
\&                               deleteoldrdn => \*(Aq1\*(Aq,
\&                               newsuperior => $branch
\&                             );
\&
\&   return $result;
\&
\& }
.Ve
.SS "OPERATION \- Adding a new Record"
.IX Subsection "OPERATION - Adding a new Record"
.Vb 1
\& my $DNbranch = "ou=bailiwick, o=mycompany, c=mycountry";
\&
\& #
\& # check with your Directory Schema or Administrator
\& # for the correct objectClass... I\*(Aqm sure it\*(Aqll be different
\& #
\& my $CreateArray = [
\&   objectClass => [ "top", "person", "organizationalPerson", "inetOrgPerson" ],
\&   cn => "Jane User",
\&   uid => "0000001",
\&   sn => "User",
\&   mail => \*(AqJaneUser@mycompany.com\*(Aq
\& ];
\&
\& #
\& # create the  new DN to look like this
\& # " cn=Jo User + uid=0000001 , ou=bailiwick, o=mycompany, c=mycountry "
\& #
\& # NOTE: this DN  MUST be changed to meet your implementation
\& #
\&
\& my $NewDN = "@$CreateArray[2]=".
\&             "@$CreateArray[3]+".
\&             "@$CreateArray[4]=".
\&             "@$CreateArray[5],".
\&             $DNbranch;
\&
\& LDAPentryCreate($ldap, $NewDN, $CreateArray);
\&
\& #
\& # CreateArray is a reference to an anonymous array
\& # you have to dereference it in the  subroutine it\*(Aqs
\& # passed to.
\& #
\&
\& sub LDAPentryCreate
\& {
\&    my ($ldap, $dn, $whatToCreate) = @_;
\&    my $result = $ldap\->add ( $dn, attrs => [ @$whatToCreate ] );
\&    return $result;
\& }
.Ve
.SS "ERROR \- Retrieving and Displaying ERROR information"
.IX Subsection "ERROR - Retrieving and Displaying ERROR information"
.Vb 6
\& if ( $result\->code ) {
\&   #
\&   # if we\*(Aqve got an error... record it
\&   #
\&   LDAPerror ( "Searching", $result );
\& }
\&
\& sub LDAPerror
\& {
\&   my ($from, $mesg) = @_;
\&   print "Return code: ", $mesg\->code;
\&   print "\etMessage: ", $mesg\->error_name;
\&   print " :",          $mesg\->error_text;
\&   print "MessageID: ", $mesg\->mesg_id;
\&   print "\etDN: ", $mesg\->dn;
\&
\&   #\-\-\-
\&   # Programmer note:
\&   #
\&   #  "$mesg\->error" DOESN\*(AqT work!!!
\&   #
\&   #print "\etMessage: ", $mesg\->error;
\&   #\-\-\-\-\-
\& }
.Ve
.SS UNBIND
.IX Subsection "UNBIND"
.Vb 1
\& $ldap\->unbind;
.Ve
.SH "LDAP SCHEMA RETRIEVAL"
.IX Header "LDAP SCHEMA RETRIEVAL"
The following code snippet shows how to retrieve schema information.
.PP
The first procedure is to initialize a new LDAP object using the
same procedures as listed at the beginning of this document.
.PP
The second procedure is to bind to your directory server.  Some
servers may require authentication to retrieve the schema from the
directory server.  This procedure is listed at the beginning of
this document too.
.PP
After a successful bind you are ready to retrieve the schema
information.  You do this by initializing a schema object.
.PP
.Vb 1
\& $schema = $ldap\->schema ( );
.Ve
.PP
In this case Net::LDAP will attempt to determine the dn under which
the schema can be found. First it will look for the attribute
\&\f(CW\*(C`subschemaSubentry\*(C'\fR in the root DSE. If that cannot be found then
it will default to the assumption of \f(CW\*(C`cn=schema\*(C'\fR
.PP
Alternatively you can specify the dn where the schema is to be found
with
.PP
.Vb 1
\& $schema = $ldap\->schema ( dn => $dn );
.Ve
.PP
Once we have a dn to search for, Net::LDAP will fetch the schema entry with
.PP
.Vb 4
\&  $mesg = $self\->search ( base   => $dn,
\&                          scope  => \*(Aqbase\*(Aq,
\&                          filter => \*(Aq(objectClass=subschema)\*(Aq,
\&                        );
.Ve
.PP
Once the schema object has been initialized, schema methods
are used to retrieve the data.  There are a number of ways this
can be done.  Information on the schema methods can be found
in the Net::LDAP::Schema pod documentation.
.PP
The following is a code snippet showing how to get and display
information about returned attributes.
.PP
.Vb 3
\& #
\& # Get the attributes
\& #
\&
\& @attributes = $schema\->all_attributes ( );
\&
\& #
\& # Display the attributes
\& #
\&
\& foreach $ar ( @attributes ) {
\&   print "attributeType: ", $ar\->{name}, "\en";
\&
\&   #
\&   # Print all the details
\&   #
\&
\&   foreach $key ( keys %{$ar} ) {
\&     print join ( "\en\et\et", "\et$key:",
\&                  ref ( $ar\->{$key} ) ? @{$ar\->{$key}} : $ar\->{$key}
\&                ), "\en";
\&   }
\& }
.Ve
.PP
The process is the basically the same for getting objectClass
information.  Where schema\->\fBall_attributes()\fR is used, substitute
schema\->\fBall_objectclasses()\fR.  From that point on the process is
the same for both objectClasses and attributes.
.SH BUGS
.IX Header "BUGS"
None known, but there may be some
.SH "AUTHOR  (of this document)"
.IX Header "AUTHOR (of this document)"
Russell Biggs <rgb@ticnet.com>
.SH COPYRIGHT
.IX Header "COPYRIGHT"
All rights to this document are hereby relinquished to Graham Barr.