Modifications to Keyspaces

Installating keyspaces

Steps to be taken at device creation

There are two ways of equipping an application with a keyspace when the application is installed on the device. One is to save the keyspace to the directory z:\private\10202BE9\at ROM build, as explained above. This method has the disadvantage that a keyspace created in this way cannot subsequently be uninstalled, though it can be modified by the software installer or firmware upgrades. The other way is to install the keyspace along with the application using the software installer. Application writers cannot do this on their own because the process requires one of the necessary files, the stub .sis file, to be set up appropriately by device creators, and another, the upgrade .sis file, to be signed by Symbian.

You install a keyspace by placing a stub .sis file (installation file) in the \System\Install<file>\System\Install</file> directory in ROM. This file is written by device creators rather than developers. It must contain the central repository server executable. It must list all the ROM-supplied keyspace files which are ntended to be upgradable.

The following template is supplied for use in device creation. Device creators are free to modify the major and minor version numbers but are strongly recommended to retain the UID 0x20007770 which is allocated for use with the central repository.

;
; template_stub.pkg

; Template Central Repository Stub Package File

; Copyright (c) 2006 Symbian Software Ltd. All rights reserved.


; Language
&EN

; Package Header

; #{"Package name"}, (Package UID), major-version, minor-version, build-number

; You are free to modify the version and build numbers but the package UID
; should NOT be altered.

#{"Centrep Stub"}, (0x20007770), 0, 0, 0

; Vendor
%{"Symbian Software Ltd."}
:"Symbian Software Ltd."

; Central Repository Server - this must be in the stub package file
"<INSERT-LOCAL-PATH-HERE>centralrepositorysrv.exe"-"z:\sys\bin\centralrepositorysrv.exe"
; eg "\epoc32\release\armv5\urel\centralrepositorysrv.exe"-"z:\sys\bin\centralrepositorysrv.exe"

; List of upgradeable ROM keyspaces

; If you wish to provide the ability for a keyspace supplied in ROM to be upgraded
; by Software Install then list it below.  Any keyspaces not included in this list
; may not be upgraded.

; Each entry in the list should take the following form:
;  ""-"z:\private\10202be9\<keyspace-file.ext>"

; For example:
;  ""-"z:\private\10202be9\ace1ace1.cre"
REPLACE THIS LINE WITH THE KEYSPACE LIST OR REMOVE IF ROM KEYSPACES SHOULD NOT BE UPGRADED

How to upgrade a keyspace during software installation

Installing an application is explained here and upgrading is explained here. Upgrading software in ROM is explained here. It involves using the CreateSIS tool to compile files listed in a package (.pkg) file into an installation (.sis) file. A package file may refer to an existing .sis file: if so, the .sis file is said to be embedded. An upgrade is essentially the installation of a software patch. You upgrade a keyspace in the same way as you upgrade the associated application and the two operations are often combined. Installing a keyspace is the same as upgrading one: you are eclipsing the stub .sis file discussed in the previous section. To do this you need:

• the upgrade .pkg file and corresponding .sis file,

• and the application .pkg file and corresponding .sis file if you are upgrading the application.

A third party developer cannot create a stub .sis file: it must have been created as part of the device's ROM. If one does not exist, you cannot upgrade a keyspace.

The upgrade .sis file must be signed.

You do not need the application .sis and .pkg files if you are installing or upgrading a keyspace without the associated application.

In both cases you write a .pkg file with details of the software upgrade. It can upgrade the application and the keyspace at the same time or could upgrade the keyspace alone as shown in the following example:

&EN

#{"Example new keyspace"}, (0x20007770), 1, 2, 3, TYPE=SP

%{"Symbian Software Ltd."}
:"Symbian Software Ltd."

; Install keyspace in Central Repository’s private data cage
"12345678.cre"-"c:\private\10202be9\12345678.cre"

The important thing is that the package UID, (0x20007770), must match the UID in the stub package header. You compile the .pkg file into a .sis file and, if required, go through the signing process at this point. At this point you can deploy the keyspace .sis file on its own. However, it is more usual to embed the keyspace .sis file into your application .pkg file and install the application.

How to uninstall a keyspace during software uninstallation

You uninstall a keyspace by uninstalling the application which it was embedded in. This has the effect of uninstalling all the software patches with which you upgraded the keyspace. If there is a version of the keyspace in ROM, placed there at device creation, it comes back into use. If the keyspace was installed subsequently then no version of it remains after uninstallation. It is not possible to remove individual upgrades, only the entire set of upgrades which have ever been applied.

Effects of upgrading a keyspace during software installation

An upgrade to a keyspace may conflict with user modifications to the keyspace. In that case the existing settings are merged with those in the upgrading keyspace in accordance with the following rules. The keyspaces are merged in accordance with the principle that user modifications override upgrade modifications.

