Requesting -and Cancelling Monitoring for a Process

Requesting -and Cancelling Monitoring for a ProcessThis tutorial describes how to request and cancel monitoring for -a process. -

Introduction

Before monitoring a process, SHMA -reads the following information from SSM:

file name of the process -to be launched
arguments required for -the process
execution behaviour -(See TSsmExecutionBehaviour for more information)
time-out to wait for -process to start before considering it as a failure
number of retries if -an application or a process fails to start.

RSysMonSession is the client interface for SHMA.

Procedure

The following methods can be used to request -monitoring a process or an application:

EXPORT_C void RSysMonSession::MonitorL( const CSsmStartupProperties& aSsmStartupProperties, - const RProcess& aProcess, - TBool aExecuteRecoveryMethodOnFailure )EXPORT_C void RSysMonSession::MonitorSelfL( const CSsmStartupProperties& aSsmStartupProperties )

When the SysMon server receives monitoring request, it checks that the -client has appropriate PlatSec capabilities, and that the process is not currently -being monitored. A client which is monitoring itself can use the following -method to cancel monitoring:

EXPORT_C void RSysMonSession::CancelMonitorSelfL()

It -is not possible for a client to cancel monitoring of another process, even -if it was responsible for requesting monitoring.

Example

The -following code fragment illustrates how a client can request monitoring using -SHMA, specifying that the monitored process must be restarted in the event -of failure and that, if it cannot be restarted, the device must be rebooted.

... -// Monitoring a process using SysMon. - -LIT( KMonitoredProcess, "monitoredprocess.exe" ); - -// Properties for the application -CSsmStartupProperties *ssmProp = CSsmStartupProperties::NewLC( KMonitoredProcess, KNullDesC ); - -//ESsmWaitForSignal is the execution behaviour for starting the process. -ssmProp->SetExecutionBehaviour( ESsmWaitForSignal ); -TSsmMonitorInfo monitorInfo; -monitorInfo.iRestartPolicy = ESsmRestartOS; - -//Startup mode to restart the OS -monitorInfo.iRestartMode = 0; - -//Infinite time-out -monitorInfo.iTimeout = 0; - -//No of retries if an application or a process fails to start. -monitorInfo.iRetries = 1; - -ssmProp->SetMonitorInfoL( monitorInfo ); - -RProcess process; - -TInt err = process.Create( KMonitoredProcess, KNullDesC ); -User::LeaveIfError( err ); -CleanupClosePushL( &process ); -process.Resume(); - -// instantiate a session -RSysMonSession sess; - -//Open a session -sess.OpenL(); - -//Create a monitor for the session -TRAP( err, sess.MonitorL( *ssmProp, process ) ); -sess.Close(); -CleanupStack::PopAndDestroy( 2, ssmProp );

The following -code fragments illustrate the structs in a resource file used for process -monitoring:

