An abstract data store for cookies.

The general usage is as follows:

my $cookiejar; $cookiejar = new CGI::Session::CookieJar::YOUR_JAR_HERE( PARAMETERS ); $cookiejar->open(); ... ... cookie operations ... $cookiejar->close();

Most functions manipulating cookies use "queries" to specify the cookies which will be operated upon. These queries are references to associative arrays. The keys indicate variables which will be compared, and the values specify the query operations. These intersection of all the results determines which ones will be selected.

Here are examples of simple queries:

{ user => "bob" } selects all cookies with the user value of "bob"

{ expiration => "<".time() } selects all cookies which have already expired

{ expiration => ">".time() } selects all cookies which have not expired

{ cookie_name => "$cookie" } selects all cookies which are named $cookie

{ passkey => "435765" } selects all cookies which have the passkey value of "435765"

{ user => "bob", passkey => "6578" } selects all cookies which have the user "bob" and the passkey set to "6578"

There is no way to select a union of search results.

$cookiejar->open();

Opens up the cookie jar. This must be called before any operations can take place. When you are through with the cookie jar the close operation me be called.

$cookiejar->close;

Closes a previously opened cookie jar. This must be done before your program ends.

Determines if a session contains a given cookie.

my $time = time; my %query = ( user=>'bob', cookie_name=>'3476dfgh', passkey=>'23438', expiration=>'>$time' );

my $has_cookie = $cookie_jar->contains( -query => \$query );

Retreives a cookie from the cookie jar using a specified query. If no cookie is found then it returns 'undef'.

By default all cookie fields are returned as an array of hashes . If your application potentially contains large 'server_side_data' fields this may not be what you want. In this case cases you can specify that the server_side_data field will not be returned by setting the -omit_server_side_data option to a true value.

my $time = time; my %query = ( user=>'bob', cookie_name=>'3476dfgh', passkey=>'23438', expiration=>">$time" );

my $cookie = $cookie_jar->cookie( -query => \%query );

if ( !defined $cookie ) { croak "There is no such cookie."; }

...or...

my @sessions = $cookie_jar->session( -query => \%query, -omit_server_side_data=>1 );

Deletes the specified cookies from the cookie jar.

my $time = time; my %query = ( expiration=>'<$time' ); $cookie_jar->delete( -query => \$query );

Sets the session variables for a previously created user entry. The user entry must already exist. If it does not exist then it must be created with CGI::Session::CookieJar::register_user.

The 'user' field is required for the c

my $time = time; my %session = ( user=>'bob', cookie_name=>'3476dfgh', passkey=>'23438', expiration=>'$time', server_data=>$data );

my $cookie_jar->set_session( -session => \%session );

Creates an entry for the specified user within the cookie jar. Attempting to register a user which does not exist will result in an error.

  if ( ! $cookie_jar->contains( -user=>$username ) )
    {
      $cookie_jar->register_user( $username );
    }

Returns the version of CGI::Session that was used to create this data store.

my $version => $cookie_jar->version();

Creates a new cookie jar. For a database cookie jar this would create the necessary tables. For a file based cookie jar this might set up the required directory structure.

This should only be necessary once.

$cookie_jar->create_cookie_jar();

Destroys an existing cookie jar. For a database cookie jar this would drop all of the tables. For a file based cookie jar this might delete all the existing files and directories.

This should only be necessary once.

$cookie_jar->destroy_cookie_jar();

If the previous cookie operation resulted in an error then the value of this error will be found here. If the operation did not result in an error then this will return 'undef'.

Calling error() does not alter the value. Each cookie jar object has it's own error state, which is independent of the backend database.

my $error = $cookie_jar->error();