System Monitor

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.

An application or process may also add itself to the System Monitor's list.

Use of the System Monitor API is restricted by capabilites of the client:

WriteDeviceData is required to request a process restart,
ProtServ is required to request an OS restart into Normal mode
PowerMgmt is required to request a restart into Startup mode

The system monitor API is simple and self explanatory. A client must instantiate an RSysMonSession, connect to the SysMon server and open [the session].

// 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() ;  
        
} ;

Monitoring is started with a call to MonitorL() or MonitorSelfL(). Before calling one of these functions, however, a CStartupProperties object must be created and populated with the desired monitoring and restart configuration.

CStartupProperties has a series of Set...() 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 Version() function) as it is designed to remain compatible with future Symbian extensions.

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.

...
// 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() ;
...

Setting up Monitoring in an SSC

Process monitoring is normally configured for processes and applications using START_PROCESS_INFO2 and START_APP_INFO2 resources in an SSC. These are defined in sysstart.rh.

Note that these structures add monitor, startup mode and a localisable error message to START_PROCESS_INFO and START_APP_INFO.

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
    }

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
    }

For more information on how to write a Static Startup Configuration see

System Starter documents.

Setting up Monitoring in a DSC

Aftermarket components started at boot using a Dynamic Startup Configuration (DSC) may also be monitored and restarted by SysMon. The DSC API uses CStartupProperties in the manner described above. An AMC may be restarted on failure but it will not be permitted to reboot the device.