|
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-723F8716-1FDD-57B4-B685-672D3A755592" xml:lang="en"><title>Requesting |
|
13 and Cancelling Monitoring for a Process</title><shortdesc>This tutorial describes how to request and cancel monitoring for |
|
14 a process. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
15 <section><title>Introduction</title> <p>Before monitoring a process, SHMA |
|
16 reads the following information from SSM: </p> <ul> |
|
17 <li id="GUID-5396E46B-9AB1-526A-9AAA-FBC5A40A1094"><p>file name of the process |
|
18 to be launched </p> </li> |
|
19 <li id="GUID-E18CEB76-319C-5DBA-8DEA-9254EF9CC0CE"><p>arguments required for |
|
20 the process </p> </li> |
|
21 <li id="GUID-DC166941-30B5-5918-839A-6700C5932B90"><p>execution behaviour |
|
22 (See <xref href="GUID-12EE2A10-149F-36C8-8699-65BE8DDFCC6C.dita"><apiname>TSsmExecutionBehaviour</apiname></xref> for more information) </p> </li> |
|
23 <li id="GUID-A78E13B0-C9AD-5E6E-9BD9-5A103033CEAC"><p>time-out to wait for |
|
24 process to start before considering it as a failure </p> </li> |
|
25 <li id="GUID-463017DC-3DC7-54A6-B39B-96324642A52C"><p>number of retries if |
|
26 an application or a process fails to start. </p> </li> |
|
27 </ul> <p> <xref href="GUID-19467402-8575-33F0-817D-339D39982D39.dita"><apiname>RSysMonSession</apiname></xref> is the client interface for SHMA. </p> </section> |
|
28 <section><title>Procedure</title><p>The following methods can be used to request |
|
29 monitoring a process or an application:</p><codeblock xml:space="preserve">EXPORT_C void RSysMonSession::MonitorL( const CSsmStartupProperties& aSsmStartupProperties, |
|
30 const RProcess& aProcess, |
|
31 TBool aExecuteRecoveryMethodOnFailure )</codeblock><codeblock xml:space="preserve">EXPORT_C void RSysMonSession::MonitorSelfL( const CSsmStartupProperties& aSsmStartupProperties )</codeblock><p>When the SysMon server receives monitoring request, it checks that the |
|
32 client has appropriate PlatSec capabilities, and that the process is not currently |
|
33 being monitored. A client which is monitoring itself can use the following |
|
34 method to cancel monitoring:</p><codeblock xml:space="preserve">EXPORT_C void RSysMonSession::CancelMonitorSelfL()</codeblock><p>It |
|
35 is not possible for a client to cancel monitoring of another process, even |
|
36 if it was responsible for requesting monitoring.</p></section> |
|
37 <section id="GUID-91438FCA-D06F-5779-98E9-D353692BE59F"><title>Example</title> <p>The |
|
38 following code fragment illustrates how a client can request monitoring using |
|
39 SHMA, specifying that the monitored process must be restarted in the event |
|
40 of failure and that, if it cannot be restarted, the device must be rebooted. </p> <codeblock id="GUID-226291A8-CF61-5A8D-BA0C-6FBCA5F5E160" xml:space="preserve">... |
|
41 // Monitoring a process using SysMon. |
|
42 |
|
43 LIT( KMonitoredProcess, "monitoredprocess.exe" ); |
|
44 |
|
45 // Properties for the application |
|
46 CSsmStartupProperties *ssmProp = CSsmStartupProperties::NewLC( KMonitoredProcess, KNullDesC ); |
|
47 |
|
48 //ESsmWaitForSignal is the execution behaviour for starting the process. |
|
49 ssmProp->SetExecutionBehaviour( ESsmWaitForSignal ); |
|
50 TSsmMonitorInfo monitorInfo; |
|
51 monitorInfo.iRestartPolicy = ESsmRestartOS; |
|
52 |
|
53 //Startup mode to restart the OS |
|
54 monitorInfo.iRestartMode = 0; |
|
55 |
|
56 //Infinite time-out |
|
57 monitorInfo.iTimeout = 0; |
|
58 |
|
59 //No of retries if an application or a process fails to start. |
|
60 monitorInfo.iRetries = 1; |
|
61 |
|
62 ssmProp->SetMonitorInfoL( monitorInfo ); |
|
63 |
|
64 RProcess process; |
|
65 |
|
66 TInt err = process.Create( KMonitoredProcess, KNullDesC ); |
|
67 User::LeaveIfError( err ); |
|
68 CleanupClosePushL( &process ); |
|
69 process.Resume(); |
|
70 |
|
71 // instantiate a session |
|
72 RSysMonSession sess; |
|
73 |
|
74 //Open a session |
|
75 sess.OpenL(); |
|
76 |
|
77 //Create a monitor for the session |
|
78 TRAP( err, sess.MonitorL( *ssmProp, process ) ); |
|
79 sess.Close(); |
|
80 CleanupStack::PopAndDestroy( 2, ssmProp ); </codeblock> <p>The following |
|
81 code fragments illustrate the structs in a resource file used for process |
|
82 monitoring: </p> <codeblock id="GUID-921B742E-6566-51CF-92A7-1AC653379647" xml:space="preserve">STRUCT SSM_START_APP_INFO |
|
83 { |
|
84 // Must be the first entry in this struct - Zero means command is unconditional |
|
85 LLINK conditional_information = 0; |
|
86 // Must be the second entry in this struct and must not be changed |
|
87 WORD type = ESsmCmdStartApp; |
|
88 #ifndef SYMBIAN_SSM_FLEXIBLE_MERGE |
|
89 // Must be the third entry in this struct |
|
90 WORD version = ECmdStartAppInitialVersion; |
|
91 #else |
|
92 // This version supports priority of the command |
|
93 WORD version = ECmdStartAppVersionWithPriority; |
|
94 #endif |
|
95 // Can have a higher severity defined in TCmdErrorSeverity |
|
96 WORD severity = ECmdIgnoreFailure; |
|
97 // VALUE REQUIRED - full path to the application |
|
98 LTEXT name = ""; |
|
99 // Passed to the "Tail End" at the command line |
|
100 // see CApaCommandLine. Maximum argument length allowed is 256 chars. |
|
101 LTEXT args = ""; |
|
102 // Can also be ESsmWaitForSignal or ESsmDeferredWaitForSignal |
|
103 BYTE execution_behaviour = ESsmFireAndForget; |
|
104 // Time in milliseconds for every retry on failure |
|
105 LONG timeout = 0; |
|
106 // Number of times to retry on failure |
|
107 WORD retries = 0; |
|
108 // Set to 1 if app is viewless |
|
109 BYTE viewless = 0; |
|
110 // Set to 1 if app should be launched in the background |
|
111 BYTE background = 0; |
|
112 // zero means no monitoring is required, SSM_MONITOR_INFO |
|
113 // should be used if monitoring is required |
|
114 LLINK monitor_info = 0; |
|
115 #ifdef SYMBIAN_SSM_FLEXIBLE_MERGE |
|
116 // The order of the command in the list - range can be from 0x00 to 0xffffu |
|
117 WORD priority = KDefaultCommandPriority; |
|
118 #endif |
|
119 } |
|
120 </codeblock> <codeblock id="GUID-D8529CF5-87ED-503E-87CB-7599263AF403" xml:space="preserve"> |
|
121 /** |
|
122 Struct for starting processes. |
|
123 |
|
124 STRUCT SSM_START_PROCESS_INFO |
|
125 { |
|
126 // Must be the first entry in this struct - Zero means |
|
127 // command is unconditional |
|
128 LLINK conditional_information = 0; |
|
129 // Must be the second entry in this struct and must not be changed |
|
130 WORD type = ESsmCmdStartProcess; |
|
131 #ifndef SYMBIAN_SSM_FLEXIBLE_MERGE |
|
132 // Must be the third entry in this struct |
|
133 WORD version = ECmdStartProcessInitialVersion; |
|
134 #else |
|
135 // This version supports priority of the command |
|
136 WORD version = ECmdStartProcessVersionWithPriority; |
|
137 #endif |
|
138 // Can have a higher severity defined in TCmdErrorSeverity |
|
139 WORD severity = ECmdIgnoreFailure; |
|
140 // VALUE REQUIRED - full path to the process |
|
141 LTEXT name = ""; |
|
142 // Passed to the "Tail End" at the command line |
|
143 // see CApaCommandLine. Maximum argument length allowed is 256 chars. |
|
144 LTEXT args = ""; |
|
145 // Can also be ESsmWaitForSignal or ESsmDeferredWaitForSignal |
|
146 BYTE execution_behaviour = ESsmFireAndForget; |
|
147 // Time in milliseconds for every retry on failure |
|
148 LONG timeout = 0; |
|
149 // Number of times to retry on failure |
|
150 WORD retries = 0; |
|
151 // zero means no monitoring is required, |
|
152 // SSM_MONITOR_INFO should be used if monitoring is required |
|
153 LLINK monitor_info = 0; |
|
154 #ifdef SYMBIAN_SSM_FLEXIBLE_MERGE |
|
155 // The order of the command in the list - range can be from 0x00 to 0xffffu |
|
156 WORD priority = KDefaultCommandPriority; |
|
157 #endif |
|
158 }</codeblock> <codeblock id="GUID-06E40D32-AF80-58D8-B445-75D317F7D748" xml:space="preserve">/** |
|
159 Struct for monitoring information. |
|
160 |
|
161 STRUCT SSM_MONITOR_INFO |
|
162 { |
|
163 // Must be the first entry in this struct and must not be changed |
|
164 WORD type = ESsmMonitorInfo; |
|
165 // Must be the second entry in this struct |
|
166 WORD version = ESsmMonitorInfoInitialVersion; |
|
167 // OS Restart policy to be used if component restarting has failed |
|
168 BYTE restart_policy = ESsmIgnoreOnFailure; |
|
169 // Restart mode when restart_policy=ESsmRestartOSWithMode |
|
170 BYTE restart_mode; |
|
171 // Delay in milliseconds between retries |
|
172 LONG timeout = 0; |
|
173 // Number of times to attempt to restart a failed component |
|
174 WORD retries = 0; |
|
175 }</codeblock> </section> |
|
176 </conbody><related-links> |
|
177 <link href="GUID-8BC13552-7C7D-52AC-AF91-1BB7476912AF.dita"><linktext>System Health |
|
178 Manager Overview</linktext></link> |
|
179 <link href="GUID-484B27EF-3FA1-5193-97EC-B9699AE49026.dita"><linktext>System Health |
|
180 Manager Concepts</linktext></link> |
|
181 </related-links></concept> |