sqlsession Session Managment System
===================================
joshua macadam, josh@onestop.net


Overview
--------

        Session management is handled by setting a cookie on the client containing
a large, random, alphanumeric string for unique identification. This string is recorded,
along with the user's current IP number, in a MySQL table as described below.
      The basic process involves calling a function called s_demand_session() which
will make sure the user has a session, that it's valid (based on elapsed time and IP), and if
not create them a new one, or tell them they need to log back onto the system. This
function can either be called automatically on including sqlsession.ph, or within the
program. The default is within the program.


Installation
------------

        Installation is a simple as it gets. First, just create the database and tables for
sqlsession by using the sql script provided:

              mysql -u root -p <sqlsession.sql

Of course, user does not have to be root.
   Once this is done, just put sqlsession.ph wherever you want it. Although it is not
required, for large applications it should be in the php include path. This can be set easily
in php3.ini by setting include_path. SECURITY NOTE: The path where this is places
should not be web accessable.
       In order to execute the example script ("example.php3") you must copy it to
somewhere in the http path.




Data
----

Currently a few constant values defined in the beginning of sqlsession.ph are relevant:

  MAX_UNAUTH_IDLE: How long, in seconds, can a user be idle on the
    system before their session ID and associated variables are deleted.
    Generally this can be a very high number and is relevant only due to
    resource concerns.

  MAX_AUTH_IDLE: Inversely, how long, in seconds, can a user who has
    logged into the system remains idle before they are effectively
    logged out. This number should be significantly lower than above
    due to security concerns that are obvious.




Function Reference
------------------

function s_killold() - Based on MAX_UNAUTH_IDLE and MAX_AUTH_IDLE,
  deletes all session data (codes and associated variables)
  if they have not been updated in the max lifetime. Updated
  implies any call to s_demand_session() or similar high level
  session call.

  No Return Value.


function s_valid_session($sess) - After calling s_killold() to
  ensure all old session entries are purged, the session code
  passed as $sess will be looked up in the session database
  to ensure it exists, and the calling IP number will be
  referenced to ensure it matches the stored IP of that session.

  Returns 1 on success, 0 on failure.


function s_set_var($varname, $type, $value) - Used to register a
  variable with the current session code (the active session).
  Varname is a string specifying a variable reference. Type
  is the string either "INT" or "STRING". And value is an
  initial value to assign this variable.
  NOTE: Current implementation does not allow for any type of
  floating point number. Until another version is available,
  the "STRING" type should be used.

  No return value.


function s_get_var($varname) - Returns a variable associated with
  the current session code.


function s_is_registered($varname) - Checks to see if a variable is
  registered to the current session code.

  Returns 1 if there is, 0 if not.


function s_demand_session() - One of the most used functions in this
  module, s_demand_session() makes sure a session cookie is set,
  and if not, generates one referencing the current IP. s_touch()
  is used on each call of this function to keep the session code
  from expiring prematurely.

  No return value.


function s_login($userID) - Sets this user as logged in (meaning they
  have been authenticated somehow). $userID is the numeric ID used
  to reference users in all onestop.net projects.

  No return value.


function s_gencode() - Generates a new session code of
  $session_code_length bytes (a variable specified in the function).
  This function does not however, generate the actual session entry,
   just the code.

  Returns a new session code.


function s_begin_session() - Begins a session by creating a new code
  with s_gencode() and recording it in the sessions database, along
  with the users current IP number. A cookie is set on the client's
  system to create useable persistant data.

  Returns the newly generated session code.


function s_return_var($variable) - Returns a variable from the session
  entry record itself. This is primarily an internal function but
  can be used if needed to obtain the users IP or session code.

  Returns the requested variable.


function s_logged_in() - Checks to see whether the user has been
  authenticated into the system yet by s_login().

  Returns 1 if the user has been authenticated, 0 if not.
