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
    }