cson  cson_sessmgr_cpdo

ACHTUNG: THIS PAGE IS NOW MAINTAINED IN THE NEW WIKI: http://whiki.wanderinghorse.net/wikis/cson/?page=cson_sessmgr_cpdo

See also: cson_session, cson_sessmgr_file, cson_sessmgr_whio_ht, cson_sessmgr_whio_epfs

Database cson_session Storage

For this to be enabled, the library must be built with the CSON_ENABLE_CPDO macro set to a true value. Additionally, CPDO_ENABLE_SQLITE3 and/or CPDO_ENABLE_MYSQL5 will need to be set to true values if those back-ends are to be enabled. See AmalgamationBuild for more details.

The function cson_sessmgr_cpdo() is used to instantiate a session manager for database-based storage, using the cpdo database access abstraction library (included in this source tree). Or one can use cson_sessmgr_load()>, passing it a key of "cpdo". The second argument to both functions is a cson_object which should have the following JSON structure:

{
    "dsn": "drivername:driver_options... see cpdo docs",
    "user": "database user name",
    "password": "database password", 
    "table": "database table name containing the sessions",
    "fieldId": "db field which stores the session id (VARCHAR, length is app-dependent)",
    "fieldTimestamp": "db field which stores the last modification time (INTEGER-form timestamp)",
    "fieldSession": "db field which stores the raw JSON data (TEXT or BLOB, depending on the db)"
}

The "dsn" option is required. All others use defaults if not specified (but logging in will likely fail if the user/password parts are not supplied). cpdo's DSN string format is described on this page. Note that the sqlite3-based back-end does not require user/password information.

The fieldTimestamp value must name a field which contains an integer value. The library assumes that times are stored in Unix Epoch (seconds since midnight 1970.1.1). The library currently uses local time, but should arguably be changed to use GMT (or make this a config option).

See the file cgi-test.json, in the source tree, for examples of configuring both sqlite3- and mysql-based sessions.

Here is some sample SQL for setting up a session table:

sqlite3:

CREATE TABLE cson_session (
    id VARCHAR(50) PRIMARY KEY NOT NULL, -- session ID string
    last_saved INTEGER NOT NULL DEFAULT 0, -- Unix Epoch timestamp
    json TEXT DEFAULT NULL -- the raw session JSON
);

MySQL 5:

CREATE TABLE `cson_session` (
  `id` varchar(50) PRIMARY KEY NOT NULL,
  `last_saved` int(11) NOT NULL DEFAULT 0,
  `json` text DEFAULT NULL
) ENGINE=MyISAM DEFAULT CHARSET=utf8;

Note, however, that the manager configuration options can be used to define the names of the table and fields. Client-side session tables can also have additional fields, with the caveats that all must be able to default to some value and that this library might delete them (when it saves the session). This API only explicitly uses the fields described above, but may remove/replace rows, so clients cannot depend on any custom fields having stable values.