<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html;charset=utf-8">
<meta http-equiv="cache-control" content="no-cache">
<title>Genivia - The Sessions Plugin</title>
<link href="genivia_tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css">
<link href="genivia_content.css" rel="stylesheet" type="text/css">
</head>
<body>
<div id="top">
<div id="titlearea">
<table height="72px" width="100%" cellspacing="0" cellpadding="0">
<tbody>
<tr>
<td width="10%"> </td>
<td width="175px"><a href="http://www.genivia.com"><img alt="Genivia" src="GeniviaLogo2_trans_noslogan.png"/></a></td>
<td class="tab_home"><a href="http://www.genivia.com">Home</a></td>
<td class="tab_home"><a href="http://www.genivia.com/docs.html">Documentation</a></td>
<td>
<div style="float: right; font-size: 18px; font-weight: bold;">The Sessions Plugin</div>
<br>
<div style="float: right; font-size: 10px;">updated Wed Aug 17 2016</div>
</td>
<td width="10%"> </td>
</tr>
</tbody>
</table>
</div>
<!-- Generated by Doxygen 1.8.10 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<li class="current"><a href="index.html"><span>Main Page</span></a></li>
<li><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="annotated.html"><span>Classes</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
</div><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title">The Sessions Plugin </div> </div>
</div><!--header-->
<div class="contents">
<div class="toc"><h3>Table of Contents</h3>
<ul><li class="level1"><a href="#title">HTTP Server Session Management Plugin</a></li>
<li class="level1"><a href="#overview">Overview</a></li>
<li class="level1"><a href="#features">Features</a></li>
<li class="level1"><a href="#setup">Setup</a></li>
<li class="level1"><a href="#usage">Basic Usage</a></li>
<li class="level1"><a href="#example">Simple Calculator Server (C) Example</a></li>
<li class="level1"><a href="#api">Sessions Plugin API</a></li>
<li class="level1"><a href="#settings">Settings</a></li>
<li class="level1"><a href="#internals">The Internals</a></li>
</ul>
</div>
<div class="textblock"><h1><a class="anchor" id="title"></a>
HTTP Server Session Management Plugin</h1>
<p>By Chris Moutsos and Robert van Engelen.</p>
<h1><a class="anchor" id="overview"></a>
Overview</h1>
<p>The HTTP server session management plugin for gSOAP enables servers to store a database of sessions to keep track of client data across multiple requests. Client data is stored per session as name and value pairs that can be set to any valid string. Sessions are tracked with unique session IDs (sometimes called tokens) that are passed between the server and client with HTTP cookies.</p>
<p>The sessions plugin is MT safe.</p>
<h1><a class="anchor" id="features"></a>
Features</h1>
<ul>
<li>Stores sessions identified by random 128-bit session IDs managed with HTTP cookies</li>
<li>Session validity can be restricted based on domain and path</li>
<li>Each session stores a list of session variables (name/value string pairs)</li>
<li>Can easily create, modify, delete, and retrieve session variables</li>
<li>Configurable settings<ul>
<li>Rolling sessions (re-set session ID cookie with every response)</li>
<li>Session ID cookie <code>Max-Age</code> and <code>Expire</code> attribute values</li>
<li>Maximum stale time before a session expires server-side</li>
<li>Time interval between purging expired sessions</li>
<li>Max number of sessions allowed in database</li>
</ul>
</li>
<li>Thread-safe</li>
<li>Can be used with C or C++ projects</li>
</ul>
<h1><a class="anchor" id="setup"></a>
Setup</h1>
<p>To set up the sessions plugin on the server-side:</p>
<ol type="1">
<li>Make sure to compile your program with <a class="el" href="sessions_8c.html">plugin/sessions.c</a> and <a class="el" href="threads_8c.html">plugin/threads.c</a>.</li>
<li>Enable cookies by compiling all gSOAP source code with <code>-DWITH_COOKIES</code>. Cookies are required for tracking session IDs.</li>
<li>Enable HTTPS (compile with <code>-DWITH_OPENSSL</code> or <code>-DWITH_GNUTLS</code> or link with <code>-lgsoapssl</code>/<code>-lgsoapssl++</code>).</li>
</ol>
<dl class="section note"><dt>Note</dt><dd>While it is not a requirement to use HTTPS with this plugin, it is <b>strongly recommended</b> to use HTTPS. This is because the session ID cookies can be intercepted if not encrypted with SSL/TLS. Cookies are automatically sent with the Secure flag enabled when SSL is enabled. The HttpOnly flag is automatically enabled for all cookies in order to prevent XSS attacks.</dd></dl>
<h1><a class="anchor" id="usage"></a>
Basic Usage</h1>
<p>Client-side usage is automatic, provided that the client supports cookies and the server has properly configured the plugin. If the client is a gSOAP application, make sure to compile with <code>-DWITH_COOKIES</code>.</p>
<p>For server-side usage, register the plugin with:</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include "<a class="code" href="sessions_8h.html">plugin/sessions.h</a>"</span></div>
<div class="line"></div>
<div class="line"><span class="keyword">struct </span>soap *soap = soap_new();</div>
<div class="line">soap_register_plugin(soap, <a class="code" href="sessions_8h.html#aad73583096a7750438cc7f622aeed575">sessions</a>);</div>
</div><!-- fragment --><p>If you are using a server object in C++ generated with soappcpp2 option <code>-j</code>:</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include "<a class="code" href="sessions_8h.html">plugin/sessions.h</a>"</span></div>
<div class="line"></div>
<div class="line">soap_register_plugin(server.soap, <a class="code" href="sessions_8h.html#aad73583096a7750438cc7f622aeed575">sessions</a>);</div>
</div><!-- fragment --><p>For brevity, the <code>struct soap*</code> version will be used below. Replace <code>soap</code> with your server object's <code>soap</code> member if necessary.</p>
<p>Start a new session with:</p>
<div class="fragment"><div class="line"><span class="keyword">struct </span><a class="code" href="structsoap__session.html">soap_session</a> *session = <a class="code" href="sessions_8h.html#a61db3eb7e302105558a0871e120fa108">soap_start_session</a>(soap, <span class="stringliteral">"domain"</span>, <span class="stringliteral">"path"</span>); </div>
</div><!-- fragment --><p>This creates a new session with a random 128-bit session ID and the default settings (see section: <a class="el" href="index.html#settings">Settings</a>). If the client already has a session ID cookie with name <code>SESSION_COOKIE_NAME</code> and the given <code>domain</code> and <code>path</code>, and that ID refers to a valid session, that existing session will be returned instead.</p>
<dl class="section note"><dt>Note</dt><dd>For all of the sessions plugin function calls, <code>domain</code> and <code>path</code> arguments are required. These must match the values that were given when the session was created, otherwise the client's session ID cookie won't be found. The <code>domain</code> and <code>path</code> arguments may be set to <code>NULL</code> to use the current values given by the <code>soap</code> context's <code>cookie_domain</code> and <code>cookie_path</code> members:</dd>
<dd>
<table class="doxtable">
<tr>
<th>Attribute </th><th>Value </th></tr>
<tr>
<td><code>const char *cookie_domain</code> </td><td>MUST be set to the domain (host) of the service </td></tr>
<tr>
<td><code>const char *cookie_path</code> </td><td>MAY be set to the default path to the service (defaults to '<code>/</code>') </td></tr>
</table>
</dd>
<dd>
These rules also apply to the cookies used for tracking session IDs. See the <a href="http://genivia.com/doc/soapdoc2.html">gSOAP User Guide</a> for more information on how gSOAP handles cookies.</dd></dl>
<p>For example, to create a session on localhost:8080 that is valid on any path:</p>
<div class="fragment"><div class="line">soap->cookie_domain = <span class="stringliteral">"localhost:8080"</span>;</div>
<div class="line"><span class="keyword">struct </span><a class="code" href="structsoap__session.html">soap_session</a> *session = <a class="code" href="sessions_8h.html#a61db3eb7e302105558a0871e120fa108">soap_start_session</a>(soap, NULL, NULL); </div>
</div><!-- fragment --><p>To create a new session variable or modify an existing session variable inside that session:</p>
<div class="fragment"><div class="line"><a class="code" href="sessions_8h.html#a60cae529297cd676f6781328c0f39cd5">soap_set_session_var</a>(soap, <span class="stringliteral">"session_var_name"</span>, <span class="stringliteral">"session_var_value"</span>, NULL, NULL);</div>
</div><!-- fragment --><p>To access the value of that session variable:</p>
<div class="fragment"><div class="line"><span class="keyword">const</span> <span class="keywordtype">char</span> *value = <a class="code" href="sessions_8h.html#a9ef5df49d2579505149b4f7ca5c388cd">soap_get_session_var</a>(soap, <span class="stringliteral">"session_var_name"</span>, NULL, NULL);</div>
</div><!-- fragment --><p>To delete that session variable:</p>
<div class="fragment"><div class="line"><a class="code" href="sessions_8h.html#a111decf2a202afda5381ada3d6904d06">soap_clr_session_var</a>(soap, <span class="stringliteral">"session_var_name"</span>, NULL, NULL);</div>
</div><!-- fragment --><p>Consider changing the session's <code>rolling</code>, <code>cookie_maxage</code>, <code>max_inactive_secs</code> settings from their defaults. Read more about these in the <a class="el" href="index.html#settings">Settings</a> section.</p>
<h1><a class="anchor" id="example"></a>
Simple Calculator Server (C) Example</h1>
<p>We will show how to extend the simple calculator server example (in C) to keep track of the client's last calculated value with a session variable.</p>
<p>Make sure to register the plugin and set the default <code>domain</code> and <code>path</code>. After calling <code>soap_destroy</code> and <code>soap_end</code>, we should also free the internal cookie database (or call <code>soap_done</code>):</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include "plugin/session.h"</span></div>
<div class="line">...</div>
<div class="line">struct soap soap;</div>
<div class="line">soap_init(&soap);</div>
<div class="line">soap_register_plugin(&soap, <a class="code" href="sessions_8h.html#aad73583096a7750438cc7f622aeed575">sessions</a>);</div>
<div class="line">soap.cookie_domain = <span class="stringliteral">"localhost:8080"</span>;</div>
<div class="line">soap.cookie_path = <span class="stringliteral">"/"</span>;</div>
<div class="line">... <span class="comment">// set up the service and serve requests</span></div>
<div class="line">soap_destroy(&soap);</div>
<div class="line">soap_end(&soap);</div>
<div class="line">soap_free_cookies(&soap);</div>
</div><!-- fragment --><p>Now in each of our calculator service operations (<code>ns__add</code>, <code>ns__sub</code>, etc.), we can update the <code>lastCalculation</code> session variable in our current session:</p>
<div class="fragment"><div class="line"><span class="keywordtype">int</span> ns__add(<span class="keyword">struct</span> soap *soap, <span class="keywordtype">double</span> a, <span class="keywordtype">double</span> b, <span class="keywordtype">double</span> *result)</div>
<div class="line">{ </div>
<div class="line"> (void)soap; *result = a + b;</div>
<div class="line"> </div>
<div class="line"> <span class="comment">// make sure we have a session </span></div>
<div class="line"> </div>
<div class="line"> <span class="keywordflow">if</span> (!<a class="code" href="sessions_8h.html#aa0174ffa84386ab41f9e1d2ba8794d04">soap_get_session</a>(soap, NULL, NULL))</div>
<div class="line"> {</div>
<div class="line"> <span class="comment">// no current session, create a new one</span></div>
<div class="line"> </div>
<div class="line"> <span class="keywordflow">if</span> (!<a class="code" href="sessions_8h.html#a61db3eb7e302105558a0871e120fa108">soap_start_session</a>(soap, NULL, NULL))</div>
<div class="line"> <span class="keywordflow">return</span> SOAP_ERR; <span class="comment">// session creation failed</span></div>
<div class="line"> </div>
<div class="line"> <span class="comment">// configure session settings</span></div>
<div class="line"> <a class="code" href="sessions_8h.html#ab4bfe8aeec045e9f31bd860fa4627ef8">soap_set_session_rolling</a>(soap, 1, NULL, NULL);</div>
<div class="line"> <a class="code" href="sessions_8h.html#a7455f112585da290cf814b7b002496a6">soap_set_session_cookie_maxage</a>(soap, 30, NULL, NULL);</div>
<div class="line"> <a class="code" href="sessions_8h.html#aaa12654f17fa42f4cdd93a3a11aec435">soap_set_session_max_inactive_secs</a>(soap, 30, NULL, NULL);</div>
<div class="line"> }</div>
<div class="line"> </div>
<div class="line"> <span class="comment">// update `lastCalculation` session variable </span></div>
<div class="line"> </div>
<div class="line"> <span class="keywordtype">char</span> calculation[80];</div>
<div class="line"> sprintf(calculation, <span class="stringliteral">"add %f %f, result = %f"</span>, a, b, *result);</div>
<div class="line"> <a class="code" href="sessions_8h.html#a60cae529297cd676f6781328c0f39cd5">soap_set_session_var</a>(soap, <span class="stringliteral">"lastCalculation"</span>, calculation, NULL, NULL);</div>
<div class="line"> </div>
<div class="line"> <span class="keywordflow">return</span> SOAP_OK;</div>
<div class="line">} </div>
</div><!-- fragment --><p>If we want to allow the client to access their last calculation, add another service operation to retrieve the <code>lastCalculation</code> session variable:</p>
<div class="fragment"><div class="line"><span class="keywordtype">int</span> ns__getLastCalculation(<span class="keyword">struct</span> soap *soap, <span class="keywordtype">char</span> **r)</div>
<div class="line">{ </div>
<div class="line"> <span class="keyword">const</span> <span class="keywordtype">char</span> *lastCalculation = <a class="code" href="sessions_8h.html#a9ef5df49d2579505149b4f7ca5c388cd">soap_get_session_var</a>(soap, <span class="stringliteral">"lastCalculation"</span>, NULL, NULL);</div>
<div class="line"> <span class="keywordflow">if</span> (!lastCalculation) </div>
<div class="line"> lastCalculation = <span class="stringliteral">"None"</span>;</div>
<div class="line"> <span class="keywordflow">if</span> ((*r = (<span class="keywordtype">char</span>*)soap_malloc(soap, strlen(lastCalculation)+1)))</div>
<div class="line"> strcpy(*r, lastCalculation);</div>
<div class="line"> <span class="keywordflow">return</span> SOAP_OK;</div>
<div class="line">}</div>
</div><!-- fragment --><h1><a class="anchor" id="api"></a>
Sessions Plugin API</h1>
<p>This section describes the Sessions Plugin API.</p>
<dl class="section note"><dt>Note</dt><dd>The term <em>session ID cookie</em> refers to a cookie with the name <code>SESSION_COOKIE_NAME</code> (see section: <a class="el" href="index.html#settings">Settings</a>), the given <code>domain</code> and <code>path</code> (see section: <a class="el" href="index.html#usage">Basic Usage</a>), and a random 128-bit session ID as the value. The term <em>current session</em> refers to the session in the database identified by the client's session ID cookie.</dd>
<dd>
The arguments <code>domain</code> and <code>path</code> may be set to <code>NULL</code> to use the current values given by <code>soap->cookie_domain</code> and <code>soap->cookie_path</code> (see section: <a class="el" href="index.html#usage">Basic Usage</a>).</dd></dl>
<p>The sessions plugin provides the following API for server-side session management:</p>
<table class="doxtable">
<tr>
<th>Session Plugin Function Description </th></tr>
<tr>
<td><em><b>struct soap_session*</b> soap_start_session(<b>struct soap *</b> soap, <b>const char *</b>domain, <b>const char *</b>path);</em><br />
Create a session in the database and a session ID cookie. Behaves the same as <code>soap_get_session</code> if the client already has a valid session ID cookie. Returns pointer to the session node, or <code>NULL</code> if the session could not be created. </td></tr>
<tr>
<td><em><b>struct soap_session*</b> soap_get_session(<b>struct soap *</b>soap, <b>const char *</b>domain, <b>const char *</b>path);</em><br />
Get the current session. Can be used as a 'touch'. Returns pointer to the session node, or <code>NULL</code> if the session is not found or is expired. </td></tr>
<tr>
<td><em><b>int</b> soap_get_num_sessions(<b>struct soap *</b>soap, <b>const char *</b>domain, <b>const char *</b>path);</em><br />
Get the number of sessions in the database. Returns <code>-1</code> if the session is not found or is expired. </td></tr>
<tr>
<td><em><b>struct soap_session*</b> soap_regenerate_session_id(<b>struct soap * </b>soap, <b>const char *</b>domain, <b>const char *</b>path);</em><br />
Create a new session ID for the current session and update the session ID cookie. Returns pointer to the session node, or <code>NULL</code> if the session is not found or is expired. </td></tr>
<tr>
<td><em><b>int</b> soap_get_num_session_vars(<b>struct soap *</b>soap, <b>const char *</b>domain, <b>const char *</b>path);</em><br />
Get the number of session variables in the current session. Returns <code>-1</code> if the session is not found or is expired. </td></tr>
<tr>
<td><em><b>void</b> soap_end_session(<b>struct soap *</b>soap, <b>const char * </b>domain, <b>const char *</b>path);</em><br />
Delete the current session from the database and clear the client's session ID cookie. </td></tr>
<tr>
<td><em><b>void</b> soap_end_sessions(<b>struct soap *</b>soap, <b>const char * </b>domain, <b>const char *</b>path);</em><br />
Delete all sessions in the database and clear the current session ID cookie. </td></tr>
<tr>
<td><em><b>struct soap_session_var*</b> soap_set_session_var(<b>struct soap * </b>soap, <b>const char *</b>name, <b>const char *</b>value, <b>const char </b>domain, <b>const char *</b>path);</em><br />
Set a session variable with the given <code>name</code> and <code>value</code> in the current session, overwring any old <code>value</code>. Returns pointer to the session variable node, or <code>NULL</code> if the session is not found or is expired. </td></tr>
<tr>
<td><em><b>const char*</b> soap_get_session_var(<b>struct soap *</b>soap, <b> const char *</b>name, <b>const char *</b>domain, <b>const char *</b>path); </em><br />
Get the <code>value</code> of the session variable with the given <code>name</code> in the current session. Returns <code>NULL</code> if the session is not found or is expired. </td></tr>
<tr>
<td><em><b>void</b> soap_clr_session_var(<b>struct soap *</b>soap, <b>const char *</b>name, <b>const char *</b>domain, <b>const char *</b>path);</em><br />
Delete the session variable with the given <code>name</code> in the current session. </td></tr>
<tr>
<td><em><b>void</b> soap_clr_session_vars(<b>struct soap</b> *soap, <b>const char</b> *domain, <b>const char</b> *path);</em> <br />
Delete all session variables in the current session. </td></tr>
</table>
<p>For managing session settings (see section: <a class="el" href="index.html#settings">Settings</a>), the following API is provided:</p>
<table class="doxtable">
<tr>
<th>Session Plugin Function Description (Settings / Misc.) </th></tr>
<tr>
<td><em><b>int</b> soap_set_session_rolling(<b>struct soap * </b>soap, <b>int</b> rolling, <b>const char *</b>domain, <b>const char * </b>path);</em><br />
Set the <code>rolling</code> setting for the current session. Zero (non-rolling) means the session ID cookie is only set when the session is first created. Non-zero (rolling) means the session ID cookie will be re-set on every response. If successful, returns SOAP_OK, or SOAP_ERR otherwise. </td></tr>
<tr>
<td><em><b>int</b> soap_get_session_rolling(<b>struct soap * </b>soap, <b>const char *</b>domain, <b>const char *</b>path);</em><br />
Get the <code>rolling</code> setting for the current session. Returns <code>-1</code> if the session is not found or is expired. </td></tr>
<tr>
<td><em><b>int</b> soap_set_session_cookie_maxage(<b>struct soap * </b>soap, <b>long</b> maxage, <b>const char *</b>domain, <b>const char * </b>path);</em><br />
Set the <code>cookie_maxage</code> member for the current session. This will be used to set the session ID cookie's <code>Max-Age</code> and <code>Expires</code> attributes. <code>-1</code> means the cookie will have no <code>Max-Age</code> or <code>Expires</code> attributes. If successful, returns SOAP_OK, or SOAP_ERR otherwise. </td></tr>
<tr>
<td><em><b>long</b> soap_get_session_cookie_maxage(<b>struct soap * </b>soap, <b>const char *</b>domain, <b>const char *</b>path);</em><br />
Get the <code>cookie_maxage</code> member for the current session. Returns <code>0</code> if the session is not found or is expired. </td></tr>
<tr>
<td><em><b>int</b> soap_set_session_max_inactive_secs(<b>struct soap * </b>soap, <b>long</b> max, <b>const char *</b>domain, <b>const char * </b>path);</em><br />
Set the <code>max_inactive_secs</code> member for the current session. This is the maximum amount of stale time in seconds before a session is marked as expired (to be purged) on the server-side. <code>-1</code> means the session will never expire. If successful, returns SOAP_OK, or SOAP_ERR otherwise. </td></tr>
<tr>
<td><em><b>long</b> soap_get_session_max_inactive_secs(<b>struct soap * </b>soap, <b>const char *</b>domain, <b>const char *</b>path);</em><br />
Get the <code>max_inactive_secs</code> member for the current session. Returns <code>0</code> if the session is not found or is expired. </td></tr>
<tr>
<td><em><b>struct soap_session*</b> soap_get_sessions_head(<b></b>);</em> <br />
Get <code>soap_sessions</code>, the first node in the sessions linked list. Not necessary unless low-level list management is needed (see section: <a class="el" href="index.html#internals">The Internals</a>). </td></tr>
</table>
<h1><a class="anchor" id="settings"></a>
Settings</h1>
<p>In <code>plugins/session.h</code>, the following constants are defined:</p>
<table class="doxtable">
<tr>
<th>Name </th><th>Default </th><th>Description </th></tr>
<tr>
<td><code>SESSION_COOKIE_NAME</code> </td><td><code>"GSOAP_SESSIONID"</code> </td><td>The name to use for session ID cookies. </td></tr>
<tr>
<td><code>SESSION_MAX</code> </td><td><code>8192</code> </td><td>The max number of sessions allowed in the database. Any attempt to create more sessions than this will fail. </td></tr>
<tr>
<td><code>SESSIONS_DEFAULT_MAX_INACTIVE_SECS</code> </td><td><code>300</code> </td><td>The default time in seconds for sessions' <code>max_inactive_secs</code> member. <code>-1</code> means the session will never expire server-side. </td></tr>
<tr>
<td><code>SESSION_PURGE_INTERVAL</code> </td><td><code>300</code> </td><td>On every session database access, the time since the last database purge is checked. If it's been longer than this interval (in seconds), any expired sessions will be purged with <code><a class="el" href="sessions_8c.html#af89638dcb0fed58b795c3134f847d69d" title="Removes all sessions that have been stale longer than their max_inactive_secs allows. -1 max_inactive_secs means the session will never expire. The when parameter is usually the current time, i.e. time(NULL) to purge sessions that expire after the when time. ">soap_purge_sessions()</a></code>. <code>0</code> means a purge will occcur on every database access. <code>-1</code> means a purge will never occur. </td></tr>
</table>
<p>Set these values to whatever makes sense for your application.</p>
<p>In each session node, the following settings are declared:</p>
<table class="doxtable">
<tr>
<th>Name </th><th>Default </th><th>Description </th></tr>
<tr>
<td><code>rolling</code> </td><td><code>0</code> </td><td>Non-rolling (<code>0</code>) means the session ID cookie is only set when the session is first created. Rolling (non-<code>0</code>) means the session ID cookie will be re-set on every response after any part of the session has been touched. </td></tr>
<tr>
<td><code>cookie_maxage</code> </td><td><code>-1</code> </td><td>This will be used to set the session ID cookie's <code>Max-Age</code> and <code>Expires</code> attributes. <code>-1</code> means the cookie will have no <code>Max-Age</code> or <code>Expires</code> attributes. </td></tr>
<tr>
<td><code>max_inactive_secs</code> </td><td><code>SESSIONS_DEFAULT_MAX_INACTIVE_SECS</code> </td><td>This is the maximum amount of stale time in seconds before a session is marked as expired (to be purged) on the server-side. <code>-1</code> means the session will never expire server-side. This should probably be set equal to <code>cookie_maxage</code> unless that value is <code>-1</code>. </td></tr>
</table>
<dl class="section note"><dt>Note</dt><dd>These settings should not be changed directly. See the <a class="el" href="index.html#api">Sessions Plugin API</a> section for functions to manage these settings.</dd></dl>
<h1><a class="anchor" id="internals"></a>
The Internals</h1>
<p>The session database is stored as a linked list pointed to by <code>soap_sessions</code> (accessible by calling <code><a class="el" href="sessions_8c.html#a539448f198293a94eae014318369036f" title="Gets soap_sessions (first node in sessions linked list). ">soap_get_sessions_head()</a></code>). Session nodes are of type <code>struct <a class="el" href="structsoap__session.html" title="A session node. ">soap_session</a></code> and are declared as:</p>
<div class="fragment"><div class="line"><span class="keyword">struct </span><a class="code" href="structsoap__session.html">soap_session</a></div>
<div class="line">{ </div>
<div class="line"> <span class="keyword">struct </span><a class="code" href="structsoap__session.html">soap_session</a> *<a class="code" href="structsoap__session.html#a05ce834ed2a71f79cd61e4c81a368c98">next</a>;</div>
<div class="line"> <span class="keyword">const</span> <span class="keywordtype">char</span> *<a class="code" href="structsoap__session.html#ac55bd514bf7dcc854a1df6a32345c707">id</a>;</div>
<div class="line"> <span class="keyword">struct </span><a class="code" href="structsoap__session__var.html">soap_session_var</a> *<a class="code" href="structsoap__session.html#a11fdfef3b6f2e20a842cb79ddfb94209">session_vars</a>;</div>
<div class="line"> <span class="keyword">struct </span><a class="code" href="structsoap__session__var.html">soap_session_var</a> *<a class="code" href="structsoap__session.html#a24f1d15feb594b9085ff6c9a222f35da">session_vars_tail</a>;</div>
<div class="line"> <span class="keywordtype">int</span> <a class="code" href="structsoap__session.html#a468b65a9d7dc6b30448cb1a56e8b37f9">num_session_vars</a>; <span class="comment">// the total number of session_vars we have in this session </span></div>
<div class="line"> <span class="keywordtype">long</span> <a class="code" href="structsoap__session.html#ab6b4ba002662300fd4ff8ed43e38b2a1">cookie_maxage</a>; <span class="comment">// client time in seconds before the cookie expires (-1 for session cookie) </span></div>
<div class="line"> <span class="keywordtype">int</span> <a class="code" href="structsoap__session.html#a6e46a225e7cf029a1dfc1c6f9747365b">rolling</a>; <span class="comment">// whether or not we should set the cookie's maxage on every response </span></div>
<div class="line"> time_t <a class="code" href="structsoap__session.html#a865c543823ca04a50d91e71457964829">last_touched</a>; <span class="comment">// time that we last touched this session or its vars </span></div>
<div class="line"> <span class="keywordtype">long</span> <a class="code" href="structsoap__session.html#aaf697411a908c1d6a670f4a197b98c23">max_inactive_secs</a>; <span class="comment">// server time in seconds before inactive session expires (-1 to never expire) </span></div>
<div class="line"> <span class="comment">// this should usually be at least as high as cookie_maxage </span></div>
<div class="line">};</div>
</div><!-- fragment --><p>The <code>session_vars</code> member is a pointer to the session's linked list of session variables. Session variable nodes are of type <code>struct <a class="el" href="structsoap__session__var.html" title="A session variable node. Session variables are name-value pairs. ">soap_session_var</a></code> and are declared as:</p>
<div class="fragment"><div class="line"><span class="keyword">struct </span><a class="code" href="structsoap__session__var.html">soap_session_var</a></div>
<div class="line">{</div>
<div class="line"> <span class="keyword">struct </span><a class="code" href="structsoap__session__var.html">soap_session_var</a> *<a class="code" href="structsoap__session__var.html#ae8a36a82dacb99d70daf83afe2523ff2">next</a>;</div>
<div class="line"> <span class="keyword">const</span> <span class="keywordtype">char</span> *<a class="code" href="structsoap__session__var.html#af0c60d4a99f97d7e56ed6b5569822329">name</a>;</div>
<div class="line"> <span class="keyword">const</span> <span class="keywordtype">char</span> *<a class="code" href="structsoap__session__var.html#ac11005f964c6acd34a4c27628297f437">value</a>;</div>
<div class="line">};</div>
</div><!-- fragment --> </div></div><!-- contents -->
<hr class="footer">
<address class="footer">
Copyright (C) 2016, Robert van Engelen, Genivia Inc., All Rights Reserved.
</address>
<address class="footer"><small>
Converted on Wed Aug 17 2016 10:37:47 by <a target="_blank" href="http://www.doxygen.org/index.html">Doxygen</a> 1.8.10</small></address>
<br>
<div style="height: 246px; background: #DBDBDB;">
</body>
</html>
