cookies.pm - an object class interface to HTTP cookies.
use EWS::cookies;
### Public Methods ###
$cookies = new EWS::cookies(-io => $baseIO);
%cookieHash = $cookies->cookies($cookie_name);
$cookieRef = $cookies->cookiesref($cookie_name);
$expiration = $cookies->expirationDate(7 * 24 * 60); # 7 days from now.
$cookie_value = $cookies->find($cookie_name);
@cookie_names = $cookies->names;
%cookie_hash = $cookies->read;
$cookie_ref = $cookies->readref;
$cookies->reset($name);
$secure = $cookies->secure($name);
$newSecure = $cookies->secure($name, 1);
$cookies->send;
$cookies->sendall;
$cookies->sendheader;
$cookies->sendmodified;
$cookies->set($name, {-value => 'Value',
-domain => $domain,
-expires => 7 * 24 * 60 * 60, # 7 days
-path => '/'} );
### Private Methods ###
$cookies->_setItem;
### Attributes ###
$domain = $cookies->domain($name);
$newDomain = $cookies->domain($name, $cookieDomain);
$expires = $cookies->expires($name);
$newExpiration = $cookies->expires($name, $expirationDate);
if ($cookies->isCookie($name))
{
...
}
$modified = $cookies->modified($name);
$newModified = $cookies->modified($name, 1);
$path = $cookies->path($name);
$newPath = $cookies->path($name, '/');
$revision = $cookies->Revision;
$secure = $cookies->secure($name);
$newSecure = $cookies->secure($name, 1);
$cookie_exists = $cookies->valid;
$value = $cookies->value($cookie_name);
$newValue = $cookies->value($cookie_name, $value);
$version = $cookies->Version;
EWS::cookies is an object class interface to HTTP cookies. EWS::cookies creates a wrapper around the methods and attributes used to manipulate HTTP cookies.
EWS::cookies can be sub-classed and supports full inheritance. It may be used as a base-class for a new class object specific to an application.
A single hash structure (hash of hashes) is maintained by EWS::cookies. It is used to hold the values of the current HTTP Cookie and to construct a cookie for output to the http user-agent using the EWS::baseIO object class. Attribute methods are provided to access and modify each field of each cookie within this complex structure.
The new method creates a new object class used to manipulate a cookie item:
$cookie = EWS::cookies->new(-io => EWS::baseIO object,
-debug => 1 to debug,
-path => RFC2109 path,
-expire => expiration time, in seconds);
or
$cookie = new EWS::cookies(-io => EWS::baseIO object,
-debug => 1 to debug,
-path => RFC2109 path,
-expire => expiration time, in seconds);
Enter:
%params = parameter hash (see below).
Exit:
$self = blessed class object.
%params contain hash values as follows:
-expire => default expiration date, in seconds (default = 1 year).
-path => RFC2109 path (default = "/")
-io => baseIO object (default = internally generated baseIO object).
-debug => 1 to debug (default = 0)
Fetch all cookie values from class structure:
%cookies = $cookies->cookies;
Enter:
none.
Exit:
%cookies = hash of cookies
undef if not found
Fetch reference to cookie hash:
%cookies = $cookies->cookiesref;
Enter:
none.
Exit:
\%cookies = reference to hash of cookies
undef if not found
The expirationDate method sets the expiration time of the cookie as an offset from the current time:
$cookie->expirationDate($Offset);
To set a cookie as expired, pass -1 to the routine, and the time will be set backwards, causing the cookie to expire.
Enter:
$delta = # seconds until expiration
Exit:
$expiration = expiration date string in RFC2109 format.
The find method expects the name of the Cookie to find:
$value = $cookie->find($name);
If the requested name is found, its associated value is returned. If the requested name is NOT found, undef is returned.
Enter:
$name = name of cookie to locate.
Exit:
$value = value of cookie.
undef if $name does not exist.
The GetCookieNames method returns the cookie names:
@names = $cookie->names;
Enter:
none.
Exit:
array containing cookie names (array reference in scalar mode)
undef if cookies not defined.
The read method reads the current cookie values and returns them in a hash:
%cookieHash = $cookies->read;
The hash returned contains the cookie names as the key and the cookie values as the associated data.
Enter:
none.
Exit:
%cookieHash = hash containing cookies read.
undef if no cookies to load.
The readref method reads the current cookie values into an internal hash and returns a reference pointer to the hash:
$cookieRef = $cookies->readref;
The referenced hash contains the cookie names as the key and the cookie values as the associated data.
Enter:
none.
Exit:
$cookies = reference to hash containing cookies read.
undef if no cookies to load.
The reset method resets cookie parameters:
$cookie->reset;
Enter:
$name = name of cookie to reset.
Exit:
none.
The send method sends the cookie parameters set in the set method to the user-agent:
$cookie->send;
Note: After the last cookie has been sent, an HTML header must be sent to the browser to activate the cookie. See sendHtmlHeader.
Enter:
$name = name of cookie to send.
Exit:
1 if $name exists and has been sent.
undef if $name does not exist.
Send the values in all cookie hashes to the requesting browser.
Enter:
none.
Exit:
none.
The sendheader method sends an HTML header to the browser. This header should be sent AFTER the LAST cookie has been sent to the browser, and contains the following information:
Content-type: text/html
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html>
<head>
<meta http-equiv="Content-Type"
content="text/html; charset=iso-8859-1">
<meta name="GENERATOR" content="myprog">
where myprog is the name of the perl script containing the EWS::cookies module.
This method is included for completness only.
Enter:
none.
Exit:
none.
Send the values in cookie hashes containing modified=1 to the user-agent.
Enter:
none.
Exit:
none.
Calls B<send> for each cookie name that has modified > 0.
The set method allows setting of any (or all) of the parameters of a cookie:
$cookie->set(-cookie_field=>cookie_value, ...);
Parameters may be of the form:
Set Cookie Name: -name => Cookie Name (required)
Set Cookie Value: -value => Value
Cookie Path: -path => Path
Domain: -domain => Domain
Expiration date: -expires => Date
Secure: -secure => value
Any, or all, of the parameters may be set in a single call. Multiple calls can be used to set individual parameters.
Note: This method does NOT send the cookie. It merely sets cookie
parameter(s).
Enter:
%params = parameter hash (see above).
Exit:
none.
The domain method expects the name of the cookie to evaluate and an optional domain to set:
$domain = $cookie->domain($name);
or
$newDomain = $cookie->domain($name, $domain);
Enter:
$name = cookie name
$domain = domain value.
Exit:
$domain = current domain
undef if not found.
The expires method expects the name of the cookie to evaluate and an optional expires to set:
$expires = $cookie->expires($name);
or
$newExpires = $cookie->expires($name, $expires);
Enter:
$name = cookie name
$expires = expires value.
Exit:
$expires = current expires
undef if not found.
Check for existence of a cookie with $name.
Enter:
$name = cookie name to check for
Exit:
1 if exists
undef if doesn't exist
The modified method expects the name of the cookie to evaluate and an optional modified to set:
$modified = $cookie->modified($name);
or
$newModified = $cookie->modified($name, $modified);
Enter:
$name = cookie name
$modified = modified value.
Exit:
$modified = current modified
undef if not found.
The path method expects the name of the cookie to evaluate and an optional path to set:
$path = $cookie->path($name);
or
$newPath = $cookie->path($name, $path);
Enter:
$name = cookie name
$path = path value.
Exit:
$path = current path
undef if not found.
The Revision method returns the revision number of cookies.pm:
$cookie_revision = $cookie->Revision;
Enter:
none.
Exit:
current revision string.
The secure method expects the name of the cookie to evaluate and an optional secure to set:
$secure = $cookie->secure($name);
or
$newSecure = $cookie->secure($name, $secure);
Enter:
$name = cookie name
$secure = secure value.
Exit:
$secure = current secure
undef if not found.
The valid method returns defined if a cookie exists, and undef if no cookies are found.
Enter:
none.
Exit:
1 if cookies have been returned by the user-agent.
0 if no cookies
The value method expects the name of the cookie to evaluate:
$value = $cookie->value($name);
Enter:
$name = cookie name
Exit:
value of cookie.
undef if not found.
The Version method returns the version number of cookies.pm:
$cookie_version = $cookie->Version;
Enter:
none.
Exit:
current version string.
Local subroutine to set the value of a new cookie item, if a match to a built-in key is found.
For cookie $name, set $field to $value if
$key eq $param
NOTE: This routine IGNORES errors!
(i.e. - the assumption is that you know what you are doing!)
Enter:
$name = cookie name (e.g. -name)
$key = cookie field name to match
$param = parameter name of field being set
$field = cookie field name
$value = field value to set
Exit:
1 if added
0 if not added.
This module assumes that the target platform (web server) supports the HTTP_COOKIE environment variable ($ENV{'HTTP_COOKIE'}).
This implementation was developed on a FreeBSD 4.3 Unix server running the Apache Server and perl 5.005. It has been tested on Microsoft Windows200 and WindowsNT 4.0 platform running the Microsoft Internet Information Server (IIS3/IIS4) and ActivePerl. It is currently in use on several Linux servers of various vintages.
This implementation conforms to RFC2109, HTTP State Management Mechanism, available at http://www.faqs.org/rfcs/rfc2109.html
RFC2109, HTTP State Management Mechanism, is available at http://www.faqs.org/rfcs/rfc2109.html
For more information on using cookies, the technical specification, or other samples/examples of cookie implementations in perl5 as well as C++, Java, JavaScript, etc., refer to the very well informative site Cookie Central at http://www.cookiecentral.com .
There is a VERY good FAQ written by David Whalen at http://www.cookiecentral.com/faq/ .
Jay Wheeler (jaywheeler@geocities.com), EarthWalk Software.
EWS::cookies is copyright © 1999, 2002. EarthWalk Software.
This module is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.
This module is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License along with this script; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA, or from the Free Software Foundation web page at http://www.fsf.org/licenses/lgpl.txt