File Information
Library: OSP/Web
Package: Web
Header: Poco/OSP/Web/WebSession.h
Description
A WebSession is used for tracking users between different HTTP(S) requests. WebSession objects are managed by a session manager (usually, an implementation of the WebSessionService).
The WebSession can also be used to store arbitrary data (attributes) in the form of key-value pairs between different requests. Poco::Any is used for storing values, so practically any object can be attached to a session.
A WebSession has a time out. If a WebSession instance is not accessed for a given time, it will be destroyed by the session manager.
Note that the iterator-based access methods (find(), begin(), end()) are not thread-safe.
When a new session is created, the session manager will generate a CSRF synchronizer token, which can be used in forms to prevent Cross-Site Request Forgery (CSRF) attacks. The name of the property is "#csrfToken". It can also be obtained by calling the csrfToken() member function.
Member Summary
Member Functions: access, accessImpl, begin, clear, clearImpl, clientAddress, created, csrfToken, end, erase, find, get, getExpiration, getValue, has, id, onBundleStopping, set, setValue, timeout, updateVersion, version
Types Aliases
Attributes
using Attributes = std::map < std::string, Poco::Any >;
Ptr
using Ptr = Poco::SharedPtr < WebSession >;
Constructors
WebSession
WebSession(
const std::string & id,
const std::string & csrfToken,
Poco::Int64 version,
int timeoutSeconds,
const Poco::Net::IPAddress & clientAddress,
Poco::AutoPtr < WebSessionStore > pStore,
BundleContext::Ptr pContext
);
Creates a new WebSession with the given ID and time out.
WebSession
WebSession(
const std::string & id,
Poco::Int64 version,
int timeoutSeconds,
const Poco::Net::IPAddress & clientAddress,
Poco::AutoPtr < WebSessionStore > pStore,
BundleContext::Ptr pContext,
Poco::Timestamp created,
const Attributes & attrs
);
Creates a new WebSession with the given ID and time out.
Destructor
~WebSession 
virtual ~WebSession();
Fires a sessionEnds event and destroys the WebSession.
Member Functions
access
void access();
Updates the expiration time.
begin 
Attributes::const_iterator begin() const;
Returns the begin iterator for attributes.
clear
void clear();
Erases all attributes.
clientAddress
const Poco::Net::IPAddress & clientAddress() const;
Returns the IP address of the client holding the session.
created
const Poco::Timestamp & created() const;
Returns the creation time of the session, i.e. the time the user sent the first request.
csrfToken
std::string csrfToken() const;
Returns the CSRF synchronizer token for this session.
end
Attributes::const_iterator end() const;
Returns the end iterator for attributes.
erase
void erase(
const std::string & key
);
Erases an attribute value from the session.
find
Attributes::const_iterator find(
const std::string & key
) const;
Searches for an attribute. Returns end() if not found.
get
const Poco::Any & get(
const std::string & key
) const;
Returns the attribute with the given key.
Throws a Poco::NotFoundException if the attribute does not exist.
getExpiration
const Poco::Timestamp & getExpiration() const;
Return the time when the session will expire.
getValue
template < typename T > T getValue(
const std::string & key
) const;
Convenience function that returns the attribute with the given key, casted to the desired type.
Throws a Poco::NotFoundException if the attribute does not exist. Throws a Poco::BadCastException if the cast is invalid.
getValue
template < typename T > T getValue(
const std::string & key,
T deflt
) const;
Convenience function that returns the attribute with the given key, casted to the desired type. If the attribute does not exist, the given default value is returned.
Throws a Poco::BadCastException if the cast is invalid.
has
bool has(
const std::string & key
) const;
Returns true if and only if the session has an attribute with the given value.
id
const std::string & id() const;
The unique identifier of the session.
set
void set(
const std::string & key,
const Poco::Any & value
);
Sets/Overwrites an attribute value.
setValue
template < typename T > void setValue(
const std::string & key,
T value
);
Sets/Overwrites an attribute value.
timeout
int timeout() const;
Returns the timeout of the session in seconds.
version
Poco::Int64 version() const;
Returns the version number of the session.
accessImpl 
void accessImpl();
Updates the expiration time.
clearImpl
void clearImpl();
Erases all attributes.
onBundleStopping
void onBundleStopping(
const void * pSender,
BundleEvent & ev
);
When the bundle owning the session is stopped, all attributes are cleared.
After the bundle owning the session has been stopped and its libraries have been unloaded, virtual destructors of objects stored in the session might no longer be available. Therefore all attributes must be removed while their object's destructors are still available.
updateVersion
void updateVersion(
Poco::Int64 version
);
Updates the version if the new version is one higher than the current version.
Variables
CSRF_TOKEN 
static const std::string CSRF_TOKEN;
The name of the attribute storing the CSRF synchronizer token.
sessionEnds
Poco::BasicEvent < const WebSession * > sessionEnds;
Fired before the session object is destroyed.