## Role |
|
This class is used for working with sessions. |
|
Header: `#include <cppcms/session_interface.h>` |
|
Generally you access `session_interface` class via `session` member of `worker_thread` or `application`. |
|
In order to use it, sessions should be enabled in [CppCMS configuration](/wikipp/en/page/ref_config#sessions). |
|
|
## 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 `boost::lexical_cast`. |
|
- **`bool is_set(string const &key)`** check if key `key` exists 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, `boost::bad_lexical_cast` is thrown. |
- **`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: [`cppcms::serializable`](/wikipp/en/page/ref_cppcms_serializable). |
- **`void set(string const &key,serializable const &);`** -- fetch serializable object from session. See: [`cppcms::serializable`](/wikipp/en/page/ref_cppcms_serializable) |
- **`void clear()`** -- clear session -- remove it. |
|
|
## Working with client side programming. |
|
In many cases it is useful to make session values be accessible by client-side -- javascript. CppCMS sessions provide simple API to expose certain values to client side using cookies. |
|
- **`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 |
|
cppcms_session=58b536a0d5b6f7dea2df70277482e536 |
cppcms_session_username=Moshe%20Rabinovich |
|
The prefix of session cookies (cppcms\_session) is [configurable](/wikipp/en/page/ref_config#sessions). |
|
_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 |
|
### Expiration policy |
|
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 `renew` policy. |
|
Default behavior and default timeout can be configured in CppCMS [configuration file](/wikipp/en/page/ref_config#sessions). |
|
### Changing defaults: |
|
- **`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. |
|
