Skip to main content
ATL Server Library Reference 
Session-State Support 

This topic addresses how to use session-state support from ATL Server request handlers. The following topics apply to applications that will be used with an ISAPI extension DLL that includes ATL session-state support. The solution files and source code necessary for session-state-enabled extension DLLs can be generated easily using the ATL Server Project Wizard.

For instruction on how to add support to an existing ISAPI DLL created without session-state services or help to modify session service settings, see Session-State Tasks.

Session-State Interfaces

Session objects, along with the data contained by a session, are manipulated from ATL Server request handlers using these interfaces:

Interface Description

ISessionStateControl

Can be used to set and retrieve global session timeout settings, and to determine the number of currently active sessions present on the server.

ISessionStateService

Used to create new sessions, retrieve pointers to existing sessions, and terminate sessions that are no longer needed.

ISession

Provides methods for the storage and retrieval of user-specific data and timeout settings for a single session.

Session-State Data Access

The ATL Server Project Wizard, when used to create session-state-enabled application and ISAPI DLL projects, adds code to the default request handler that performs the retrieval of an ISessionStateService interface pointer. This code includes an ISessionStateService pointer and, within the request handler's ValidateAndExchange method, a call to the IServiceProviderImpl::QueryService method, which attempts the initialization of the pointer. Once a valid ISessionStateService interface pointer has been retrieved, it can be used to create new sessions and retrieve existing ones with the CreateNewSession and GetSession methods, respectively.

See Session-State Tasks for step-by-step coverage of how to access session-state data.

Session Identification

Each session is identified by a session ID. The ISessionStateService::CreateNewSession method, in addition to initializing an ISession pointer, returns an ID to identify the new session. This session ID must be communicated to the client that the new session corresponds to so that subsequent client requests (which should also include the session ID) can be matched to the correct session data.

ATL Server provides support for communicating session IDs between client and server. When a new session is created and a new session ID is generated, the ID can be sent to the client as part of the server response using the CHttpResponse::AppendCookie method. Likewise, a client's session ID can be retrieved during subsequent requests via the CHttpRequest::GetSessionCookie method. Instances of the CHttpResponse and CHttpRequest classes are accessible through the CRequestHandlerT base class from which ATL Server request handlers are derived.

Session Data Storage and Retrieval

Once a valid ISession interface pointer has been retrieved using the ISessionStateControl interface (either to create a new session or to retrieve an existing one), session variables can be stored, modified, retrieved, and removed using the ISession methods.

Each session variable added to the session includes a name, in the form of a string, and a value, in the form of a VARIANT. The ISession::SetVariable method can be used to create new variables and to modify existing ones. Variable values can be retrieved using the ISession::GetVariable method given the variable name, or enumerated using the ISession::BeginVariableEnum, ISession::GetNextVariable, and ISession::CloseEnum methods.

Despite the fact that session-state variables are accessed with the same API regardless of the underlying session-state implementation, there are some important differences between the database and memory-based session-state services. See Implementation Differences.

Session Timeouts

Each session has a timeout value, expressed in milliseconds. A session "times out," or expires, if an amount of time greater than the timeout value elapses. Sessions can be checked for expiration using the ISession::IsExpired method.

A session's timeout value (which defaults to 600,000 milliseconds, or 10 minutes) can be set using the ISession::SetTimeout method. Alternately, the ISessionStateControl::SetSessionTimeout method can be used to set the timeout value for all current and future sessions.

It is the responsibility of the application to call one of the ISession methods to maintain the life of the session and restart the timeout (just obtaining the session object does not restart the timeout). Once the session has not been accessed for the period specified by the timeout, the session object will expire.

Depending on the underlying session-state implementation, session timeout values can affect session availability because expired sessions may be removed from storage. ATL Server memory-backed session-state support, for example, removes expired sessions automatically, and the database-backed implementation does not.

Implementation Differences

The ISessionStateControl, ISessionStateService, and ISession interfaces form the interface to ATL Server session-state support regardless of the underlying implementation. There are some important differences, however, between the two implementations provided with ATL Server.

  • The memory-backed session-state implementation, while providing optimal performance, cannot be used in multiple-machine server configurations.

  • The database-backed implementation requires extra maintenance because expired and discarded session data is not removed from the database unless the session data is explicitly deleted using the ISession::RemoveAllVariables method.

  • Before the database-backed support can be used, database tables must be configured. Use the SessonServices.sql file in the \vc7\bin installation directory to automatically configure these tables.

The CComVariant class is used to write session-state values in the database implementation. This has two ramifications:

See Also