S60 3.x Startup List Management API Specification Document

Changes in S60 3.2 Startup List Management API documentation

1.0 17.04.2007 Approved

Changes in S60 3.0 Startup List Management API documentation

1.0 First version

Purpose

This document describes Startup List Management API in S60.

Startup List Management API provides means for third party developers to add their native applications into the device’s modifiable startup list in order to launch the application at device boot up. S60 Starter executes the modifiable startup list at the end of the terminal bootup.

Startup List Management API is applicable only for native applications delivered inside SIS eXtended packages.

S60 or Symbian OS exceptions

This API is available for S60 release 3.0 and onwards.

API description

Startup List Management API defines rules and policies that allow a third party application to make modifications to the device’s startup list during the installation / uninstallation process. The API does not define any classes, but it defines a set of resource file structures and enumerations that each client must declare. This API does not require other SDK APIs.

Use cases

The only use case of this API is to offer third-party developers a mean to get their own application started during a device start-up.

API class structure

This interface has no classes.

A resource file, the structure of which is defined in StartupItem.rh , is needed to define executable(s) started at boot time.

BYTE version Indicates the version of the API. Do not use.

LTEXT Executable_name

Full path to the executable.

WORD recovery

Recovery policy used in case of failure in executable launch.

The TStartupExceptionPolicy enumeration, which is defined in StartupItem.hrh , is used to define the recovery policy in case of failure when launching the executable at device boot up. At the moment, only the value EStartupItemExPolicyNone can be used.

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.

Glossary

Abbreviations

API Application Programming Interface

SISX

SIS eXtended

UI

User Interface

Definitions

UID

Unique ID allocated by Symbian for specific purposes.

Startup control file

File containing metadata about items in modifiable startup list.

References

None