• If a setting exists in the existing keyspace on the phone and the upgrading keyspace and the existing setting has not been modified by the user, the upgrading setting replaces the existing setting.

• If a setting exists in the existing keyspace and the upgrading keyspace and the existing setting has been modified by the user, the existing setting is preserved.

• If a setting exists in the existing keyspace but not in the upgrading keyspace, the existing setting is preserved.

• If a setting exists in the upgrading keyspace but not in the existing keyspace, the upgrading setting is created.

Upgrades preserve the existing platform security policies. Metadata values assigned by default or to a range remain unchanged, but metadata values of individual keys take their upgrade settings.

The first time you upgrade a keyspace which is provided in ROM you only need to list the keys which are being added to or changed from the ROM keyspace. However, if you are performing an upgrade to a keyspace which has previously been upgraded, you must include all the changes in all the previous upgrades: this is also the case where the keyspace was originally installed as an upgrade to a stub .sis file.

If there are notification requests on any of the keys, the requests will complete as a result of installation, upgrading and uninstallation. If transactions are pending during an upgrade or uninstallation, those transactions will fail. It is advisable to close all sessions on a keyspace before uninstalling.

Firmware updates

Symbian provides limited support for firmware updates to ROM over a serial connection or by FOTA (firmware over the air). The generic term for these firmware updates is FOTx. When this happens, the Central Repository detects the upgrade when the device is next restarted and makes corresponding updates to its keyspaces. A firmware update reboots the device: as part of this process the Central Repository gets the current ROM version using SysUtil::GetSWVersion and compares it with a previously saved version. Where the Central Repository detects a difference it merges the relevant keyspaces at the level of the file or of individual settings.

The rule is that user values (settings modified by the user) override SWI values (settings modified by a software upgrade or installation) and that SWI values override ROM values.

There are two cases where a difference is resolved at the level of the file.

• Where a keyspace is non-persisted (ROM was never overridden), the ROM update replaces the current ROM.

• Where the ROM update deletes an existing ROM file, any persisted keyspaces are removed along with the deleted file. This rule also applies when the user has modified the keyspace in existing ROM, but not when the software installer has modified the keyspace in existing ROM.

Where the ROM update conflicts with user-modified keyspaces or SWI-modified keyspaces, the new ROM is merged with the persisted file at the level of the setting. The rules for resolving conflicts involve creation, modification and deletion of settings and they vary according to the point at which a setting was created.

• If a setting is created by the firmware update it is simply added to the keyspace.

• If a setting was created by the software installer, an attempted modification by FOTx is not applied. A FOTx update will have no impact on any settings created by the software installer that are not in ROM.

• If a setting was created by the device user, an attempted modification by FOTx is not applied. A FOTx update will have no impact on any settings created by the user that are not in ROM.

• If a setting was present in existing ROM, these rules apply:

  • A modification by the user overrides a modification by FOTx.

  • A modification by the user overrides a deletion by FOTx.

  • A deletion by the user is cancelled by a modification by FOTx.

  • A deletion by the user is confirmed by a deletion by FOTx.

  • A modification by the software installer overrides a modifcation by FOTx.

  • A modification by the software installer overrides a deletion by FOTx.

  • Deletions by the software installer do not occur.

• Conflicts between user modified keyspaces and SWI modified keyspaces were covered in the previous section.

Restore factory settings

The Central Repository can restore factory settings across all keyspaces. Only device creators can restore factory settings by starting the Central Repository in a special mode during a reboot. The restore does not affect all settings in the keyspace, only those which have the appropriate metadata bit set.

The effect of restoring factory settings is to revert settings to their value at the most recent software install or firmware update, to reverse changes made by the user. It does not return the device to the state in which it was created. To reverse the effects of software installation and firmware updates an uninstall is required.

• If a setting was created by the user, a restore factory settings operation deletes the setting.

• If a setting was created by SWI, a restore factory settings operation reverts the setting to the value it last had after any modifications by SWI or FOTx.

• If a setting was created in existing ROM and modified by the user only, the setting reverts to its original value.

• If a setting was created in existing ROM and deleted by the user, the setting reverts to the value it last had after any modifications by SWI or FOTx.

• If a setting was created in existing ROM and modified or deleted by SWI or firmware upgrade, the changes are not reversed.

Backup and restore

The Central Repository can back up data in a repository. Backup does not affect all repository entries, only those which have the appropriate metadata bit set.

The effect of a restore is to merge the backed up values of backed up settings with the current values of non-backed up settings. It does not mean restoring the device state at the time of backup.

• A backed up setting is restored to its value at the time of backup.

• A non-backed up setting retains its current value.

• A backed up setting is restored after a deletion, but only if the backup took place before the deletion.

• A non-backed up setting is never restored after a deletion.