S60 Startup List Management API Specification C: Using Startup List Management API

To correctly use Startup List Management API the application developer must create a startup control file containing metadata about the application to be added to the startup list. The metadata contains the full path of the application executable and startup recovery policy used in case of an error in application startup. In order to add several executables into the startup list, the application developer can declare several metadata sections in a single startup control file. For detailed description about the metadata, see section API class structure.

The metadata is in a resource file format and needs to be compiled by Symbian resource file compiler epocrc. The compiled resource file, i.e. the startup control file, must be installed into the import directory of Software Installer UI private folder in the Phone memory drive (c:\private\101f875a\import\).

In addition, the following requirements must be met:

• The installation package containing the application must be trusted, i.e. it must be signed with a valid certificate that chains to one of the root certificates on device.
• The installation package must install the application executable to be added into the startup list.
• The installation package type must be SISAPP (SA). The package types PARTIALUPGRADE (PU) and SISPATCH (SP) are supported since S60 release 3.1.
• In case of an embedded package, the control file must be included in the parent package.
• The control file must be named as [package UID].rsc, where package UID equals to the UID of the installation package.
• The control file must not contain any other resource items than those defined in the API class structure section.

If any of the requirements above is not met, the Software Installer UI ignores the startup control file and no items are added to the startup list.

An application is automatically removed from a start-up list during uninstallation.

Adding one executable into the start-up list

First of all, the start-up control file must be created for an executable.

/*
* ==============================================================================
*  Name        : [12345678].rss
*  Part of     : Example application
*  Description : A startup control file to add executable to the startup list.
*  Version     : 1
*
* ==============================================================================
*/

#include <startupitem.rh>

RESOURCE STARTUP_ITEM_INFO exampleappl
{
executable_name = "c:\\sys\\bin\\example.exe";
recovery = EStartupItemExPolicyNone;
}

The compiled startup control file is installed into the import directory of Software Installer UI private folder in Phone memory drive (c:\private\101f875a\import\) as follows:

/*
* ==============================================================================
*  Name        : exampleappl.pkg
*  Part of     : Example application
*  Description : Installation package file description for example application.
*  Version     : 1
*
* ==============================================================================
*/

;Languages
EN,FI

;Header
#{"Example application","Esimerkkisovellus"},(12345678),1,0,0, TYPE=SA

%{"Nokia Inc","Nokia Oy"}
:"Nokia"

"data\armv5\listener.exe"-"c:\sys\bin\example.exe"
"data\data\commonresource.rsc"-"c:\resource\apps\commonresource.rsc"
"data\data\[0x12345678].rsc"-"c:\private\101f875a\import\[12345678].rsc"

Adding multiple executables

Several executables can be added into the startup list by declaring several metadata sections in a single startup control file.

/*
* ==============================================================================
*  Name        : [12345678].rss
*  Part of     : Example application
*  Description : A startup control file to add two executables to startup list.
*  Version     : 1
*
* ==============================================================================
*/

#include <startupitem.rh>

RESOURCE STARTUP_ITEM_INFO exampleappl
{
executable_name = "c:\\sys\\bin\\example.exe";
recovery = EStartupItemExPolicyNone;
}

RESOURCE STARTUP_ITEM_INFO dispatcher
{
executable_name = "!:\\sys\\bin\\dispatcher.exe"; // dispatcher can be installed
                                                  // to memory card as well
recovery = EStartupItemExPolicyNone;
} 

Error handling

None.

Memory overhead

None.

Extensions to the API

There are no extensions to this API.