|  | Home | Documentation | sessions.c File Reference updated by Robert van Engelen |

Functions | Variables
sessions.c File Reference
`#include "sessions.h"`
Include dependency graph for sessions.c:

## Functions

static int | sessions_init (struct soap *soap)
| Used by plugin registry function.
static void | sessions_delete (struct soap *soap, struct soap_plugin *p)
| Deletes all sessions. Called when plugin is ended by first caller.
SOAP_FMAC1 int SOAP_FMAC2 | sessions (struct soap *soap, struct soap_plugin *p, void *arg)
| Plugin registry function, invoked by soap_register_plugin.
SOAP_FMAC1 void SOAP_FMAC2 | soap_session_cookie_create (struct soap *soap, const char *value, const char *domain, const char *path, long maxage)
| Intended for internal plugin use. Creates a cookie that will be sent to the client, named SESSION_COOKIE_NAME with the given value, domain, and path.
SOAP_FMAC1 void SOAP_FMAC2 | soap_session_cookie_delete (struct soap *soap, const char *domain, const char *path)
| Intended for internal plugin use. Creates a cookie that will be sent to the client, named SESSION_COOKIE_NAME with the given domain and path. The value will be empty and it will be set to expire when the client recieves it. This ensures the session ID is no longer in the client's cookie.
SOAP_FMAC1 struct soap_session *SOAP_FMAC2 | soap_session_internal_find (struct soap *soap, const char *domain, const char *path, time_t when)
| Intended for internal plugin use. Find the current session with domain and path. Returns NULL if not found or if the session is expired (for normal use, set when to time(NULL)). Will also clear the cookie if the session is expired.
SOAP_FMAC1 struct soap_session *SOAP_FMAC2 | soap_get_sessions_head ()
| Gets soap_sessions (first node in sessions linked list).
SOAP_FMAC1 void SOAP_FMAC2 | soap_purge_sessions (struct soap *soap, const char *domain, const char *path, time_t when)
| 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_FMAC1 int SOAP_FMAC2 | soap_get_num_sessions (struct soap *soap, const char *domain, const char *path)
| Gets the number of sessions in the database.
SOAP_FMAC1 struct soap_session *SOAP_FMAC2 | soap_get_session (struct soap *soap, const char *domain, const char *path)
| Finds the session identified by the cookie with name SESSION_COOKIE_NAME and the given domain and path. Updates session's last_touched to now. Returns NULL if not found.
SOAP_FMAC1 struct soap_session *SOAP_FMAC2 | soap_start_session (struct soap *soap, const char *domain, const char *path)
| Creates a new session with a random 128-bit ID. A cookie will be created with name SESSION_COOKIE_NAME and the given domain and path. If there already exists a session ID cookie, the only action will be updating the session's last_touched to now. Returns a pointer to the session.
SOAP_FMAC1 struct soap_session *SOAP_FMAC2 | soap_regenerate_session_id (struct soap *soap, const char *domain, const char *path)
| The session ID for the current session (identified by the cookie with name SESSION_COOKIE_NAME and the given domain and path) will be set to a new random 128-bit ID. Also updates the cookie. Returns a pointer to the session.
SOAP_FMAC1 void SOAP_FMAC2 | soap_end_sessions (struct soap *soap, const char *domain, const char *path)
| Frees all sessions in database.
SOAP_FMAC1 void SOAP_FMAC2 | soap_end_session (struct soap *soap, const char *domain, const char *path)
| Frees the current session (identified by the cookie with name SESSION_COOKIE_NAME and the given domain and path). Also clears the cookie.
SOAP_FMAC1 long SOAP_FMAC2 | soap_get_session_cookie_maxage (struct soap *soap, const char *domain, const char *path)
| Gets the cookie_maxage for the current session (identified by the cookie with name SESSION_COOKIE_NAME and the given domain and path). -1 means the cookie is a session cookie. 0 means a session was not found or is expired.
SOAP_FMAC1 int SOAP_FMAC2 | soap_set_session_cookie_maxage (struct soap *soap, long maxage, const char *domain, const char *path)
| Sets the cookie_maxage for the current session (identified by the cookie with name SESSION_COOKIE_NAME and the given domain and path). -1 means the cookie will be a session cookie. If successful, returns SOAP_OK, or SOAP_ERR otherwise.
SOAP_FMAC1 long SOAP_FMAC2 | soap_get_session_max_inactive_secs (struct soap *soap, const char *domain, const char *path)
| Gets the max_inactive_secs for the current session (identified by the cookie with name SESSION_COOKIE_NAME and the given domain and path). -1 means the session will never expire. 0 means the session wasn't found or is expired.
SOAP_FMAC1 int SOAP_FMAC2 | soap_set_session_max_inactive_secs (struct soap *soap, long max, const char *domain, const char *path)
| Sets the max_inactive_secs for the current session (identified by the cookie with name SESSION_COOKIE_NAME and the given domain and path). -1 means the session will never expire. If successful, returns SOAP_OK, or SOAP_ERR otherwise.
SOAP_FMAC1 int SOAP_FMAC2 | soap_get_session_rolling (struct soap *soap, const char *domain, const char *path)
| Gets the rolling flag for the current session (identified by the cookie with name SESSION_COOKIE_NAME and the given domain and path). -1 means the session was not found or is expired.
SOAP_FMAC1 int SOAP_FMAC2 | soap_set_session_rolling (struct soap *soap, int rolling, const char *domain, const char *path)
| Sets the rolling flag for the current session (identified by the cookie with name SESSION_COOKIE_NAME and the given domain and path). If successful, returns SOAP_OK, or SOAP_ERR otherwise.
SOAP_FMAC1 int SOAP_FMAC2 | soap_get_num_session_vars (struct soap *soap, const char *domain, const char *path)
| Gets the number of sessions variables in the current session (identified by the cookie with name SESSION_COOKIE_NAME and the given domain and path). Returns -1 if the session does not exist.
SOAP_FMAC1 const char *SOAP_FMAC2 | soap_get_session_var (struct soap *soap, const char *name, const char *domain, const char *path)
| Returns session_var value by name in the current session (identified by the cookie with name SESSION_COOKIE_NAME and the given domain and path). Returns NULL if not found.
SOAP_FMAC1 struct soap_session_var *SOAP_FMAC2 | soap_set_session_var (struct soap *soap, const char *name, const char *value, const char *domain, const char *path)
| Add new session_var with the given name and value to the current session (identified by the cookie with name SESSION_COOKIE_NAME and the given domain and path). If the name is already used, the value is re-written. If successful, returns pointer to a session_var node in the session's linked list, or NULL otherwise.
SOAP_FMAC1 void SOAP_FMAC2 | soap_clr_session_vars (struct soap *soap, const char *domain, const char *path)
| Frees all session vars in the current session (identified by the cookie with name SESSION_COOKIE_NAME and the given domain and path).
SOAP_FMAC1 void SOAP_FMAC2 | soap_clr_session_var (struct soap *soap, const char *name, const char *domain, const char *path)
| Frees session var with the given name in the current session (identified by the cookie with name SESSION_COOKIE_NAME and the given domain and path).

