NAME

CGI::Cookie::Jam - Jam a large number of cookies to a small one.

SYNOPSIS

 use CGI::Cookie::Jam qw(enjam dejam);
 
 my %param1(
     name    => 'Masanori HATA'           ,
     mail    => 'lovewing@dream.big.or.jp',
     sex     => 'male'                    ,
     birth   => '2003-04-09'              ,
     nation  => 'Japan'                   ,
     pref    => 'Saitama'                 ,
     city    => 'Kawaguchi'               ,
     tel     => '+81-48-2XX-XXXX'         ,
     fax     => '+81-48-2XX-XXXX'         ,
     job     => 'student'                 ,
     role    => 'president'               ,
     hobby   => 'exaggeration'            ,
     );
 my @cookie = enjam('jam', '4096', %param1);
 
 my %param2 = dejam($ENV{'HTTP_COOKIE'});

DESCRIPTION

This module provides jamming mean to WWW cookie. Cookie is convenient but there are some limitations on number of cookies that a client can store at a time:

 300 total cookies
 4KB per cookie, where the NAME and the VALUE combine to form the 4KB limit.
 20 cookies per server or domain.

Especially, 20 cookies limitation could be a bottle neck. So this module try to jam some cookies (which holds single pair of the NAME and the VALUE) to a cookie at maximum size of 4KB, that you can save total number of cookies to a minimum one.

FUNCTIONS

enjam($cookie_name, $maximum_size, %param)

Exportable function. This function jams a lot number of multiple NAME=VALUE strings for Set-Cookie: HTTP header to a minimum number of NAME=VALUE strings for Set-Cookie: HTTP header. It returns a list of multiple enjammed strings.

The enjamming algorithm is realized by twice uri-escaping. At first, each cookie's NAME and VALUE pairs are uri-escaped and joined with = (an equal mark). Then, multiple NAME=VALUE pairs are joined with & (an ampersand mark). This procedure is very the uri-encoding (see http://www.w3.org/TR/html4/interact/forms.html#h-17.13.4.1).

Still a cookie has only one NAME=VALUE pair, the uri-encoded string must be re-uri-escaped at the second procedure. As a result:

 '=' is converted to '%3D'
 '&' is converted to '%26'
 '%' is converted to '%25'

At last, this module uses the jam's $cookie_name (which is, of course, uri-escaped, and coupled with a serial number like $cookie_name_XX) as cookie NAME and uses the twice uri-escaped string as cookie VALUE, then join both with = to make a NAME=VALUE string. The final product is very the enjammed multi-spanning cookies.

With size attribute you can specify the size (bytes) of a cookie (that is the size of NAME=VALUE string). Generally, to set 4096 bytes (4KB) is recommended. If you set 0 byte, no size limitation will work and only one cookie will be generated without filename numbering (_XX).

When you use enjammed cookies, you may dejam to reverse the above procedure:

 1: Extract VALUEs
    and join the splitted enjammed VALUE strings to a string.
 2: uri-unescape '%3D' to '=', '%26' to '&', '%25' to '%'.
 3: uri-decode the uri-encoded string to multiple NAME and VALUE pairs.

This module implements above the function as dejam() method except for the first procedure. Otherwise, you may implement dejam() function by client side using with JavaScript and so on.

dejam($jam_string)

Exportable function. This function dejams an enjammed cookie string. It returns NAME and VALUE pairs as a list. You may use those dejammed data to put into an hash.

Note that this method does not care multi-spanning enjammed cookies.

encryptjam($cookie_name, $maximum_size, $magic_number, %param)

decryptjam($magic_number, $cryptjam_string)

Exportable functions. These functions are used to handle an encrypted/decrypted cookie jam. Magic number will be used as a seed of encrypting. To decrypt an encrypted jam, you must use the same magic number for the string.

These are alternatives for enjam() and dejam() functions.

SEE ALSO

Netscape: http://wp.netscape.com/newsref/std/cookie_spec.html (Cookie)

RFC 2965: http://www.ietf.org/rfc/rfc2965.txt (Cookie)

HTML 4: http://www.w3.org/TR/html4/interact/forms.html#h-17.13.4.1 (uri-encode)

AUTHOR

Masanori HATA http://go.to/hata (Saitama, JAPAN)

COPYRIGHT

Copyright (c) 2003-2005 Masanori HATA. All rights reserved.

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