This class is used for working with sessions.
Generally you access
session_interface class via
session member of
In order to use it, sessions should be enabled in CppCMS configuration.
Managing values in session
Session is build like std::map dictionary -- key value pairs, where both key and value are std::string.
Note: all keys starting with underscore "_" are reserved for cppcms engine use.
You can set or get any other values using automatic conversion using
bool is_set(string const &key)check if key
keyexists in session.
void del(string const &key)-- remove key from session.
std::string &operator(string const &key)-- return reference to value for key. If key not exists it is created.
template<typename T> T get(string const key)-- convert value to type T from string and return it. If conversion fails,
template<typename T> void set(string const &key,T const &val)-- convert value from T to string and assign it to key.
void get(string const &key,serializable &);-- save serializable object to session. See:
void set(string const &key,serializable const &);-- fetch serializable object from session. See:
void clear()-- clear session -- remove it.
Working with client side programming.
void expose(string const &key,bool val=true);-- if val is true expose key to client side to cookie, otherwise hide it from client side -- remove cookie.
expose()creates new cookie that has exposed value together with session cookie with additional suffix -- key.
For example, following code:
session["username"]="Moshe Rabinovich"; session.expose("username");
Would create these cookies
The prefix of session cookies (cppcms_session) is configurable.
Note: Hiding session values implemented as cookies removal and requires cooperation of client side. Never read values from these cookies, always relate to session data that is protected using signatures or session key.
void hide(std::string const &key)-- shortcut to expose(key,false).
bool is_exposed(string const &key);-- checks if specific key is exposed.
Note: it looks into session object for this information, if result is false, this does not mean that user is really removed it's cookies.
Controlling session expiration
Session interface supports three types of expiration
session_interface::fixed-- the session is removed after fixed period of time since it's creation.
This model can be generally used when we want to enforce user login every specific period of time.
session_interface::renew-- session timeout is updated each time user visits the site with new value (up to 10% accuracy).
In this case user would stay logged in each time it visits the side frequently enough.
session_interface::browser-- keep session all the time browser window is open.
Note: even this policy have default timeout that is similar to
Default behavior and default timeout can be configured in CppCMS configuration file.
void set_age(int t)-- set different lifetime of session (in seconds).
void set_expiration(int h)-- set different expiration method, one of: browser, renew or fixed.
void set_expiration();-- restore default expiration method. (cppcms v0.0.3 and above)
void set_age()-- revert session lifetime to default. (cppcms v0.0.3 and above)
Note: CppCMS v0.0.2 requires set non-default expiration lifetime and method each time you access session object. This policy has changed in next versions. Timeout period is stored withing session and should be reset to default if user wants to change it.