nawa::Session Class Reference

#include <nawa/session/Session.h>

Public Member Functions
virtual	~Session ()
	Session (Connection &connection)
std::string	start (std::string sessionId, std::optional< unsigned long > keepalive=std::nullopt)
void	start (nawa::Cookie properties=Cookie())
bool	established () const
bool	isSet (std::string const &key) const
std::any	operator[] (std::string const &key) const
void	set (std::string key, const std::any &value)
void	set (std::string key, char const *value)
template<typename T >
void	set (std::string key, T const &value)
void	unset (std::string const &key)
void	invalidate ()
std::string	getID () const

Public Attributes
friend	RequestHandler

Detailed Description

Class for managing sessions and getting and setting connection-independent session data.

Definition at line 37 of file Session.h.

Constructor & Destructor Documentation

~Session()

virtual nawa::Session::~Session ( )

virtual

Session()

Session::Session ( Connection &  connection )

explicit

Construct a new Session object. This will just store the Connection reference in the object.

Parameters

connection

Reference to the current Connection (for getting and setting cookies).

Definition at line 120 of file Session.cpp.

Member Function Documentation

start() [1/2]

std::string Session::start	(	std::string	sessionId,
		std::optional< unsigned long >	keepalive = std::nullopt
	)

Start the session based on a given session ID (if possible). If a session is already active, this function will just return the current session ID.

Please note that in order to start a new session without sending a session cookie, this overload has to be used, e.g., by passing an empty string for sessionId.

Parameters

sessionId	The session ID. If empty or if no session with the given ID exists, a new session with a new session ID will be generated.
keepalive	Session duration in seconds. Overrides the value in the NAWA config file if present.

Returns

The new session ID (may differ from the given sessionId if no session with the given ID is valid).

Definition at line 127 of file Session.cpp.

start() [2/2]

void Session::start

(

nawa::Cookie

properties = Cookie()

)

Start the session (load existing session based on a cookie sent by the client or create a new one). This will send a session cookie to the client. The properties/attributes of the session cookie are determined by, with decreasing precedence,

1. the Cookie object that may be passed as an optional parameter to this function and will be used as a template for the cookie. See the param description on how to use it.
2. the configuration in the NAWA configuration file,
3. and, of course, by the cookie policy that can be set via Connection::setCookiePolicy (if it contains stronger protections than the configuration file).

The duration (keep-alive) of the session is defined in the NAWA config file, but can be overridden by setting the attribute maxAge of the parameter object, see below.

IMPORTANT! This function will NOT work correctly after flushing the response (as setting a session cookie is impossible then). It is recommended to call start() directly in the beginning of your program.

Parameters

properties

Template for the cookie sent to the client. You can use it to influence the behavior of Session and to make sure the cookie is properly secured. Setting options in this Cookie object will override the respective options from the configuration file and the cookie policy. The attributes will be used as follows: content: will be ignored (and replaced by the session ID) expires: set this to > 0 (e.g., to 1), if the Expires and Max-Age attributes should be set for the cookie. The value will be replaced by the proper expiry time. maxAge: will be used as the session duration (inactive keep-alive, server-side!) if > 0. If expires == 0, this attribute will be reset to 0 before setting the cookie. secure: send the Secure attribute with the cookie. httpOnly: send the HttpOnly attribute with the cookie. sameSite: set the SameSite attribute to lax (if sameSite == 1) or strict (if sameSite > 1).

Definition at line 211 of file Session.cpp.

established()

bool Session::established

(

)

const

Check whether a session is currently active (has been started).

Returns

True if session is established, false otherwise.

Definition at line 274 of file Session.cpp.

isSet()

bool Session::isSet

(

std::string const &

key

)

const

Check whether there exists a stored value for the given key. Please note that the behavior of this function might differ from [key].has_value() - while this function will also return true if the key has been set to an empty std::any, the latter one only returns true if the std::any contains an object.

Parameters

key	Key to check.

Returns

True if a value exists for this key, false otherwise. Always false if no session is active.

Definition at line 278 of file Session.cpp.

operator[]()

std::any Session::operator[]

(

std::string const &

key

)

const

Get the value at the given key (as a std::any object). To actually receive the stored object, use std::any_cast (example: std::any_cast<std::string>(conn.session()["test"])). You will have to explicitly state the type of the stored object as a template argument of std::any_cast (as C++ is statically typed).

Parameters

key	Key to get value for.

Returns

Value at key. If no value exists for that key or no session established, a std::any without value will be returned.

Definition at line 286 of file Session.cpp.

set() [1/3]

void Session::set	(	std::string	key,
		const std::any &	value
	)

Set key to a value of type std::any. Throws a nawa::Exception with error code 1 if no session has been established.

Parameters

key	Key to set.
value	Value to set the key to.

Definition at line 297 of file Session.cpp.

set() [2/3]

void nawa::Session::set ( std::string  key, char const *  value  )

inline

Set key to a string value. This function exists for convenience and makes sure that you do not save a const char* (c-style string) into a session (a terrible idea, as such a pointer would not be available anymore on the next request and therefore cause a segmentation fault). For std::string values, the next specialization (arbitrary type) will be used. The c-style string will be wrapped into a std::string, which will be wrapped into a Any value. As this function internally calls set(std::string, Any), a nawa::Exception with error code 1 will be thrown if no session has been established.

Parameters

key	Key to set.
value	C-string that will be used as the value (will be stored as a std::string!).

Definition at line 149 of file Session.h.

set() [3/3]

template<typename T >

void nawa::Session::set ( std::string  key, T const &  value  )

inline

Set key to a variable of an arbitrary type. This function exists just for convenience and will create a new std::any from the value type and call set(std::string, std::any), and will therefore throw a nawa::Exception with error code 1 if no session has been established. As you need to explicitly state the type when receiving the value later on, explicitly constructing the desired type might make your code more readable and less error-prone (if the value is directly constructed and not given as a variable).

Template Parameters

T	Type of the value. Can usually be deducted automatically by the compiler.

Parameters

key	Key to set.
value	Value to set the key to.

Definition at line 164 of file Session.h.

unset()

void Session::unset

(

std::string const &

key

)

Remove the session variable with the given key. Throws a nawa::Exception with error code 1 if no session has been established.

Parameters

key	Key to remove.

Definition at line 305 of file Session.cpp.

invalidate()

void Session::invalidate

(

)

Terminate and delete the currently existing session along with its data and dequeue the session cookie. This function will do nothing if no session is currently active. After invalidating the current session, you may start a new one, as long as the response has not already been flushed (as in this case, the cookie header has already been sent).

Definition at line 313 of file Session.cpp.

getID()

std::string Session::getID

(

)

const

Get the session ID of the current session.

Returns

The current session ID. Empty if no session is active.

Definition at line 332 of file Session.cpp.

Member Data Documentation

RequestHandler

friend nawa::Session::RequestHandler

RequestHandler is declared as a friend in order to be able to call destroy().

Definition at line 192 of file Session.h.

---

The documentation for this class was generated from the following files:

• include/nawa/session/Session.h
• src/session/Session.cpp