Startup list Management API Specification

Contents

1 Overview

This document describes Startup List Management API in the Symbian platform.

Startup List Management API provides means for third party developers to add their native applications into the device's modifiable startup list to launch the application at device boot up. 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.


API categorypublic
API typec++
Existed sinceLegacy S60 3.0
Location/sf/mw/appinstall/appinstall_pub/startup_list_management_api
Buildfiles/sf/mw/appinstall/appinstall_pub/startup_list_management_api/group/bld.inf


1.1 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.

1.2 Changes

This API is available for S60 3rd Edition and onwards.

1.3 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.

1.4 Class Structure

Summary of API classes and header files
ClassesFiles
No classes/epoc32/include/mw/StartupItem.hrh, /epoc32/include/mw/StartupItem.rh

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. Currently, only EStartupItemExPolicyNone value can be used.

2 Using The 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 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, that is, the startup control file, must be installed in 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:

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 startup list during uninstallation.

2.1 Adding one executable into the startup list

First of all, the startup 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"

2.1.1 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;
}

2.2 Extensions to the API

There are no extensions to this API.

3 Glossary

3.1 Abbreviations

API Application Programming Interface
SISX SIS eXtended
UI User Interface

3.2 Definitions

Definition Description
UID Unique ID allocated by Symbian for specific purposes.
Startup control file File containing metadata about items in modifiable startup list.