http::cookies(3)

NAME

HTTP::Cookies - Cookie storage and management

SYNOPSIS

use HTTP::Cookies;
$cookie_jar = HTTP::Cookies->new;
$cookie_jar->add_cookie_header($request);
$cookie_jar->extract_cookies($response);

DESCRIPTION

Cookies are a general mechanism which server side connec
tions can use to both store and retrieve information on
the client side of the connection. For more information
about cookies refer to <URL:http://www.netscape.com/news
ref/std/cookie_spec.html> and <URL:http://www.cookiecen
tral.com/>. This module also implements the new style
cookies described in RFC 2965. The two variants of cook ies are supposed to be able to coexist happily.

Instances of the class HTTP::Cookies 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 HTTP::Request objects. The state of a HTTP::Cookies object can be saved in and restored from files.

METHODS

The following methods are provided:

$cookie_jar = HTTP::Cookies->new;

The constructor takes hash style parameters. The fol
lowing parameters are recognized:

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 request

ed to be discarded (bool)
hide_cookie2: don't add Cookie2 header to re

quests

Future parameters might include (not yet implemented):

max_cookies 300
max_cookies_per_domain 20
max_cookie_size 4096

no_cookies list of domain names that we never re

turn cookies to

$cookie_jar->add_cookie_header($request);

The add_cookie_header() method will set the appropri ate Cookie:-header for the HTTP::Request object given as argument. The $request must have a valid url
attribute before this method is called.

$cookie_jar->extract_cookies($response);

The extract_cookies() method will look for Set-Cookie: and Set-Cookie2: headers in the HTTP::Response object passed as argument. Any of these headers that are
found are used to update the state of the $cookie_jar.

$cookie_jar->set_cookie($version, $key, $val, $path,
$domain, $port, $path_spec, $secure, $maxage, $discard,
rest)

The set_cookie() method updates the state of the $cookie_jar. The $key, $val, $domain, $port and $path
arguments are strings. The $path_spec, $secure, $dis
card arguments are boolean values. The $maxage value
is a number indicating number of seconds that this
cookie will live. A value <= 0 will delete this
cookie. %rest defines various other attributes like
"Comment" and "CommentURL".

$cookie_jar->save( [$file] );

This method file saves the state of the $cookie_jar to
a file. The state can then be restored later using
the load() method. If a filename is not specified we
will use the name specified during construction. If
the attribute ignore_discared is set, then we will even save cookies that are marked to be discarded.

The default is to save a sequence of "Set-Cookie3"
lines. "Set-Cookie3" is a proprietary LWP format, not
known to be compatible with any browser. The
HTTP::Cookies::Netscape sub-class can be used to save in a format compatible with Netscape.

$cookie_jar->load( [$file] );

This method reads the cookies from the file and adds
them to the $cookie_jar. The file must be in the for
mat written by the save() method.

$cookie_jar->revert;

This method empties the $cookie_jar and re-loads the
$cookie_jar from the last save file.

$cookie_jar->clear( [$domain, [$path, [$key] ] ]);

Invoking this method without arguments will empty the
whole $cookie_jar. If given a single argument only
cookies belonging to that domain will be removed. If
given two arguments, cookies belonging to the speci
fied path within that domain are removed. If given
three arguments, then the cookie with the specified
key, path and domain is removed.

$cookie_jar->clear_temporary_cookies( );

Discard all temporary cookies. Scans for all cookies
in the jar with either no expire field or a true "dis
card" flag. To be called when the user agent shuts
down according to RFC 2965.

$cookie_jar->scan( callback );

The argument is a subroutine that will be invoked for
each cookie stored in the $cookie_jar. The subroutine
will be invoked with the following arguments:

0 version
1 key
2 val
3 path
4 domain
5 port
6 path_spec
7 secure
8 expires
9 discard

10 hash

$cookie_jar->as_string( [$skip_discard] );

The as_string() method will return the state of the $cookie_jar represented as a sequence of "Set-Cookie3"
header lines separated by "0. If $skip_discard is
TRUE, it will not return lines for cookies with the
Discard attribute.

SUB CLASSES

We also provide a subclass called HTTP::Cookies::Netscape which loads and saves Netscape compatible cookie files.
You should be able to have LWP share Netscape's cookies by
constructing your $cookie_jar like this:

$cookie_jar = HTTP::Cookies::Netscape->new(

File => "$ENV{HOME}/.netscape/cook

ies",
AutoSave => 1,

);

Please note that the Netscape cookie file format is not
able to store all the information available in the
Set-Cookie2 headers, so you will probably loose some
information if you save in this format.

COPYRIGHT

Copyright 1997-1999 Gisle Aas

This library is free software; you can redistribute it
and/or modify it under the same terms as Perl itself.

libwww-perl-5.65 2002-02-13 HTTP::Cookies(3)