1 <?xml version="1.0" encoding="utf-8"?>

     2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

     3 <!-- This component and the accompanying materials are made available under the terms of the License 

     4 "Eclipse Public License v1.0" which accompanies this distribution, 

     5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE concept

    11   PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

    12 <concept id="GUID-4E5B1276-07D1-562A-8EE8-21DDE78D2CE5" xml:lang="en"><title>System

    13 State Management Policy</title><prolog><metadata><keywords/></metadata></prolog><conbody>

    14 <p>The System State Management (SSM) policy determines the set of permissible

    15 states, state transitions, and the tasks that are performed while changing

    16 the system state. This policy is associated with a transition in system state

    17 or a system-wide property. </p>

    18 <p>This policy is defined by a system state policy plug-in and an associated <codeph>CommandList</codeph> resource

    19 file. The policy in SSM is contained in policy DLLs and resource files. The

    20 policy DLLs are identified using the requested system state or system-wide

    21 property (example <codeph>SysStatePolicy&lt;stateIdentifier&gt;</codeph> and <codeph>SysPropertyPolicy&lt;propertyIdentifier&gt;</codeph>). </p>

    22 <p>In addition to defining an interface for this framework, some command tasks,

    23 such as reading <codeph>commandList</codeph> s of a resource file format into

    24 memory, is also provided. This is implemented as a 'C' class which provides

    25 implementation of this common functionality. But, it still contains some pure

    26 virtual functions, similar to the <xref href="GUID-067293BF-B28C-3CEC-92F4-1351A795EA7F.dita"><apiname>CActive</apiname></xref> class for active

    27 objects. </p>

    28 <p>When implementing a new policy DLL, choose to start from scratch and extend

    29 from the framework’s 'M' Class, or to use the 'C' class which provides the

    30 basic functionality and is expected to be commonly used in policy DLLs. The

    31 policy DLL is dynamically loaded and an object is instantiated that implements

    32 one of the following interfaces (M Class): </p>

    33 <p>The policy DLLs are customizable by licensees. The framework for the policy

    34 DLLs are described by the APIs detailed in the following table. </p>

    35 <table id="GUID-3E8474F9-9D83-5995-B98E-29CDC3B74516">

    36 <tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/>

    37 <thead>

    38 <row>

    39 <entry><p><b>Interfaces (M Class) :</b> </p></entry>

    40 <entry><p><b>API</b></p></entry>

    41 <entry><p><b>Description</b></p></entry>

    42 </row>

    43 </thead>

    44 <tbody>

    45 <row>

    46 <entry><p>For system state </p> </entry>

    47 <entry><p> <xref href="GUID-A86FEEA6-7602-34A9-A200-E2521CB66BD4.dita"><apiname>MSsmStatePolicy</apiname></xref>  </p> </entry>

    48 <entry><p>This is an Session Initiation Protocol (SPI) which allows customization

    49 of the behavior of state changes. </p> </entry>

    50 </row>

    51 <row>

    52 <entry><p>For system-wide property </p> </entry>

    53 <entry><p> <xref href="GUID-31FB0BC8-83FC-3581-A7A3-C1781CAE7187.dita"><apiname>MSsmSwpPolicy</apiname></xref>  </p> </entry>

    54 <entry><p>This is an SPI which allows customization of the behavior of the

    55 system-wide property changes. </p> </entry>

    56 </row>

    57 </tbody>

    58 </tgroup>

    59 </table>

    60 <section><title>Transition of a system state</title> <p>The system state (and

    61 its sub-states) is distributed through the Domain Manager (DM). A specific

    62 command in a <codeph>commandList</codeph> is used to set a new value for the

    63 system state (that is SysCLE interfaces with the DM to change the system state).

    64 The new value of a system state is distributed through the DM and the appropriate

    65 Domain Hierarchy. For more information on SysCLE, see <xref href="GUID-1F2911DC-7D71-573D-AFD2-1EA4BBA88A57.dita#GUID-1F2911DC-7D71-573D-AFD2-1EA4BBA88A57/GUID-E2D75D7D-98A5-5419-8B0E-0A995D3EFEC9">System Command List Executer</xref>. </p> <p>When a change of a system state

    66 is requested: </p> <ol id="GUID-7B67F54E-91A7-52FF-91E6-93E66B7B3654">

    67 <li id="GUID-3DCB2900-E1DE-5A01-9C42-794E49CD0903"><p>SysStateMgr calls <codeph>TransitionAllowed(..)</codeph> to

    68 ascertain if the requested system state transition is allowed. </p> </li>

    69 <li id="GUID-C76D73C1-24D5-575E-A014-13629DAF2B3B"><p>If the requested transition

    70 is allowed, the SSM policy loads the policy plug-in, <codeph>GetNextCommandList(..)</codeph>. </p> </li>

    71 <li id="GUID-533853A3-4950-5067-B5F8-46B30E1A7AEA"><p> <codeph>GetNextCommandList(..)</codeph> obtains

    72 the initial <codeph>commandList</codeph> for this system state. </p> </li>

    73 <li id="GUID-B9D92285-0D0F-5B99-8B40-F1C66CE53593"><p>The new system sub-state

    74 is returned by the policy plug-in. The returned commandList object is passed

    75 to SysCLE. </p> </li>

    76 <li id="GUID-31463C2B-0531-52C7-A524-56A75A5C3280"><p>SysCLE runs the <codeph>commandList</codeph>,

    77 and provides a return code to indicate if the <codeph>commandList</codeph> is

    78 run successfully. </p> </li>

    79 <li id="GUID-9BBA2C2D-02C8-5059-88C8-3A7AA08C7ABD"><p>This return code and

    80 the system sub-state is used in a call to <codeph>GetNextCommandList(..)</codeph>.

    81 This returns the next <codeph>commandList</codeph> or NULL (indicating that

    82 there are no more <codeph>commandLists</codeph> for this system state). </p> </li>

    83 </ol> <p>Command lists stored in resource files can be implemented in one

    84 of the two ways: </p> <ul>

    85 <li id="GUID-FBE223B7-EA0E-579B-B3B4-EECA95B31FD0"><p>Single resource file

    86 containing multiple commandLists - </p> <p>This option leads to only a single

    87 file being opened at a system state transition. </p> <p>For example, on instantiation

    88 of the system state policy object, the associated resource file is opened,

    89 and this contains an array of commandLists which are used in specific system

    90 sub-states). This reduces any impact on device start-up time because of opening

    91 multiple resource files. </p> <p> <b>Note:</b> A single resource file containing

    92 multiple commandLists for a particular system state is currently the preferred

    93 solution. </p> </li>

    94 <li id="GUID-FCD34DF4-8B38-5039-A026-10DEAAFAE16B"><p>Many resource files,

    95 each containing a single <codeph>commandList</codeph> - </p> <p>Multiple resource

    96 files make distinction between different commandLists very clear. This increases

    97 maintainability and eases debugging of commandLists. </p> </li>

    98 </ul> <p><b>Example of system state transition from ‘Normal’ to ‘Shutdown’</b> </p> <p>The

    99 following image illustrates an example of the policy actions performed when

   100 the system state is transitioned from ‘Normal’ to ‘Shutdown’. </p> <fig id="GUID-C6D2D6B9-FE2D-5265-94EC-DF1D6128ACA9">

   101 <title>                 System state transition from 'Normal' to 'Shutdown'

   102               </title>

   103 <image href="GUID-1686AFA7-F0FA-5B3D-9E2F-EE2D7CDC338B_d0e140761_href.png" placement="inline"/>

   104 </fig> <p><b>Symbian defined system state transitions</b> </p> <p>The following

   105 events cause transitions in Symbian defined system state: </p> <ol id="GUID-D8F4E705-1C48-5222-956E-0D74835EEDD6">

   106 <li id="GUID-9BFC161B-D1CE-5BB4-868A-F86E432E12BC"><p> <b>Undefined -&gt; Start-up:</b>  </p> <p>In

   107 this transition, <filepath>SysStateMgr</filepath> is created by <codeph>EStart()</codeph>,

   108 the start-up system state is assumed. The start-up policy plug-in is used

   109 to select the correct ‘activities list’ for start-up. For example by reading

   110 the start-up Mode. </p> </li>

   111 <li id="GUID-5F43C1F2-57F1-5341-914C-DA389037627A"><p> <b>Start-up -&gt; Normal

   112 :</b>  </p> <p>In this transition, when the start-up state is finished, the

   113 last item in the commandList indicates to <filepath>SysStateMgr</filepath> that

   114 the Normal state should be entered. </p> </li>

   115 <li id="GUID-A5E578ED-06D0-5FD5-B268-9CA7EF4E4DB1"><p> <b>Normal -&gt; Shutdown:</b>  </p> <p>This

   116 transition is generated by the Look and Feel (LaF) Shutdown manager or another

   117 component in the device responsible for handling device shutdown, after detection

   118 of a shutdown event. </p> </li>

   119 <li id="GUID-B526B171-5654-50AA-9482-D20D4D549D28"><p> <b>Start-up/Normal/Shutdown

   120 -&gt; Fail:</b>  </p> <p>This transition can occur at any time, and it involves

   121 immediate interruption of the current commandList and immediate emergency

   122 shutdown of the device. </p> </li>

   123 </ol> <p>When distributing the system state, the domains existing in the Domain

   124 Manager hierarchy to be traversed in different directions, based on which

   125 state is being handled. Components higher up in the system model requires

   126 shutdown notification before components below them. Similarly components lower

   127 down in the system model need to be notified of start-up before components

   128 above them. The two possible options for accomplishing this using the domain

   129 hierarchy is to: </p> <ul>

   130 <li id="GUID-C2FDB7E4-CFC0-5C5D-A473-791268AE59DC"><p> <b>Have a separate

   131 domain hierarchy for each system state</b> - </p> <p>This option would have

   132 four separate domain hierarchies, one for each of the system states. The current

   133 system state is defined by the domain hierarchy which is currently in a defined

   134 state, or by a separate system state indication. </p> </li>

   135 <li id="GUID-ABC31988-39BD-5F11-AD8B-87F26B89001D"><p> <b> Traverse the same

   136 domain hierarchy in different directions, depending on the system state</b> - </p> <p>This

   137 option has one domain hierarchy with the current system state that is defined

   138 by the state of the domain hierarchy. This is the preferred option because

   139 of the simplicity in changing state and registering for notification of state

   140 transitions. </p> </li>

   141 </ul> </section>

   142 </conbody></concept>