.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29)
.\"
.\" 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 turned on, 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
.\"
.\" 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 "CGI::Session::Driver 3pm"
.TH CGI::Session::Driver 3pm "2016-01-15" "perl v5.22.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"
CGI::Session::Driver \- CGI::Session driver specifications
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    require CGI::Session::Driver;
\&    @ISA = qw( CGI::Session::Driver );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
CGI::Session::Driver is a base class for all CGI::Session's native drivers. It also documents driver specifications for those willing to write drivers for different databases not currently supported by CGI::Session.
.SH "WHAT IS A DRIVER"
.IX Header "WHAT IS A DRIVER"
Driver is a piece of code that helps CGI::Session library to talk to specific database engines, or storage mechanisms. To be more precise, driver is a \fI.pm\fR file that inherits from CGI::Session::Driver and defines \fIretrieve()\fR, \fIstore()\fR and \fIremove()\fR methods.
.SS "\s-1BLUEPRINT\s0"
.IX Subsection "BLUEPRINT"
The best way of learning the specs is to look at a blueprint of a driver:
.PP
.Vb 3
\&    package CGI::Session::Driver::your_driver_name;
\&    use strict;
\&    use base qw( CGI::Session::Driver CGI::Session::ErrorHandler );
\&
\&    sub init {
\&        my ($self) = @_;
\&        # optional
\&    }
\&
\&    sub DESTROY {
\&        my ($self) = @_;
\&        # optional
\&    }
\&
\&    sub store {
\&        my ($self, $sid, $datastr) = @_;
\&        # Store $datastr, which is an already serialized string of data.
\&    }
\&
\&    sub retrieve {
\&        my ($self, $sid) = @_;
\&        # Return $datastr, which was previously stored using above store() method.
\&        # Return $datastr if $sid was found. Return 0 or "" if $sid doesn\*(Aqt exist
\&        }
\&
\&    sub remove {
\&        my ($self, $sid) = @_;
\&        # Remove storage associated with $sid. Return any true value indicating success,
\&        # or undef on failure.
\&    }
\&
\&    sub traverse {
\&        my ($self, $coderef) = @_;
\&        # execute $coderef for each session id passing session id as the first and the only
\&        # argument
\&    }
\&
\&    1;
.Ve
.PP
All the attributes passed as the second argument to CGI::Session's \fInew()\fR or \fIload()\fR methods will automatically
be made driver's object attributes. For example, if session object was initialized as following:
.PP
.Vb 1
\&    $s = CGI::Session\->new("driver:your_driver_name", undef, {Directory=>\*(Aq/tmp/sessions\*(Aq});
.Ve
.PP
You can access value of 'Directory' from within your driver like so:
.PP
.Vb 4
\&    sub store {
\&        my ($self, $sid, $datastr) = @_;
\&        my $dir = $self\->{Directory};   # <\-\- in this example will be \*(Aq/tmp/sessions\*(Aq
\&    }
.Ve
.PP
Optionally, you can define \f(CW\*(C`init()\*(C'\fR method within your driver to do driver specific global initialization. \f(CW\*(C`init()\*(C'\fR method will be invoked only once during the lifecycle of your driver, which is the same as the lifecycle of a session object.
.PP
For examples of \f(CW\*(C`init()\*(C'\fR look into the source code of native CGI::Session drivers.
.SH "METHODS"
.IX Header "METHODS"
This section lists and describes all driver methods. All the driver methods will receive driver object ($self) as the first argument. Methods that pertain to an individual session (such as \f(CW\*(C`retrieve()\*(C'\fR, \f(CW\*(C`store()\*(C'\fR and \f(CW\*(C`remove()\*(C'\fR) will also receive session id ($sid) as the second argument.
.PP
Following list describes every driver method, including its argument list and what step of session's life they will be invoked. Understanding this may help driver authors.
.ie n .IP "retrieve($self, $sid)" 4
.el .IP "retrieve($self, \f(CW$sid\fR)" 4
.IX Item "retrieve($self, $sid)"
Called whenever a specific session is requested either via \f(CW\*(C`CGI::Session\->new()\*(C'\fR or \f(CW\*(C`CGI::Session\->load()\*(C'\fR syntax. Method should try to retrieve data associated with \f(CW $sid \fR and return it. In case no data could be retrieved for \f(CW $sid \fR 0 (zero) or "" should be returned. undef must be returned only to signal error. Error message should be set via \fIset_error()\fR, which can be inherited from CGI::Session::ErrorHandler.
.Sp
Tip: \fIset_error()\fR always returns undef. Use it for your advantage.
.ie n .IP "store($self, $sid, $datastr)" 4
.el .IP "store($self, \f(CW$sid\fR, \f(CW$datastr\fR)" 4
.IX Item "store($self, $sid, $datastr)"
Called whenever modified session data is to be stored back to disk. This happens whenever CGI::Session\->\fIflush()\fR is called on modified session. Since CGI::Session\->\s-1\fIDESTROY\s0()\fR calls \fIflush()\fR, \fIstore()\fR gets requested each time session object is to be terminated.
.Sp
\&\f(CW\*(C` store() \*(C'\fR is called both to store new sessions and to update already stored sessions. It's driver author's job to figure out which operation needs to be performed.
.Sp
\&\f(CW$datastr\fR, which is passed as the third argument to represents \fBalready serialized\fR session data that needs to be saved.
.Sp
\&\fIstore()\fR can return any true value indicating success or undef on failure. Error message should be passed to \fIset_error()\fR
.ie n .IP "remove($self, $sid)" 4
.el .IP "remove($self, \f(CW$sid\fR)" 4
.IX Item "remove($self, $sid)"
Called whenever session data is to be deleted, which is when CGI::Session\->\fIdelete()\fR is called. Should return any true value indicating success, undef on failure. Error message should be logged in \fIset_error()\fR.
.IP "traverse($self, \e&coderef)" 4
.IX Item "traverse($self, &coderef)"
Called only from within CGI::Session\->\fIfind()\fR. Job of \fItraverse()\fR is to call \e&coderef for every single session stored in disk passing session's id as the first and only argument: \f(CW\*(C`$coderef\->( $sid )\*(C'\fR
.IP "init($self)" 4
.IX Item "init($self)"
Optional. Called whenever driver object is to be initialized, which happens only once during the lifecycle of CGI::Session object. Here you can do driver-wide initialization, such as to open connection to a database server.
.IP "\s-1DESTROY\s0($self)" 4
.IX Item "DESTROY($self)"
Optional. Perl automatically calls this method on objects just before they are to be terminated. This gives your driver chance to close any database connections or close any open file handles.
.SS "\s-1NOTES\s0"
.IX Subsection "NOTES"
.IP "\(bu" 4
All driver \fI.pm\fR files must be lowercase!
.IP "\(bu" 4
DBI-related drivers are better off using CGI::Session::Driver::DBI as base, but don't have to.
.SH "BACKWARDS COMPATIBILITY"
.IX Header "BACKWARDS COMPATIBILITY"
Version 4.0 of CGI::Session's driver specification is \fB\s-1NOT\s0\fR backward
compatible with the previous specification. If you already have a driver
developed to work with the previous version you're highly encouraged to upgrade
your driver code to make it compatible with the current version. Fortunately,
current driver specs are a lot easier to adapt to.
.PP
For support information see CGI::Session
.SH "LICENSING"
.IX Header "LICENSING"
For support and licensing see CGI::Session.