httpd::session(n) 1.0 "Tcl Web Server"

NAME

httpd::session - Session management

SYNOPSIS

package require httpd::session ?1.0?

Session_Create type ?isSafe?
Session_CreateWithID type id ?isSafe?
Session_Destroy id
Session_Reap age ?type?
Session_Match querylist ?type? ?error_name? ?isSafe?
Session_Authorized id
Session_Require id tag
Session_Import valid array ?interp?
Session_Session arg
Session_Sequence id
Session_Variable id var ?value?
Session_Value id var ?default?

DESCRIPTION

The package httpd::session implements session management for a tcl based web server. The basic idea is to implement a session as a safe slave interpreter that holds its state. Each session has a four-character ID, allowing around 128^4 different sessions, assuming the ASCII character set.

Note: This package does not care where a session id comes from. They can be provided through hidden form data, or through cookies, for example. This is in the area of responsibility of the code making use of the package.

Public API

Session_Create type ?isSafe?
Creates a new session and returns its ID. By default the interpreter created for the session is marked as save, but this can be deactivated by specifying false for isSafe.

The type determines what commands are available in the slave interpreter for the session: All commands in the master interpreter whose name begins with type_ are made available as aliases to the new slave. Inside of the slave the prefix type_ will be stripped off. Additional automatisms: If the first argument of the command is interp or session the alias command will automatically called with either the session interp or the session id. Note that the latter allows determination of the former.

Standard commands available to the seesion interpreter are:

session
Returns the seesion id.

sequence
Returns an increasing sequence number which can be used to chain together pages and detect bookmarks and "backs" that screw things up.

group
Set or get the current session "group". In the session interp a group is simply an array.

value
Get a value from the current "group", or a default value.
Session_CreateWithID type id ?isSafe?
Like Session_Create, except that the id is not randomly chosen, but specified by the caller.

Session_Destroy id
This command destroys the specified session.

Session_Reap age ?type?
This command destroys all sessions which have not been touched for at least age seconds and are matching the type. The latter is a regexp pattern and defaults to .*, i.e. everything matches.

Session_Match querylist ?type? ?error_name? ?isSafe?
Finds a session based on the form data which is stored in the dictionary query. Assumes the existence of a form variable named session.

If the value of that variable is new a new session is created. If it is kill ID the session with that id is destroyed. Else the value is used to look for an existing session. If a type is specified the found session has to be of that type or an error will be thrown. If the session has a sequence number the system expects a form variable sequence and its value has to match.

error_name is the name of the variable where an error message will be stored if something goes wrong. The last argument, isSafe has the same meaning as for Sequence_Create.

The command returns the session id for the session, or the empty string if none could be found.

Session_Authorized id
This command returns the interpreter for the session having the specified id and installs privileged aliases. If the session does not exist it will be created.

An authorized interpreter has two additional commands available to it:

require tag
Loads and initializes packages based on the tag. Calls a command "tag_Init" with the session array and returns its result as the HTML generated by this command.

exit
Destroys the session.
Session_Require id tag
See above, Session_Authorized. This implements the require command to load and initialize special packages in the session interpreter.

Session_Import valid array ?interp?
Imports the valid components of the array in interp as variables into the local scope. valid is the name of an array whose keys are the valid components to import (prefix with a dash). If valid is the empty string all components of the array are imported.

If no interp was specified the main interp is used as source.

Session_Session arg
Returns the argument. This implements the session command for session interpreters.

Session_Sequence id
Generates a sequence value and returns it. This implements the sequence command for session interpreters.

Session_Variable id var ?value?
Sets or gets data from the global state associated with the session interpreter. This is used to implement the group command for session interpreters.

Session_Value id var ?default?
Gets a value from the current group, or a default if the group does not have a component called var. This implements the value command for session interpreters.

SEE ALSO

httpd, httpd::utils

KEYWORDS

sessions, web server

COPYRIGHT

Copyright © 2003 Andreas Kupries <andreas_kupries@users.sourceforge.net>