sessions.h File Reference

#include "stdsoap2.h"
#include "threads.h"

Include dependency graph for sessions.h:

This graph shows which files directly or indirectly include this file:

Classes
struct	soap_session
	A session node. More...
struct	soap_session_var
	A session variable node. Session variables are name-value pairs. More...

Macros
#define	SESSIONS_ID   "SESSIONS-1.0"
#define	SESSION_MAX   (8192)
#define	SESSIONS_DEFAULT_MAX_INACTIVE_SECS   (300);
#define	SESSION_PURGE_INTERVAL   (300)

Functions
SOAP_FMAC1 int SOAP_FMAC2	sessions (struct soap *soap, struct soap_plugin *plugin, void *arg)
	Plugin registry function, invoked by soap_register_plugin. More...
SOAP_FMAC1 struct soap_session *SOAP_FMAC2	soap_get_sessions_head ()
	Gets soap_sessions (first node in sessions linked list). More...
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. More...
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. More...
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. More...
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. More...
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. More...
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. More...
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. More...
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. More...
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. More...
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. More...
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. More...
SOAP_FMAC1 void SOAP_FMAC2	soap_end_sessions (struct soap *soap, const char *domain, const char *path)
	Frees all sessions in database. More...
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. More...
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. More...
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. More...
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. More...
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). More...
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). More...

Variables
const char	sessions_id []
static const char	SESSION_COOKIE_NAME [] = "GSOAP_SESSIONID"

Macro Definition Documentation

#define SESSION_MAX   (8192)

Max number of sessions allowed

#define SESSION_PURGE_INTERVAL   (300)

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 soap_session_purge(). A value of 0 means a purge will occcur on every database access. A value of -1 means a purge will never occur.

#define SESSIONS_DEFAULT_MAX_INACTIVE_SECS   (300);

Default max amount of stale time (seconds) server-side before a session is expired

#define SESSIONS_ID   "SESSIONS-1.0"

plugin identification for plugin registry

Function Documentation

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

Plugin registry function, invoked by soap_register_plugin.

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_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_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 void SOAP_FMAC2 soap_end_sessions	(	struct soap *	soap,
		const char *	domain,
		const char *	path
	)

Frees all sessions in database.

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 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 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 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_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 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* 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.

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_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 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 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_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 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 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

const char SESSION_COOKIE_NAME[] = "GSOAP_SESSIONID"

static

Name used for session ID cookies

const char sessions_id[]

plugin identification for plugin registry