STRUCT SSM_START_APP_INFO - { - // Must be the first entry in this struct - Zero means command is unconditional - LLINK conditional_information = 0; - // Must be the second entry in this struct and must not be changed - WORD type = ESsmCmdStartApp; - #ifndef SYMBIAN_SSM_FLEXIBLE_MERGE - // Must be the third entry in this struct - WORD version = ECmdStartAppInitialVersion; - #else - // This version supports priority of the command - WORD version = ECmdStartAppVersionWithPriority; - #endif - // Can have a higher severity defined in TCmdErrorSeverity - WORD severity = ECmdIgnoreFailure; - // VALUE REQUIRED - full path to the application - LTEXT name = ""; - // Passed to the "Tail End" at the command line - // see CApaCommandLine. Maximum argument length allowed is 256 chars. - LTEXT args = ""; - // Can also be ESsmWaitForSignal or ESsmDeferredWaitForSignal - BYTE execution_behaviour = ESsmFireAndForget; - // Time in milliseconds for every retry on failure - LONG timeout = 0; - // Number of times to retry on failure - WORD retries = 0; - // Set to 1 if app is viewless - BYTE viewless = 0; - // Set to 1 if app should be launched in the background - BYTE background = 0; - // zero means no monitoring is required, SSM_MONITOR_INFO - // should be used if monitoring is required - LLINK monitor_info = 0; - #ifdef SYMBIAN_SSM_FLEXIBLE_MERGE - // The order of the command in the list - range can be from 0x00 to 0xffffu - WORD priority = KDefaultCommandPriority; - #endif - } - -/** -Struct for starting processes. - -STRUCT SSM_START_PROCESS_INFO - { - // Must be the first entry in this struct - Zero means - // command is unconditional - LLINK conditional_information = 0; - // Must be the second entry in this struct and must not be changed - WORD type = ESsmCmdStartProcess; - #ifndef SYMBIAN_SSM_FLEXIBLE_MERGE - // Must be the third entry in this struct - WORD version = ECmdStartProcessInitialVersion; - #else - // This version supports priority of the command - WORD version = ECmdStartProcessVersionWithPriority; - #endif - // Can have a higher severity defined in TCmdErrorSeverity - WORD severity = ECmdIgnoreFailure; - // VALUE REQUIRED - full path to the process - LTEXT name = ""; - // Passed to the "Tail End" at the command line - // see CApaCommandLine. Maximum argument length allowed is 256 chars. - LTEXT args = ""; - // Can also be ESsmWaitForSignal or ESsmDeferredWaitForSignal - BYTE execution_behaviour = ESsmFireAndForget; - // Time in milliseconds for every retry on failure - LONG timeout = 0; - // Number of times to retry on failure - WORD retries = 0; - // zero means no monitoring is required, - // SSM_MONITOR_INFO should be used if monitoring is required - LLINK monitor_info = 0; - #ifdef SYMBIAN_SSM_FLEXIBLE_MERGE - // The order of the command in the list - range can be from 0x00 to 0xffffu - WORD priority = KDefaultCommandPriority; - #endif - } /** -Struct for monitoring information. - -STRUCT SSM_MONITOR_INFO - { - // Must be the first entry in this struct and must not be changed - WORD type = ESsmMonitorInfo; - // Must be the second entry in this struct - WORD version = ESsmMonitorInfoInitialVersion; - // OS Restart policy to be used if component restarting has failed - BYTE restart_policy = ESsmIgnoreOnFailure; - // Restart mode when restart_policy=ESsmRestartOSWithMode - BYTE restart_mode; - // Delay in milliseconds between retries - LONG timeout = 0; - // Number of times to attempt to restart a failed component - WORD retries = 0; - }

-System Health -Manager Overview -System Health -Manager Concepts + + + + + +Requesting +and Cancelling Monitoring for a ProcessThis tutorial describes how to request and cancel monitoring for +a process. +

Introduction

Before monitoring a process, SHMA +reads the following information from SSM:

file name of the process +to be launched
arguments required for +the process
execution behaviour +(See TSsmExecutionBehaviour for more information)
time-out to wait for +process to start before considering it as a failure
number of retries if +an application or a process fails to start.

RSysMonSession is the client interface for SHMA.

Procedure

The following methods can be used to request +monitoring a process or an application:

EXPORT_C void RSysMonSession::MonitorL( const CSsmStartupProperties& aSsmStartupProperties, + const RProcess& aProcess, + TBool aExecuteRecoveryMethodOnFailure )EXPORT_C void RSysMonSession::MonitorSelfL( const CSsmStartupProperties& aSsmStartupProperties )

When the SysMon server receives monitoring request, it checks that the +client has appropriate PlatSec capabilities, and that the process is not currently +being monitored. A client which is monitoring itself can use the following +method to cancel monitoring:

EXPORT_C void RSysMonSession::CancelMonitorSelfL()

It +is not possible for a client to cancel monitoring of another process, even +if it was responsible for requesting monitoring.

Example

The +following code fragment illustrates how a client can request monitoring using +SHMA, specifying that the monitored process must be restarted in the event +of failure and that, if it cannot be restarted, the device must be rebooted.

... +// Monitoring a process using SysMon. + +LIT( KMonitoredProcess, "monitoredprocess.exe" ); + +// Properties for the application +CSsmStartupProperties *ssmProp = CSsmStartupProperties::NewLC( KMonitoredProcess, KNullDesC ); + +//ESsmWaitForSignal is the execution behaviour for starting the process. +ssmProp->SetExecutionBehaviour( ESsmWaitForSignal ); +TSsmMonitorInfo monitorInfo; +monitorInfo.iRestartPolicy = ESsmRestartOS; + +//Startup mode to restart the OS +monitorInfo.iRestartMode = 0; + +//Infinite time-out +monitorInfo.iTimeout = 0; + +//No of retries if an application or a process fails to start. +monitorInfo.iRetries = 1; + +ssmProp->SetMonitorInfoL( monitorInfo ); + +RProcess process; + +TInt err = process.Create( KMonitoredProcess, KNullDesC ); +User::LeaveIfError( err ); +CleanupClosePushL( &process ); +process.Resume(); + +// instantiate a session +RSysMonSession sess; + +//Open a session +sess.OpenL(); + +//Create a monitor for the session +TRAP( err, sess.MonitorL( *ssmProp, process ) ); +sess.Close(); +CleanupStack::PopAndDestroy( 2, ssmProp );

The following +code fragments illustrate the structs in a resource file used for process +monitoring:

STRUCT SSM_START_APP_INFO + { + // Must be the first entry in this struct - Zero means command is unconditional + LLINK conditional_information = 0; + // Must be the second entry in this struct and must not be changed + WORD type = ESsmCmdStartApp; + #ifndef SYMBIAN_SSM_FLEXIBLE_MERGE + // Must be the third entry in this struct + WORD version = ECmdStartAppInitialVersion; + #else + // This version supports priority of the command + WORD version = ECmdStartAppVersionWithPriority; + #endif + // Can have a higher severity defined in TCmdErrorSeverity + WORD severity = ECmdIgnoreFailure; + // VALUE REQUIRED - full path to the application + LTEXT name = ""; + // Passed to the "Tail End" at the command line + // see CApaCommandLine. Maximum argument length allowed is 256 chars. + LTEXT args = ""; + // Can also be ESsmWaitForSignal or ESsmDeferredWaitForSignal + BYTE execution_behaviour = ESsmFireAndForget; + // Time in milliseconds for every retry on failure + LONG timeout = 0; + // Number of times to retry on failure + WORD retries = 0; + // Set to 1 if app is viewless + BYTE viewless = 0; + // Set to 1 if app should be launched in the background + BYTE background = 0; + // zero means no monitoring is required, SSM_MONITOR_INFO + // should be used if monitoring is required + LLINK monitor_info = 0; + #ifdef SYMBIAN_SSM_FLEXIBLE_MERGE + // The order of the command in the list - range can be from 0x00 to 0xffffu + WORD priority = KDefaultCommandPriority; + #endif + } + +/** +Struct for starting processes. + +STRUCT SSM_START_PROCESS_INFO + { + // Must be the first entry in this struct - Zero means + // command is unconditional + LLINK conditional_information = 0; + // Must be the second entry in this struct and must not be changed + WORD type = ESsmCmdStartProcess; + #ifndef SYMBIAN_SSM_FLEXIBLE_MERGE + // Must be the third entry in this struct + WORD version = ECmdStartProcessInitialVersion; + #else + // This version supports priority of the command + WORD version = ECmdStartProcessVersionWithPriority; + #endif + // Can have a higher severity defined in TCmdErrorSeverity + WORD severity = ECmdIgnoreFailure; + // VALUE REQUIRED - full path to the process + LTEXT name = ""; + // Passed to the "Tail End" at the command line + // see CApaCommandLine. Maximum argument length allowed is 256 chars. + LTEXT args = ""; + // Can also be ESsmWaitForSignal or ESsmDeferredWaitForSignal + BYTE execution_behaviour = ESsmFireAndForget; + // Time in milliseconds for every retry on failure + LONG timeout = 0; + // Number of times to retry on failure + WORD retries = 0; + // zero means no monitoring is required, + // SSM_MONITOR_INFO should be used if monitoring is required + LLINK monitor_info = 0; + #ifdef SYMBIAN_SSM_FLEXIBLE_MERGE + // The order of the command in the list - range can be from 0x00 to 0xffffu + WORD priority = KDefaultCommandPriority; + #endif + } /** +Struct for monitoring information. + +STRUCT SSM_MONITOR_INFO + { + // Must be the first entry in this struct and must not be changed + WORD type = ESsmMonitorInfo; + // Must be the second entry in this struct + WORD version = ESsmMonitorInfoInitialVersion; + // OS Restart policy to be used if component restarting has failed + BYTE restart_policy = ESsmIgnoreOnFailure; + // Restart mode when restart_policy=ESsmRestartOSWithMode + BYTE restart_mode; + // Delay in milliseconds between retries + LONG timeout = 0; + // Number of times to attempt to restart a failed component + WORD retries = 0; + }

+System Health +Manager Overview +System Health +Manager Concepts

\ No newline at end of file