apache2::cookie.3

视频监控网络部分的协议ddns,的模块的实现代码,请大家大胆指正.

.\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.05)
.\"
.\" 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\}
.\"
.\" 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 (.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.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" 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 "Apache2::Cookie 3"
.TH Apache2::Cookie 3 "2006-08-09" "perl v5.10.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"
Apache2::Cookie, Apache2::Cookie::Jar \- HTTP Cookies Class
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Apache2::Cookie;
\&
\&    $j = Apache2::Cookie::Jar\->new($r);
\&    $c_in = $j\->cookies("foo");         # get cookie from request headers
\&
\&    $c_out = Apache2::Cookie\->new($r,
\&                                  \-name  => "mycookie",
\&                                  \-value => $c_in\->name );
\&
\&    $c_out\->path("/bar");               # set path to "/bar"
\&    $c_out\->bake;                       # send cookie in response headers
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The Apache2::Cookie module is based on the original 1.X versions, which mimic
the CGI::Cookie \s-1API\s0.  The current version of this module includes several packages
and methods which are patterned after Apache2::Request, yet remain largely
backwards-compatible with the original 1.X \s-1API\s0 (see the \*(L"\s-1PORTING\s0 from 1.X\*(R" section
below for known issues).
.PP
This manpage documents the Apache2::Cookie and Apache2::Cookie::Jar packages.
.SH "Apache2::Cookie::Jar"
.IX Header "Apache2::Cookie::Jar"
This class collects Apache2::Cookie objects into a lookup table.  It plays
the same role for accessing the incoming cookies as Apache2::Request does for
accessing the incoming params and file uploads.
.Sh "new"
.IX Subsection "new"
.Vb 1
\&    Apache2::Cookie::Jar\->new($env)
.Ve
.PP
Class method that retrieves the parsed cookie jar from the current
environment.
.Sh "cookies"
.IX Subsection "cookies"
.Vb 2
\&    $jar\->cookies()
\&    $jar\->cookies($key)
.Ve
.PP
Retrieve cookies named \f(CW$key\fR with from the jar object.  In scalar
context the first such cookie is returned, and in list context the
full list of such cookies are returned.
.PP
If the \f(CW$key\fR argument is omitted, \f(CW\*(C`scalar $jar\->cookies()\*(C'\fR will
return an APR::Request::Cookie::Table object containing all the cookies in
the jar.  Modifications to the this object will affect the jar's
internal \fIcookies\fR table in \f(CW\*(C`apreq_jar_t\*(C'\fR, so their impact will
be noticed by all libapreq2 applications during this request.
.PP
In list context \f(CW\*(C`$jar\->cookies()\*(C'\fR returns the list of names
for all the cookies in the jar.  The order corresponds to the
order in which the cookies appeared in the incoming \*(L"Cookie\*(R" header.
.PP
This method will throw an \f(CW\*(C`APR::Request::Error\*(C'\fR object into $@ if
the returned value(s) could be unreliable.  In particular, note that
\&\f(CW\*(C`scalar $jar\->cookies("foo")\*(C'\fR will not croak if it can locate
the a \*(L"foo\*(R" cookie within the jar's parsed cookie table, even if the
cookie parser has failed (the cookies are parsed in the same order
as they appeared in the \*(L"Cookie\*(R" header). In all other circumstances
\&\f(CW\*(C`cookies\*(C'\fR will croak if the parser failed to successfully parse the
\&\*(L"Cookie\*(R" header.
.PP
.Vb 2
\&    $c = Apache2::Cookie\->new($r, name => "foo", value => 3);
\&    $j\->cookies\->add($c);
\&
\&    $cookie = $j\->cookies("foo");  # first foo cookie
\&    @cookies = $j\->cookies("foo"); # all foo cookies
\&    @names = $j\->cookies();        # all cookie names
.Ve
.Sh "status"
.IX Subsection "status"
.Vb 1
\&    $jar\->status()
.Ve
.PP
Get the \fI\s-1APR\s0\fR status code of the cookie parser:
\&\s-1APR_SUCCESS\s0 on success, error otherwise.
.SH "Apache2::Cookie"
.IX Header "Apache2::Cookie"
.Sh "new"
.IX Subsection "new"
.Vb 1
\&    Apache2::Cookie\->new($env, %args)
.Ve
.PP
Just like CGI::Cookie::new, but requires an additional environment argument:
.PP
.Vb 8
\&    $cookie = Apache2::Cookie\->new($r,
\&                             \-name    =>  \*(Aqfoo\*(Aq,
\&                             \-value   =>  \*(Aqbar\*(Aq,
\&                             \-expires =>  \*(Aq+3M\*(Aq,
\&                             \-domain  =>  \*(Aq.capricorn.com\*(Aq,
\&                             \-path    =>  \*(Aq/cgi\-bin/database\*(Aq,
\&                             \-secure  =>  1
\&                            );
.Ve
.PP
The \f(CW\*(C`\-value\*(C'\fR argument may be either an arrayref, a hashref, or
a string.  \f(CW\*(C`Apache2::Cookie::freeze\*(C'\fR encodes this argument into the
cookie's raw value.
.Sh "freeze"
.IX Subsection "freeze"
.Vb 1
\&    Apache2::Cookie\->freeze($value)
.Ve
.PP
Helper function (for \f(CW\*(C`new\*(C'\fR) that serializes a new cookie's value in a
manner compatible with CGI::Cookie (and Apache2::Cookie 1.X).  This class
method accepts an arrayref, hashref, or normal perl string in \f(CW$value\fR.
.PP
.Vb 1
\&    $value = Apache2::Cookie\->freeze(["2+2", "=4"]);
.Ve
.Sh "thaw"
.IX Subsection "thaw"
.Vb 2
\&    Apache2::Cookie\->thaw($value)
\&    $cookie\->thaw()
.Ve
.PP
This is the helper method (for \f(CW\*(C`value\*(C'\fR) responsible for decoding the
raw value of a cookie.  An optional argument \f(CW$value\fR may be used in
place of the cookie's raw value.  This method can also decode cookie
values created using CGI::Cookie or Apache2::Cookie 1.X.
.PP
.Vb 2
\&    print $cookie\->thaw;                    # prints "bar"
\&    @values = Apache2::Cookie\->thaw($value); # ( "2+2", "=4" )
.Ve
.Sh "as_string"
.IX Subsection "as_string"
.Vb 1
\&    $cookie\->as_string()
.Ve
.PP
Format the cookie object as a string.  The quote-operator for Apache2::Cookie
is overloaded to run this method whenever a cookie appears in quotes.
.PP
.Vb 1
\&    ok "$cookie" eq $cookie\->as_string;
.Ve
.Sh "name"
.IX Subsection "name"
.Vb 1
\&    $cookie\->name()
.Ve
.PP
Get the name of the cookie.
.Sh "value"
.IX Subsection "value"
.Vb 1
\&    $cookie\->value()
.Ve
.PP
Get the (unswizzled) value of the cookie:
.PP
.Vb 2
\&    my $value = $cookie\->value;
\&    my @values = $cookie\->value;
.Ve
.PP
Note: if the cookie's value was created using a  \f(CW\*(C`freeze\*(C'\fR method,
one way to reconstitute the object is by subclassing
Apache2::Cookie with a package that provides the associated \f(CW\*(C`thaw\*(C'\fR sub:
.PP
.Vb 5
\&    {
\&        package My::COOKIE;
\&        @ISA = \*(AqApache2::Cookie\*(Aq;
\&        sub thaw { my $val = shift\->raw_value; $val =~ tr/a\-z/A\-Z/; $val }
\&    }
\&
\&    bless $cookie, "My::COOKIE";
\&
\&    ok $cookie\->value eq "BAR";
.Ve
.Sh "raw_value"
.IX Subsection "raw_value"
.Vb 1
\&    $cookie\->raw_value()
.Ve
.PP
Gets the raw (opaque) value string as it appears in the incoming
\&\*(L"Cookie\*(R" header.
.PP
.Vb 1
\&    ok $cookie\->raw_value eq "bar";
.Ve
.Sh "bake"
.IX Subsection "bake"
.Vb 1
\&    $cookie\->bake($r)
.Ve
.PP
Adds a \fISet-Cookie\fR header to the outgoing headers table.
.Sh "bake2"
.IX Subsection "bake2"
.Vb 1
\&    $cookie\->bake2($r)
.Ve
.PP
Adds a \fISet\-Cookie2\fR header to the outgoing headers table.
.Sh "domain"
.IX Subsection "domain"
.Vb 2
\&    $cookie\->domain()
\&    $cookie\->domain($set)
.Ve
.PP
Get or set the domain for the cookie:
.PP
.Vb 2
\&    $domain = $cookie\->domain;
\&    $cookie\->domain(".cp.net");
.Ve
.Sh "path"
.IX Subsection "path"
.Vb 2
\&    $cookie\->path()
\&    $cookie\->path($set)
.Ve
.PP
Get or set the path for the cookie:
.PP
.Vb 2
\&    $path = $cookie\->path;
\&    $cookie\->path("/");
.Ve
.Sh "version"
.IX Subsection "version"
.Vb 2
\&    $cookie\->version()
\&    $cookie\->version($set)
.Ve
.PP
Get or set the cookie version for this cookie.
Netscape spec cookies have version = 0;
RFC-compliant cookies have version = 1.
.PP
.Vb 3
\&    ok $cookie\->version == 0;
\&    $cookie\->version(1);
\&    ok $cookie\->version == 1;
.Ve
.Sh "expires"
.IX Subsection "expires"
.Vb 2
\&    $cookie\->expires()
\&    $cookie\->expires($set)
.Ve
.PP
Get or set the future expire time for the cookie.  When
assigning, the new value ($set) should match /^\e+?(\ed+)([YMDhms]?)$/
\&\f(CW$2\fR qualifies the number in \f(CW$1\fR as representing \*(L"Y\*(R"ears, \*(L"M\*(R"onths,
\&\*(L"D\*(R"ays, \*(L"h\*(R"ours, \*(L"m\*(R"inutes, or \*(L"s\*(R"econds (if the qualifier is
omitted, the number is interpreted as representing seconds).
As a special case, \f(CW$set\fR = \*(L"now\*(R" is equivalent to \f(CW$set\fR = \*(L"0\*(R".
.PP
.Vb 2
\&    my $expires = $cookie\->expires;
\&    $cookie\->expires("+3h"); # cookie is set to expire in 3 hours
.Ve
.Sh "secure"
.IX Subsection "secure"
.Vb 2
\&    $cookie\->secure()
\&    $cookie\->secure($set)
.Ve
.PP
Get or set the secure flag for the cookie:
.PP
.Vb 3
\&    $cookie\->secure(1);
\&    $is_secure = $cookie\->secure;
\&    $cookie\->secure(0);
.Ve
.Sh "comment"
.IX Subsection "comment"
.Vb 2
\&    $cookie\->comment()
\&    $cookie\->comment($set)
.Ve
.PP
Get or set the comment field of an \s-1RFC\s0 (Version > 0) cookie.
.PP
.Vb 2
\&    $cookie\->comment("Never eat yellow snow");
\&    print $cookie\->comment;
.Ve
.Sh "commentURL"
.IX Subsection "commentURL"
.Vb 2
\&    $cookie\->commentURL()
\&    $cookie\->commentURL($set)
.Ve
.PP
Get or set the commentURL field of an \s-1RFC\s0 (Version > 0) cookie.
.PP
.Vb 2
\&    $cookie\->commentURL("http://localhost/cookie.policy");
\&    print $cookie\->commentURL;
.Ve
.Sh "fetch"
.IX Subsection "fetch"
.Vb 1
\&    Apache2::Cookie\->fetch($r)
.Ve
.PP
Fetch and parse the incoming \fICookie\fR header:
.PP
.Vb 1
\&    my $cookies = Apache2::Cookie\->fetch($r); # APR::Request::Cookie::Table ref
\&
\&    It should be noted, that with perl 5.8+ Iterator magic, table is able
\&    to handle multiple cookies of the same name.
\&
\&    my %cookies = Apache2::Cookie\->fetch($r);
.Ve
.SH "PORTING from 1.X"
.IX Header "PORTING from 1.X"
Changes to the 1.X \s-1API:\s0
.IP "\(bu" 4
\&\f(CW\*(C`Apache2::Cookie::fetch\*(C'\fR now expects an \f(CW$r\fR object as (second)
        argument, although this isn't necessary in mod_perl 2 if
        \f(CW\*(C`Apache2::RequestUtil\*(C'\fR is loaded and 'PerlOptions +GlobalRequest'
        is in effect.
.IP "\(bu" 4
\&\f(CW\*(C`Apache2::Cookie::parse\*(C'\fR is gone.
.IP "\(bu" 4
\&\f(CW\*(C`Apache2::Cookie::new\*(C'\fR no longer encodes the supplied cookie name.
.IP "\(bu" 4
\&\f(CW\*(C`name()\*(C'\fR and \f(CW\*(C`value()\*(C'\fR no longer accept a \*(L"set\*(R" argument. In other words,
        neither a cookie's name, nor its value, may be modified.  A new cookie
        should be made instead.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Apache2::Request, APR::Request::Cookie,
APR::Request::Error, \fICGI::Cookie\fR\|(3)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
.Vb 1
\&  Copyright 2003\-2006  The Apache Software Foundation
\&
\&  Licensed under the Apache License, Version 2.0 (the "License");
\&  you may not use this file except in compliance with the License.
\&  You may obtain a copy of the License at
\&
\&      http://www.apache.org/licenses/LICENSE\-2.0
\&
\&  Unless required by applicable law or agreed to in writing, software
\&  distributed under the License is distributed on an "AS IS" BASIS,
\&  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
\&  See the License for the specific language governing permissions and
\&  limitations under the License.
.Ve