## Variables

const char | sessions_id [] = SESSIONS_ID
static struct soap_session * | soap_sessions = NULL
static struct soap_session * | soap_sessions_tail = NULL
static int | num_sessions = 0
static time_t | last_purged_sessions
static MUTEX_TYPE | sessions_lock = MUTEX_INITIALIZER

## Function Documentation

## ◆ sessions()

SOAP_FMAC1 int SOAP_FMAC2 sessions | ( | struct soap * | soap,
|  | struct soap_plugin * | p,
|  | void * | arg )

Plugin registry function, invoked by soap_register_plugin.

## ◆ sessions_delete()

void sessions_delete | ( | struct soap * | soap,
|  | struct soap_plugin * | p )

static

Deletes all sessions. Called when plugin is ended by first caller.

## ◆ sessions_init()

int sessions_init | ( | struct soap * | soap | ) |

static

Used by plugin registry function.

## ◆ soap_clr_session_var()

SOAP_FMAC1 void SOAP_FMAC2 soap_clr_session_var | ( | struct soap * | soap,
|  | const char * | name,
|  | const char * | domain,
|  | const char * | path )

Frees session var with the given name in the current session (identified by the cookie with name SESSION_COOKIE_NAME and the given domain and path).

## ◆ soap_clr_session_vars()

SOAP_FMAC1 void SOAP_FMAC2 soap_clr_session_vars | ( | struct soap * | soap,
|  | const char * | domain,
|  | const char * | path )

