Requesting and Cancelling 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;
    }