Symbian
Symbian Developer Library

SYMBIAN OS V9.4

Feedback

[Index] [Previous] [Next]


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.

[Top]


Inserting a DSC into an SSC

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.

[Top]


Using the DSC API

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:

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.

The following errors should be expected and handled explicitly:
  • KErrNotReady, the database is not set up

  • KErrLocked, the record is locked by another client

  • KErrNotFound, the DSC or item specified does not exist

  • KErrAlreadyExists, items must be unique

  • KErrArgument, invalid argument/parameter.

Other errors may be passed up the stack.


Adding an After Market Component to a DSC during installation

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

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.


Adding an After Market Component to a DSC under User Control

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.


Processing a DSC

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