--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-4E195F2A-78AE-5664-A115-AD65BF457AB1.dita Thu Jan 21 18:18:20 2010 +0000
@@ -0,0 +1,102 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
+<!-- This component and the accompanying materials are made available under the terms of the License
+"Eclipse Public License v1.0" which accompanies this distribution,
+and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
+<!-- Initial Contributors:
+ Nokia Corporation - initial contribution.
+Contributors:
+-->
+<!DOCTYPE concept
+ PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
+<concept xml:lang="en" id="GUID-4E195F2A-78AE-5664-A115-AD65BF457AB1"><title>System Monitor</title><prolog><metadata><keywords/></metadata></prolog><conbody><p>The System Monitor (SysMon) provides a Process Monitor and Restart service. Its clients are typically the System Starter and After Market Starter which use information in static and dynamic startup configurations (SSC & DSC) to set the restart parameters. </p> <p>An application or process may also add itself to the System Monitor's list. </p> <p>Use of the System Monitor API is restricted by capabilites of the client: </p> <ul><li id="GUID-8F39C454-1FDB-5907-B189-234EE3F61EF1"><p> <b>WriteDeviceData</b> is required to request a process restart, </p> </li> <li id="GUID-0DB11E09-A380-5522-8385-5D439CCC9774"><p> <b>ProtServ</b> is required to request an OS restart into Normal mode </p> </li> <li id="GUID-82701B6E-BBBE-5925-8D20-871C21AB94D5"><p> <b> PowerMgmt</b> is required to request a restart into Startup mode </p> </li> </ul> <p>The system monitor API is simple and self explanatory. A client must instantiate an <xref href="GUID-19467402-8575-33F0-817D-339D39982D39.dita"><apiname>RSysMonSession</apiname></xref>, connect to the SysMon server and open [the session]. </p> <codeblock id="GUID-2017D6A5-BA32-5DAC-820A-A862A0F381B8" xml:space="preserve">
+// sysmonclisess.h
+//
+// Copyright (c) 2006 Symbian Software Ltd. All rights reserved.
+//
+
+#include <e32std.h>
+#include <e32base.h>
+#include <startupproperties.h>
+#include "startup.hrh"
+
+class RSysMonSession : public RSessionBase
+{
+public:
+ IMPORT_C TInt Open() ;
+ IMPORT_C void Close() ;
+
+ IMPORT_C TInt MonitorL(CStartupProperties& aStartupProperties, RProcess& aProcess) ;
+
+ IMPORT_C TInt MonitorSelfL(CStartupProperties& aStartupProperties) ;
+ IMPORT_C TInt CancelMonitorSelf() ;
+
+} ;</codeblock> <p>Monitoring is started with a call to <codeph>MonitorL()</codeph> or <codeph>MonitorSelfL()</codeph>. Before calling one of these functions, however, a <xref href="GUID-90F95A8A-A901-3987-99ED-57F1A57F1C09.dita"><apiname>CStartupProperties</apiname></xref> object must be created and populated with the desired monitoring and restart configuration. </p> <p> <xref href="GUID-90F95A8A-A901-3987-99ED-57F1A57F1C09.dita"><apiname>CStartupProperties</apiname></xref> has a series of <codeph>Set...()</codeph> functions which are used to determine the monitoring and restart behaviour for the application or process to be monitored. It has a version number (returned by the <codeph>Version()</codeph> function) as it is designed to remain compatible with future Symbian extensions. </p> <p>The following snippet shows how a process might add itself to SysMon, specifying that it should be restarted in the event of failure and that, if it cannot be restarted, the device should be rebooted. </p> <codeblock id="GUID-AE7B448B-BDC6-53D3-A429-3B28E5638DD5" xml:space="preserve">
+...
+// Add this application to SysMon.
+
+// (Note that this is normally done by SysStart or AmaStarter using information in an SSC or DSC.)
+
+RSysMonSession sysMon ;
+TInt err = sysMon.Connect() ;
+ // handle error
+
+err = sysMon.Open() ;
+ // handle error
+
+_LIT( KFileName, "Z:\\sys\\bin\\myServ.exe" ) ;
+_LIT( KRestartArg, "-restart" ) ;
+
+CStartupProperties startupProperties = CStartupProperties::NewLC( KFileName, KRestartArg ) ;
+
+startupProperties->SetStartupType( EStartProcess) ; // TStartupType
+startupProperties->SetStartMethod( EWaitForStart ) ; // TStartMethod
+startupProperties->SetNumberOfRetries( KRetryCount ) ;
+startupProperties->SetTimeout( KRestartTimeout ) ; // timeout in milliseconds
+startupProperties->SetRecoveryParams( ERestartOS , KNormalMode ) ; // TRecoveryMethod, modes are device specific
+startupProperties->SetMonitored( ETrue ) ; // montoring enabled
+startupProperties->SetViewless( ETrue ) ;
+startupProperties->SetStartInBackground( ETrue ) ;
+
+
+err = sysMon.MonitorSelfL( *startupProperties ) ;
+ // handle error
+
+CleanupStack::PopAndDestroy( startupProperties ) ;
+sysMon.Close() ;
+...
+
+</codeblock> <p><b>Setting up Monitoring in an SSC </b> </p> <p>Process monitoring is normally configured for processes and applications using <xref href="GUID-F118988C-47C9-3AF0-BCD2-150CAA5508C3.dita"><apiname>START_PROCESS_INFO2</apiname></xref> and <xref href="GUID-FFC386AF-61B6-39F8-90BB-5AD94190E5D6.dita"><apiname>START_APP_INFO2</apiname></xref> resources in an SSC. These are defined in <filepath>sysstart.rh</filepath>. </p> <p>Note that these structures add <b>monitor</b>, <b>startup mode</b> and a <b>localisable error message</b> to <xref href="GUID-41FDADC6-D207-341F-BA5E-BF7F9CF99601.dita"><apiname>START_PROCESS_INFO</apiname></xref> and <xref href="GUID-4CE505AC-FDD9-3155-8141-C54C5EEB259E.dita"><apiname>START_APP_INFO</apiname></xref>. </p> <codeblock id="GUID-5E4F5ED2-DE43-51D1-A99C-A8864376C2BC" xml:space="preserve">
+STRUCT START_PROCESS_INFO2 // For starting processes
+ {
+ WORD type = EStartupProcess2; // do not change
+ LTEXT path = ""; // VALUE REQUIRED
+ LTEXT args = ""; // Passed to the command line of the started process
+ WORD start_method = EFireAndForget; // can also be EWaitForStart or EDeferredWaitForStart
+ LONG timeout = 0; // In milliseconds only used for EWaitForStart
+ WORD retry_failure_recovery_method = ERestartOS; // can be EIgnoreCommandFailure
+ WORD no_of_retries_on_failure = 0; // only used for EWaitForStart
+ WORD monitor = 0; // can be 1 if monitoring required
+ WORD retry_failure_recovery_startup_mode = -1;
+ LTEXT localisable_resource_file="";
+ LONG localisable_resource_id=0; // used when fail_on_error= EinformUserOnFailure
+ }
+</codeblock> <codeblock id="GUID-73B02FE6-928F-55DF-9139-93355D04CFC5" xml:space="preserve">
+STRUCT START_APP_INFO2 // For starting apps
+ {
+ WORD type = EStartupApp2; // do not change
+ LTEXT path = ""; // VALUE REQUIRED
+ LTEXT args = ""; // Ignored
+ WORD start_method = EFireAndForget; // can also be EWaitForStart or EDeferredWaitForStart
+ WORD viewless = 0; // can be 1
+ WORD start_in_background = 0; // can be 1
+ LONG timeout = 0; // In milliseconds only used for EWaitForStart
+ WORD retry_failure_recovery_method = ERestartOS; // can be EIgnoreCommandFailure
+ WORD no_of_retries_on_failure = 0; // only used for EWaitForStart
+
+ WORD monitor = 0; // can be 1 if monitoring required
+ WORD retry_failure_recovery_startup_mode = -1;
+ LTEXT localisable_resource_file="";
+ LONG localisable_resource_id=0; // used when fail_on_error= EinformUserOnFailure
+ }
+</codeblock> <p><b>Setting up Monitoring in a DSC </b> </p> <p>Aftermarket components started at boot using a <xref href="GUID-E3941FAF-988E-5FB3-8E62-84E192E41EA1.dita">Dynamic Startup Configuration (DSC)</xref> may also be monitored and restarted by SysMon. The DSC API uses <xref href="GUID-90F95A8A-A901-3987-99ED-57F1A57F1C09.dita"><apiname>CStartupProperties</apiname></xref> in the manner described above. An AMC may be restarted on failure but it will not be permitted to reboot the device. </p> </conbody></concept>
\ No newline at end of file