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.

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’.

- 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.