390 lines
9.5 KiB
HTML
390 lines
9.5 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of HTTP::Cookies</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>HTTP::Cookies</H1>
|
|
Section: User Contributed Perl Documentation (3pm)<BR>Updated: 2019-12-06<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
HTTP::Cookies - HTTP cookie jars
|
|
<A NAME="lbAC"> </A>
|
|
<H2>VERSION</H2>
|
|
|
|
|
|
|
|
version 6.08
|
|
<A NAME="lbAD"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
use HTTP::Cookies;
|
|
$cookie_jar = HTTP::Cookies->new(
|
|
file => "$ENV{'HOME'}/lwp_cookies.dat",
|
|
autosave => 1,
|
|
);
|
|
|
|
use LWP;
|
|
my $browser = LWP::UserAgent->new;
|
|
$browser->cookie_jar($cookie_jar);
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Or for an empty and temporary cookie jar:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
use LWP;
|
|
my $browser = LWP::UserAgent->new;
|
|
$browser->cookie_jar( {} );
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbAE"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
|
|
|
|
This class is for objects that represent a ``cookie jar'' --- that is, a
|
|
database of all the <FONT SIZE="-1">HTTP</FONT> cookies that a given LWP::UserAgent object
|
|
knows about.
|
|
<P>
|
|
|
|
Cookies are a general mechanism which server side connections can use
|
|
to both store and retrieve information on the client side of the
|
|
connection. For more information about cookies refer to
|
|
Cookie Spec <<A HREF="http://curl.haxx.se/rfc/cookie_spec.html">http://curl.haxx.se/rfc/cookie_spec.html</A>> and
|
|
Cookie Central <<A HREF="http://www.cookiecentral.com">http://www.cookiecentral.com</A>>. This module also implements the
|
|
new style cookies described in <FONT SIZE="-1">RFC 2965</FONT> <<A HREF="https://tools.ietf.org/html/rfc2965">https://tools.ietf.org/html/rfc2965</A>>.
|
|
The two variants of cookies are supposed to be able to coexist happily.
|
|
<P>
|
|
|
|
Instances of the class <I>HTTP::Cookies</I> are able to store a collection
|
|
of Set-Cookie2: and Set-Cookie: headers and are able to use this
|
|
information to initialize Cookie-headers in <I>HTTP::Request</I> objects.
|
|
The state of a <I>HTTP::Cookies</I> object can be saved in and restored from
|
|
files.
|
|
<A NAME="lbAF"> </A>
|
|
<H2>LIMITATIONS</H2>
|
|
|
|
|
|
|
|
This module does not support Public Suffix <<A HREF="https://publicsuffix.org/">https://publicsuffix.org/</A>> encouraged by a more recent standard, <FONT SIZE="-1">RFC
|
|
6265</FONT> <<A HREF="https://tools.ietf.org/html/rfc6265">https://tools.ietf.org/html/rfc6265</A>>.
|
|
<P>
|
|
|
|
This module's shortcomings mean that a malicious Web site can set
|
|
cookies to track your user agent across all sites under a top level
|
|
domain. See <I>t/publicsuffix.t</I> in this module's distribution for
|
|
details.
|
|
<P>
|
|
|
|
HTTP::CookieJar::LWP supports Public Suffix, but only provides a
|
|
limited subset of this module's functionality and does not
|
|
support standards older than
|
|
<I></I><FONT SIZE="-1"><I>RFC 6265</I></FONT><I></I>.
|
|
<A NAME="lbAG"> </A>
|
|
<H2>METHODS</H2>
|
|
|
|
|
|
|
|
The following methods are provided:
|
|
<DL COMPACT>
|
|
<DT id="1">$cookie_jar = HTTP::Cookies->new<DD>
|
|
|
|
|
|
|
|
|
|
The constructor takes hash style parameters. The following
|
|
parameters are recognized:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
file: name of the file to restore cookies from and save cookies to
|
|
autosave: save during destruction (bool)
|
|
ignore_discard: save even cookies that are requested to be discarded (bool)
|
|
hide_cookie2: do not add Cookie2 header to requests
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Future parameters might include (not yet implemented):
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
max_cookies 300
|
|
max_cookies_per_domain 20
|
|
max_cookie_size 4096
|
|
|
|
no_cookies list of domain names that we never return cookies to
|
|
|
|
</PRE>
|
|
|
|
|
|
<DT id="2">$cookie_jar->get_cookies( $url_or_domain )<DD>
|
|
|
|
|
|
|
|
|
|
|
|
<DT id="3">$cookie_jar->get_cookies( $url_or_domain, $cookie_key,... )<DD>
|
|
|
|
|
|
|
|
|
|
|
|
Returns a hash of the cookies that applies to the given <FONT SIZE="-1">URL.</FONT> If a
|
|
domainname is given as argument, then a prefix of ``<A HREF="https://''">https://''</A> is assumed.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If one or more <TT>$cookie_key</TT> parameters are provided return the given values,
|
|
or <TT>"undef"</TT> if the cookie isn't available.
|
|
<DT id="4">$cookie_jar->add_cookie_header( $request )<DD>
|
|
|
|
|
|
|
|
|
|
The <B>add_cookie_header()</B> method will set the appropriate Cookie:-header
|
|
for the <I>HTTP::Request</I> object given as argument. The <TT>$request</TT> must
|
|
have a valid url attribute before this method is called.
|
|
<DT id="5">$cookie_jar->extract_cookies( $response )<DD>
|
|
|
|
|
|
|
|
|
|
The <B>extract_cookies()</B> method will look for Set-Cookie: and
|
|
Set-Cookie2: headers in the <I>HTTP::Response</I> object passed as
|
|
argument. Any of these headers that are found are used to update
|
|
the state of the <TT>$cookie_jar</TT>.
|
|
<DT id="6">$cookie_jar->set_cookie( $version, $key, $val, $path, $domain, $port, $path_spec, $secure, $maxage, $discard, \%rest )<DD>
|
|
|
|
|
|
|
|
|
|
The <B>set_cookie()</B> method updates the state of the <TT>$cookie_jar</TT>. The
|
|
<TT>$key</TT>, <TT>$val</TT>, <TT>$domain</TT>, <TT>$port</TT> and <TT>$path</TT> arguments are strings. The
|
|
<TT>$path_spec</TT>, <TT>$secure</TT>, <TT>$discard</TT> arguments are boolean values. The <TT>$maxage</TT>
|
|
value is a number indicating number of seconds that this cookie will
|
|
live. A value of <TT>$maxage</TT> <= 0 will delete this cookie. The <TT>$version</TT> argument
|
|
sets the version of the cookie; the default value is 0 ( original Netscape
|
|
spec ). Setting <TT>$version</TT> to another value indicates the <FONT SIZE="-1">RFC</FONT> to which the
|
|
cookie conforms (e.g. version 1 for <FONT SIZE="-1">RFC 2109</FONT>). <TT>%rest</TT> defines various other
|
|
attributes like ``Comment'' and ``CommentURL''.
|
|
<DT id="7">$cookie_jar->save<DD>
|
|
|
|
|
|
|
|
|
|
|
|
<DT id="8">$cookie_jar->save( $file )<DD>
|
|
|
|
|
|
|
|
|
|
<DT id="9">$cookie_jar->save( file => $file, ignore_discard => $ignore_discard )<DD>
|
|
|
|
|
|
|
|
|
|
|
|
This method file saves the state of the <TT>$cookie_jar</TT> to a file.
|
|
The state can then be restored later using the <B>load()</B> method. If a
|
|
filename is not specified we will use the name specified during
|
|
construction. If the <TT>$ignore_discard</TT> value is true (or not specified,
|
|
but attribute <I>ignore_discard</I> was set at cookie jar construction),
|
|
then we will even save cookies that are marked to be discarded.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The default is to save a sequence of ``Set-Cookie3'' lines.
|
|
``Set-Cookie3'' is a proprietary <FONT SIZE="-1">LWP</FONT> format, not known to be compatible
|
|
with any browser. The <I>HTTP::Cookies::Netscape</I> sub-class can
|
|
be used to save in a format compatible with Netscape.
|
|
<DT id="10">$cookie_jar->load<DD>
|
|
|
|
|
|
|
|
|
|
|
|
<DT id="11">$cookie_jar->load( $file )<DD>
|
|
|
|
|
|
|
|
|
|
|
|
This method reads the cookies from the file and adds them to the
|
|
<TT>$cookie_jar</TT>. The file must be in the format written by the <B>save()</B>
|
|
method.
|
|
<DT id="12">$cookie_jar->revert<DD>
|
|
|
|
|
|
|
|
|
|
This method empties the <TT>$cookie_jar</TT> and re-loads the <TT>$cookie_jar</TT>
|
|
from the last save file.
|
|
<DT id="13">$cookie_jar->clear<DD>
|
|
|
|
|
|
|
|
|
|
|
|
<DT id="14">$cookie_jar->clear( $domain )<DD>
|
|
|
|
|
|
|
|
|
|
<DT id="15">$cookie_jar->clear( $domain, $path )<DD>
|
|
|
|
|
|
|
|
|
|
<DT id="16">$cookie_jar->clear( $domain, $path, $key )<DD>
|
|
|
|
|
|
|
|
|
|
|
|
Invoking this method without arguments will empty the whole
|
|
<TT>$cookie_jar</TT>. If given a single argument only cookies belonging to
|
|
that domain will be removed. If given two arguments, cookies
|
|
belonging to the specified path within that domain are removed. If
|
|
given three arguments, then the cookie with the specified key, path
|
|
and domain is removed.
|
|
<DT id="17">$cookie_jar->clear_temporary_cookies<DD>
|
|
|
|
|
|
|
|
|
|
Discard all temporary cookies. Scans for all cookies in the jar
|
|
with either no expire field or a true <TT>"discard"</TT> flag. To be
|
|
called when the user agent shuts down according to <FONT SIZE="-1">RFC 2965.</FONT>
|
|
<DT id="18">$cookie_jar->scan( \&callback )<DD>
|
|
|
|
|
|
|
|
|
|
The argument is a subroutine that will be invoked for each cookie
|
|
stored in the <TT>$cookie_jar</TT>. The subroutine will be invoked with
|
|
the following arguments:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
0 version
|
|
1 key
|
|
2 val
|
|
3 path
|
|
4 domain
|
|
5 port
|
|
6 path_spec
|
|
7 secure
|
|
8 expires
|
|
9 discard
|
|
10 hash
|
|
|
|
</PRE>
|
|
|
|
|
|
<DT id="19">$cookie_jar->as_string<DD>
|
|
|
|
|
|
|
|
|
|
|
|
<DT id="20">$cookie_jar->as_string( $skip_discardables )<DD>
|
|
|
|
|
|
|
|
|
|
|
|
The <B>as_string()</B> method will return the state of the <TT>$cookie_jar</TT>
|
|
represented as a sequence of ``Set-Cookie3'' header lines separated by
|
|
``\n''. If <TT>$skip_discardables</TT> is <FONT SIZE="-1">TRUE,</FONT> it will not return lines for
|
|
cookies with the <I>Discard</I> attribute.
|
|
</DL>
|
|
<A NAME="lbAH"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
|
|
|
|
HTTP::Cookies::Netscape, HTTP::Cookies::Microsoft
|
|
<A NAME="lbAI"> </A>
|
|
<H2>AUTHOR</H2>
|
|
|
|
|
|
|
|
Gisle Aas <<A HREF="mailto:gisle@activestate.com">gisle@activestate.com</A>>
|
|
<A NAME="lbAJ"> </A>
|
|
<H2>COPYRIGHT AND LICENSE</H2>
|
|
|
|
|
|
|
|
This software is copyright (c) 2002-2019 by Gisle Aas.
|
|
<P>
|
|
|
|
This is free software; you can redistribute it and/or modify it under
|
|
the same terms as the Perl 5 programming language system itself.
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="21"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="22"><A HREF="#lbAC">VERSION</A><DD>
|
|
<DT id="23"><A HREF="#lbAD">SYNOPSIS</A><DD>
|
|
<DT id="24"><A HREF="#lbAE">DESCRIPTION</A><DD>
|
|
<DT id="25"><A HREF="#lbAF">LIMITATIONS</A><DD>
|
|
<DT id="26"><A HREF="#lbAG">METHODS</A><DD>
|
|
<DT id="27"><A HREF="#lbAH">SEE ALSO</A><DD>
|
|
<DT id="28"><A HREF="#lbAI">AUTHOR</A><DD>
|
|
<DT id="29"><A HREF="#lbAJ">COPYRIGHT AND LICENSE</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:45 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|