.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.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" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Net::LDAP::Server 3pm"
.TH Net::LDAP::Server 3pm "2007-10-27" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
Net::LDAP::Server \- LDAP server side protocol handling
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 15
\&  package MyServer;
\&  use Net::LDAP::Server;
\&  use Net::LDAP::Constant qw(LDAP_SUCCESS);
\&  use base \(aqNet::LDAP::Server\(aq;
\&  sub search {
\&      my $self = shift;
\&      my ($reqData, $fullRequest) = @_;
\&      print "Searching\en";
\&      ...
\&      return {
\&          \(aqmatchedDN\(aq => \(aq\(aq,
\&          \(aqerrorMessage\(aq => \(aq\(aq,
\&          \(aqresultCode\(aq => LDAP_SUCCESS
\&      }, @entries;
\&  }
.Ve
.PP
.Vb 3
\&  package main;
\&  my $handler = MyServer\->new($socket);
\&  $handler\->handle;
.Ve
.SH "ABSTRACT"
.IX Header "ABSTRACT"
This class provides the protocol handling for an \s-1LDAP\s0 server. You can subclass
it and implement the methods you need (see below). Then you just instantiate 
your subclass and call its \f(CW\*(C`handle\*(C'\fR method to establish a connection with the client.
.SH "SUBCLASSING"
.IX Header "SUBCLASSING"
You can subclass Net::LDAP::Server with the following lines:
.PP
.Vb 3
\&  package MyServer;
\&  use Net::LDAP::Server;
\&  use base \(aqNet::LDAP::Server\(aq;
.Ve
.PP
Then you can add your custom methods by just implementing a subroutine
named after the name of each method. These are supported methods:
.ie n .IP """bind""" 4
.el .IP "\f(CWbind\fR" 4
.IX Item "bind"
.PD 0
.ie n .IP """unbind""" 4
.el .IP "\f(CWunbind\fR" 4
.IX Item "unbind"
.ie n .IP """search""" 4
.el .IP "\f(CWsearch\fR" 4
.IX Item "search"
.ie n .IP """add""" 4
.el .IP "\f(CWadd\fR" 4
.IX Item "add"
.ie n .IP """modify""" 4
.el .IP "\f(CWmodify\fR" 4
.IX Item "modify"
.ie n .IP """delete""" 4
.el .IP "\f(CWdelete\fR" 4
.IX Item "delete"
.ie n .IP """modifyDN""" 4
.el .IP "\f(CWmodifyDN\fR" 4
.IX Item "modifyDN"
.ie n .IP """compare""" 4
.el .IP "\f(CWcompare\fR" 4
.IX Item "compare"
.ie n .IP """abandon""" 4
.el .IP "\f(CWabandon\fR" 4
.IX Item "abandon"
.PD
.PP
For any method that is not supplied, Net::LDAP::Server will return an 
\&\f(CW\*(C`LDAP_UNWILLING_TO_PERFORM\*(C'\fR.
.Sh "\fInew()\fP"
.IX Subsection "new()"
You can also subclass the \f(CW\*(C`new\*(C'\fR constructor to do something at connection time:
.PP
.Vb 6
\&  sub new {
\&     my ($class, $sock) = @_;
\&     my $self = $class\->SUPER::new($sock);
\&     printf "Accepted connection from: %s\en", $sock\->peerhost();
\&     return $self;
\&  }
.Ve
.PP
Note that \f(CW$self\fR is constructed using the fields pragma, so if you want to add
data to it you should add a line like this in your subclass:
.PP
.Vb 1
\&  use fields qw(myCustomField1 myCustomField2);
.Ve
.Sh "Methods"
.IX Subsection "Methods"
When a method is invoked it will be obviously passed \f(CW$self\fR as generated by 
\&\f(CW\*(C`new\*(C'\fR, and two variables:
.IP "* the Request datastructure that is specific for this method (e.g. BindRequest);" 4
.IX Item "the Request datastructure that is specific for this method (e.g. BindRequest);"
.PD 0
.IP "* the full request message (useful if you want to access \fImessageID\fR or \fIcontrols\fR parts)" 4
.IX Item "the full request message (useful if you want to access messageID or controls parts)"
.PD
.PP
You can look at Net::LDAP::ASN or use Data::Dumper to find out what is 
presented to your method:
.PP
.Vb 4
\&  use Data::Dumper;
\&  sub search {
\&     print Dumper \e@_;
\&  }
.Ve
.PP
If anything goes wrong in the module you specify (e.g. it died or the result 
is not a correct ldapresult structure) Net::LDAP::Server will return an 
\&\f(CW\*(C`LDAP_OPERATIONS_ERROR\*(C'\fR where the errorMessage will specify what went 
wrong. 
.PP
All methods should return a LDAPresult hashref, for example:
.PP
.Vb 5
\&  return({
\&      \(aqmatchedDN\(aq => \(aq\(aq,
\&      \(aqerrorMessage\(aq => \(aq\(aq,
\&      \(aqresultCode\(aq => LDAP_SUCCESS
\&  });
.Ve
.PP
\&\f(CW\*(C`search\*(C'\fR should return a LDAPresult hashref followed by a list of entries 
(if applicable). Entries may be coded either as searchResEntry or 
searchRefEntry structures or as Net::LDAP::Entry or Net::LDAP::Reference
objects.
.SH "CLIENT HANDLING"
.IX Header "CLIENT HANDLING"
.Sh "\fIhandle()\fP"
.IX Subsection "handle()"
When you get a socket from a client you can instantiate the class and handle 
the request:
.PP
.Vb 2
\&  my $handler = MyServer\->new($socket);
\&  $handler\->handle;
.Ve
.PP
See examples in \fIexamples/\fR directory for sample servers, using IO::Select 
or Net::Daemon.
.SH "DEPENDENCIES"
.IX Header "DEPENDENCIES"
.Vb 2
\& Net::LDAP::ASN
\& Net::LDAP::Constant
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "Net::LDAP" 4
.IX Item "Net::LDAP"
.PD 0
.IP "Examples in \fIexamples\fR directory." 4
.IX Item "Examples in examples directory."
.PD
.SH "BUGS AND FEEDBACK"
.IX Header "BUGS AND FEEDBACK"
There are no known bugs. You are very welcome to write mail to the maintainer 
(aar@cpan.org) with your contributions, comments, suggestions, bug reports 
or complaints.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
.SH "AUTHOR"
.IX Header "AUTHOR"
Alessandro Ranellucci <aar@cpan.org>
The original author of a Net::LDAP::Daemon module is 
Hans Klunder <hans.klunder@bigfoot.com>