Frees all session vars in the current session (identified by the cookie with name SESSION_COOKIE_NAME and the given domain and path).

## ◆ soap_end_session()

SOAP_FMAC1 void SOAP_FMAC2 soap_end_session | ( | struct soap * | soap,
|  | const char * | domain,
|  | const char * | path )

Frees the current session (identified by the cookie with name SESSION_COOKIE_NAME and the given domain and path). Also clears the cookie.

## ◆ soap_end_sessions()

SOAP_FMAC1 void SOAP_FMAC2 soap_end_sessions | ( | struct soap * | soap,
|  | const char * | domain,
|  | const char * | path )

Frees all sessions in database.

## ◆ soap_get_num_session_vars()

SOAP_FMAC1 int SOAP_FMAC2 soap_get_num_session_vars | ( | struct soap * | soap,
|  | const char * | domain,
|  | const char * | path )

Gets the number of sessions variables in the current session (identified by the cookie with name SESSION_COOKIE_NAME and the given domain and path). Returns -1 if the session does not exist.

## ◆ soap_get_num_sessions()

SOAP_FMAC1 int SOAP_FMAC2 soap_get_num_sessions | ( | struct soap * | soap,
|  | const char * | domain,
|  | const char * | path )

Gets the number of sessions in the database.

## ◆ soap_get_session()

SOAP_FMAC1 struct soap_session *SOAP_FMAC2 soap_get_session | ( | struct soap * | soap,
|  | const char * | domain,
|  | const char * | path )

Finds the session identified by the cookie with name SESSION_COOKIE_NAME and the given domain and path. Updates session's last_touched to now. Returns NULL if not found.

## ◆ soap_get_session_cookie_maxage()

SOAP_FMAC1 long SOAP_FMAC2 soap_get_session_cookie_maxage | ( | struct soap * | soap,
|  | const char * | domain,
|  | const char * | path )

Gets the cookie_maxage for the current session (identified by the cookie with name SESSION_COOKIE_NAME and the given domain and path). -1 means the cookie is a session cookie. 0 means a session was not found or is expired.

## ◆ soap_get_session_max_inactive_secs()

SOAP_FMAC1 long SOAP_FMAC2 soap_get_session_max_inactive_secs | ( | struct soap * | soap,
|  | const char * | domain,
|  | const char * | path )

Gets the max_inactive_secs for the current session (identified by the cookie with name SESSION_COOKIE_NAME and the given domain and path). -1 means the session will never expire. 0 means the session wasn't found or is expired.

## ◆ soap_get_session_rolling()

SOAP_FMAC1 int SOAP_FMAC2 soap_get_session_rolling | ( | struct soap * | soap,
|  | const char * | domain,
|  | const char * | path )

Gets the rolling flag for the current session (identified by the cookie with name SESSION_COOKIE_NAME and the given domain and path). -1 means the session was not found or is expired.

## ◆ soap_get_session_var()

SOAP_FMAC1 const char *SOAP_FMAC2 soap_get_session_var | ( | struct soap * | soap,
|  | const char * | name,
|  | const char * | domain,
|  | const char * | path )

Returns session_var value by name in the current session (identified by the cookie with name SESSION_COOKIE_NAME and the given domain and path). Returns NULL if not found.

## ◆ soap_get_sessions_head()

SOAP_FMAC1 struct soap_session *SOAP_FMAC2 soap_get_sessions_head | ( |  | ) |

Gets soap_sessions (first node in sessions linked list).

## ◆ soap_purge_sessions()

SOAP_FMAC1 void SOAP_FMAC2 soap_purge_sessions | ( | struct soap * | soap,
|  | const char * | domain,
|  | const char * | path,
|  | time_t | when )

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.

This is called internally every time a session or a session_var is accessed, so it shouldn't ever be necessary to manually call this function.

Only will purge when the last time we purged was more than SESSION_PURGE_INTERVAL seconds ago (defined in sessions.h). SESSION_PURGE_INTERVAL == -1 means never purge. SESSION_PURGE_INTERVAL == 0 means always purge.

## ◆ soap_regenerate_session_id()

SOAP_FMAC1 struct soap_session *SOAP_FMAC2 soap_regenerate_session_id | ( | struct soap * | soap,
|  | const char * | domain,
|  | const char * | path )

The session ID for the current session (identified by the cookie with name SESSION_COOKIE_NAME and the given domain and path) will be set to a new random 128-bit ID. Also updates the cookie. Returns a pointer to the session.

