Collapse all Symbian^3 Product Developer Library

System State Management Policy

The System State Management (SSM) policy determines the set of permissible states, state transitions, and the tasks that are performed while changing the system state. This policy is associated with a transition in system state or a system-wide property.

This policy is defined by a system state policy plug-in and an associated CommandList resource file. The policy in SSM is contained in policy DLLs and resource files. The policy DLLs are identified using the requested system state or system-wide property (example SysStatePolicy<stateIdentifier> and SysPropertyPolicy<propertyIdentifier>).

In addition to defining an interface for this framework, some command tasks, such as reading commandList s of a resource file format into memory, is also provided. This is implemented as a 'C' class which provides implementation of this common functionality. But, it still contains some pure virtual functions, similar to the CActive class for active objects.

When implementing a new policy DLL, choose to start from scratch and extend from the framework’s 'M' Class, or to use the 'C' class which provides the basic functionality and is expected to be commonly used in policy DLLs. The policy DLL is dynamically loaded and an object is instantiated that implements one of the following interfaces (M Class):

The policy DLLs are customizable by licensees. The framework for the policy DLLs are described by the APIs detailed in the following table.

Interfaces (M Class) :	API	Description
For system state	MSsmStatePolicy	This is an Session Initiation Protocol (SPI) which allows customization of the behavior of state changes.
For system-wide property	MSsmSwpPolicy	This is an SPI which allows customization of the behavior of the system-wide property changes.

Transition of a system state

The system state (and its sub-states) is distributed through the Domain Manager (DM). A specific command in a commandList is used to set a new value for the system state (that is SysCLE interfaces with the DM to change the system state). The new value of a system state is distributed through the DM and the appropriate Domain Hierarchy. For more information on SysCLE, see System Command List Executer.

When a change of a system state is requested:

SysStateMgr calls TransitionAllowed(..) to ascertain if the requested system state transition is allowed.
If the requested transition is allowed, the SSM policy loads the policy plug-in, GetNextCommandList(..).
GetNextCommandList(..) obtains the initial commandList for this system state.
The new system sub-state is returned by the policy plug-in. The returned commandList object is passed to SysCLE.
SysCLE runs the commandList, and provides a return code to indicate if the commandList is run successfully.
This return code and the system sub-state is used in a call to GetNextCommandList(..). This returns the next commandList or NULL (indicating that there are no more commandLists for this system state).

Command lists stored in resource files can be implemented in one of the two ways:

Single resource file containing multiple commandLists -

This option leads to only a single file being opened at a system state transition.

For example, on instantiation of the system state policy object, the associated resource file is opened, and this contains an array of commandLists which are used in specific system sub-states). This reduces any impact on device start-up time because of opening multiple resource files.

Note: A single resource file containing multiple commandLists for a particular system state is currently the preferred solution.
Many resource files, each containing a single commandList -

Multiple resource files make distinction between different commandLists very clear. This increases maintainability and eases debugging of commandLists.

Example of system state transition from ‘Normal’ to ‘Shutdown’

The following image illustrates an example of the policy actions performed when the system state is transitioned from ‘Normal’ to ‘Shutdown’.

Figure 1. System state transition from 'Normal' to 'Shutdown'

Symbian defined system state transitions

The following events cause transitions in Symbian defined system state:

Undefined -> Start-up:

In this transition, SysStateMgr is created by EStart(), the start-up system state is assumed. The start-up policy plug-in is used to select the correct ‘activities list’ for start-up. For example by reading the start-up Mode.
Start-up -> Normal :

In this transition, when the start-up state is finished, the last item in the commandList indicates to SysStateMgr that the Normal state should be entered.
Normal -> Shutdown:

This transition is generated by the Look and Feel (LaF) Shutdown manager or another component in the device responsible for handling device shutdown, after detection of a shutdown event.
Start-up/Normal/Shutdown -> Fail:

This transition can occur at any time, and it involves immediate interruption of the current commandList and immediate emergency shutdown of the device.

When distributing the system state, the domains existing in the Domain Manager hierarchy to be traversed in different directions, based on which state is being handled. Components higher up in the system model requires shutdown notification before components below them. Similarly components lower down in the system model need to be notified of start-up before components above them. The two possible options for accomplishing this using the domain hierarchy is to:

Have a separate domain hierarchy for each system state -

This option would have four separate domain hierarchies, one for each of the system states. The current system state is defined by the domain hierarchy which is currently in a defined state, or by a separate system state indication.
Traverse the same domain hierarchy in different directions, depending on the system state -

This option has one domain hierarchy with the current system state that is defined by the state of the domain hierarchy. This is the preferred option because of the simplicity in changing state and registering for notification of state transitions.

Parent topic: System State Manager Concepts