How to use the Dynamic Startup Configuration API

Dynamic Startup Configurations, DSC, enable the startup procedure to be extended after the ROM has been built. A DSC can include applications installed before or after the ROM is built.

A Static Startup Configuration, SSC, may include one or more DSC insertion points. A DSC, like an SSC, is a list of instructions to start applications. Typically the items listed will be After Market Applications (AMA) and After Market Services without a UI (AMS). Collectively these are referred to as After Market Components (AMC).

It is not possible to change an SSC once the ROM has been built, so the points during the startup at which DSCs may be executed are fixed by the device manufacturer.

Each DSC is identified by a UID. One DSC has a default UID (KDefaultSymbianDsc) provided by Symbian : Typically this default DSC will be executed at the end of the startup procedure. The purpose of the default DSC is to allow generic AMCs.

A DSC is inserted into an SSC using a START_AMC_STARTER structure (defined in sysstart.rh).

struct START_AMC_STARTER            // For starting AMAStarter with a particular DSC
   {
   WORD type = EStartupAMAStarter ; // Must not be changed
   LONG dsc_id = KDefaultDscId ;    // DSC id for AMAStarter.  One DSC must have KDefaultDscId.
   }

Careful consideration should be given by licencees when including this instruction before the end of the startup process.

• Starting anything unnecessarily early slows the boot process

• Many third party applications are dependent on Symbian servers, especially the AppArc server.

• Each DSC is processed sequentially and must complete before the SSC continues

Though all of the insertion points for DSCs (and therefore their UIDs) are fixed when the ROM is built, DSCs themselves may be created and deleted at run time. Items may be added, removed, updated and retrieved. An empty or non-existant DSC is simply ignored when the SSC is processed.

The DSC API is used:

• When a user wishes to configure an application to start automatically

• By the After Market Application Starter when processing a DSC

• By an application wishing to examine a DSC.

• By an application wishing to edit a DSC

Any application wishing to read or write using the DSC API requires either or both ReadDeviceData and WriteDeviceData capability.

The API comprises RDscStore and CDscItem. It is dependant upon common startup classes CStartupProperties, TStartupMethod, TStartupType and TRestartAction

Note that RDscStore is NOT derived from RSessionBase.

NONSHARABLE_CLASS ( RDscStore )
    {

public:
    IMPORT_C RDscStore();
 
    IMPORT_C void OpenL();
    IMPORT_C void Close();
    IMPORT_C TBool IsOpened() const;
 
    IMPORT_C void CreateDscL( const TUid& aDscId, const TDesC& aDescription );
    IMPORT_C void CreateDscL();
    IMPORT_C void DeleteDscL( const TUid& aDscId );
    IMPORT_C TBool DscExistsL( const TUid& aDscId ) const;
    IMPORT_C TBool DscExistsL() const;
    IMPORT_C void GetDscDescriptionL( const TUid &aDscId, TDes& aDescription ) const;
    IMPORT_C void AddItemL( CDscItem& aItem,TDscPosition aPos );
    IMPORT_C void AddItemL( CDscItem& aItem );
    IMPORT_C TBool ItemExistsL( const CDscItem& aItem ) const;
    IMPORT_C void EnumOpenLC( const TUid& aDscId );
    IMPORT_C void EnumOpenLC();
    IMPORT_C CDscItem* EnumReadNextL();
    IMPORT_C void EnumClose();
    IMPORT_C void ReadItemL( CDscItem& aItem );
    IMPORT_C void UpdateItemL( const CDscItem& aItem );
    IMPORT_C void DeleteItemL( const CDscItem& aItem );

    };

NONSHARABLE_CLASS ( CDscItem ) : public CBase
    {
public:
    IMPORT_C static CDscItem* NewL();
    IMPORT_C ~CDscItem();

    IMPORT_C void SetDscId( const TUid& aDscId );
    IMPORT_C TUid DscId() const;
    IMPORT_C TUint ItemId() const;
    IMPORT_C TPtrC FileName() const;
    IMPORT_C TPtrC Args() const;
    IMPORT_C TStartupType StartupType() const;
    IMPORT_C TStartMethod StartMethod() const;
    IMPORT_C TInt NoOfRetries() const;
    IMPORT_C TInt Timeout() const;
    IMPORT_C TBool Monitored() const;
    IMPORT_C TBool Viewless() const;
    IMPORT_C TBool StartInBackground() const;
 
    IMPORT_C void SetFileParamsL( const TDesC& aFileName, const TDesC& aArgs );
    IMPORT_C void SetStartMethodL( TStartMethod aStartMethod );
    IMPORT_C void SetNoOfRetriesL( TInt aNumRetries );
    IMPORT_C void SetTimeoutL( TInt aTimeout );
    IMPORT_C void SetMonitored( TBool aMonitored );
    IMPORT_C void SetStartupType( TStartupType aType );
    IMPORT_C void SetViewless( TBool aViewless );
    IMPORT_C void SetStartInBackground( TBool aStartInBackground );

    IMPORT_C const CStartupProperties& StartupProperties() const;
    };

Usage of the API is straightforward: Create an instance of RDscStore, call OpenL() and use the functions as appropriate.

Most of the functions leave with error codes, rather than returning. The error code is typically KErrNotReady, if the DSC database is not set up, or the code returned by the encapsulated database client.

There are several possible models for achieving the the same end.

• An application might contain code to install itself when it is first executed or via a user option. It would need to create a DSC client and add itself to a DSC. Significantly it would require both ReadDeviceData and WriteDeviceData capability.

• The installation package could include a helper application which would run automatically on installation. The helper would contain the DSC client. Only the helper application would require ReadDeviceData and WriteDeviceData capabilities. The disadvantage of this solution is that there would potentially be a multitude of almost identical helper applications installed on the phone.

• A third solution is a shared helper application which wraps a DSC client. Installation packages would need to place a resource file into a shared data area.

It is up to the licensee or the developer of the client to advise the user, or to seek the user's consent, before adding an After Market Component to a DSC. Symbian OS does not do this automatically.

Any application with sufficient capability may simply create a DSC client and connect to the server. It is likely that most devices will have a 'settings' application which does this. Note that additions to DSCs made in this manner will be lost when restoring from a backup.

This activity is only performed by the After Market Application starter which is provided by Symbian. The AMA starter is an Optional Replaceable Component.