## ◆ soap_session_cookie_create()

SOAP_FMAC1 void SOAP_FMAC2 soap_session_cookie_create | ( | struct soap * | soap,
|  | const char * | value,
|  | const char * | domain,
|  | const char * | path,
|  | long | maxage )

Intended for internal plugin use. Creates a cookie that will be sent to the client, named SESSION_COOKIE_NAME with the given value, domain, and path.

## ◆ soap_session_cookie_delete()

SOAP_FMAC1 void SOAP_FMAC2 soap_session_cookie_delete | ( | struct soap * | soap,
|  | const char * | domain,
|  | const char * | path )

Intended for internal plugin use. Creates a cookie that will be sent to the client, named SESSION_COOKIE_NAME with the given domain and path. The value will be empty and it will be set to expire when the client recieves it. This ensures the session ID is no longer in the client's cookie.

## ◆ soap_session_internal_find()

SOAP_FMAC1 struct soap_session *SOAP_FMAC2 soap_session_internal_find | ( | struct soap * | soap,
|  | const char * | domain,
|  | const char * | path,
|  | time_t | when )

Intended for internal plugin use. Find the current session with domain and path. Returns NULL if not found or if the session is expired (for normal use, set when to time(NULL)). Will also clear the cookie if the session is expired.

## ◆ soap_set_session_cookie_maxage()

SOAP_FMAC1 int SOAP_FMAC2 soap_set_session_cookie_maxage | ( | struct soap * | soap,
|  | long | maxage,
|  | const char * | domain,
|  | const char * | path )

Sets the cookie_maxage for the current session (identified by the cookie with name SESSION_COOKIE_NAME and the given domain and path). -1 means the cookie will be a session cookie. If successful, returns SOAP_OK, or SOAP_ERR otherwise.

## ◆ soap_set_session_max_inactive_secs()

SOAP_FMAC1 int SOAP_FMAC2 soap_set_session_max_inactive_secs | ( | struct soap * | soap,
|  | long | max,
|  | const char * | domain,
|  | const char * | path )

Sets the max_inactive_secs for the current session (identified by the cookie with name SESSION_COOKIE_NAME and the given domain and path). -1 means the session will never expire. If successful, returns SOAP_OK, or SOAP_ERR otherwise.

## ◆ soap_set_session_rolling()

SOAP_FMAC1 int SOAP_FMAC2 soap_set_session_rolling | ( | struct soap * | soap,
|  | int | rolling,
|  | const char * | domain,
|  | const char * | path )

Sets the rolling flag for the current session (identified by the cookie with name SESSION_COOKIE_NAME and the given domain and path). If successful, returns SOAP_OK, or SOAP_ERR otherwise.

## ◆ soap_set_session_var()

SOAP_FMAC1 struct soap_session_var *SOAP_FMAC2 soap_set_session_var | ( | struct soap * | soap,
|  | const char * | name,
|  | const char * | value,
|  | const char * | domain,
|  | const char * | path )

Add new session_var with the given name and value to the current session (identified by the cookie with name SESSION_COOKIE_NAME and the given domain and path). If the name is already used, the value is re-written. If successful, returns pointer to a session_var node in the session's linked list, or NULL otherwise.

## ◆ soap_start_session()

SOAP_FMAC1 struct soap_session *SOAP_FMAC2 soap_start_session | ( | struct soap * | soap,
|  | const char * | domain,
|  | const char * | path )

Creates a new session with a random 128-bit ID. A cookie will be created with name SESSION_COOKIE_NAME and the given domain and path. If there already exists a session ID cookie, the only action will be updating the session's last_touched to now. Returns a pointer to the session.

## Variable Documentation

## ◆ last_purged_sessions

time_t last_purged_sessions

static

Time that we last purged expired sessions

## ◆ num_sessions

int num_sessions = 0

static

Number of sessions in database

## ◆ sessions_id

const char sessions_id[] = SESSIONS_ID

plugin identification for plugin registry

## ◆ sessions_lock

MUTEX_TYPE sessions_lock = MUTEX_INITIALIZER

static

Session database lock

## ◆ soap_sessions

struct soap_session* soap_sessions = NULL

static

Head node of session database (linked list)

## ◆ soap_sessions_tail

struct soap_session* soap_sessions_tail = NULL

static

Tail node of session database