<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-998DCA78-2488-5D6D-B5B3-D86C52F32823" xml:lang="en"><title>Modifications

to Keyspaces</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>This topic describes the types of keyspace modifications </p>

<p>Keyspaces are modified by operations including </p>

<ul>

<li id="GUID-3642D0A6-456B-55A8-8CDF-FE5E56C4C5BC"><p>installation of new

software, </p> </li>

<li id="GUID-8FEA1A45-CC2B-5346-8ABC-853CF3EC319D"><p>firmware updates, </p> </li>

<li id="GUID-DDFAA956-9F88-5CE5-A00E-A6B7B90453AF"><p>the restore factory

settings operation, and </p> </li>

<li id="GUID-2948CF00-2335-51CF-A5A1-9746D62FAB53"><p>backup and restore. </p> </li>

</ul>

<p>The integrity of the keyspace is maintained over modifications of this

kind by applying the appropriate rules for each operation and combination

of operations. </p>

<section id="GUID-95F7E0FB-1435-4B68-B246-9DB111C31FC2"><title>Installating keyspaces </title> <p><b>Steps to be taken at

device creation</b> </p><p>         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 <filepath>z:\private\10202BE9\</filepath>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.  </p><p> 

        You install a keyspace by placing a stub .sis file (installation file)

in the <filepath>\System\Install</filepath>&lt;file&gt;\System\Install&lt;/file&gt;

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.   </p><p> 

        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.  </p><codeblock xml:space="preserve">;

; 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

</codeblock> <p><b>How to upgrade a keyspace during software installation</b> </p> <p>Installing

an application is explained <xref href="GUID-9C4C3F93-4F9F-5FE0-9979-7729CE255255.dita">here</xref> and

upgrading is explained <xref href="GUID-0B9C52E5-490D-5CF0-9789-1EC50D6C7919.dita">here</xref>.

Upgrading software in ROM is explained <xref href="GUID-30FFE6C4-FE79-55F9-A805-D98F83D90441.dita">here</xref>.

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: </p> <ul>

<li id="GUID-BCEB30EA-7C0F-5333-9033-0DA3521A56E7"><p>the upgrade .pkg file

and corresponding .sis file, </p> </li>

<li id="GUID-DA3E131F-98C3-57AF-BD28-C6858A2F53E4"><p>and the application

.pkg file and corresponding .sis file if you are upgrading the application. </p> </li>

</ul> <p>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. </p> <p>The upgrade .sis file must be signed. </p> <p>You

do not need the application .sis and .pkg files if you are installing or upgrading

a keyspace without the associated application. </p> <p>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: </p> <codeblock id="GUID-5436AF6A-5A82-51A4-BC52-3FEDFCBA431F" xml:space="preserve">&amp;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"

</codeblock> <p>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. </p> <p><b>How to uninstall a keyspace during

software uninstallation</b> </p> <p>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. </p> <p><b>Effects

of upgrading a keyspace during software installation</b> </p> <p>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. </p> <ul>

<li id="GUID-D0E7853C-D91D-53C4-9DA8-C581A9AB5A79"><p>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. </p> </li>

<li id="GUID-C94441FB-0967-53D5-9EAE-750BDABE48E2"><p>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. </p> </li>

<li id="GUID-DEEF31A4-5CF6-540A-A81A-E43DF2026C77"><p>If a setting exists

in the existing keyspace but not in the upgrading keyspace, the existing setting

is preserved. </p> </li>

<li id="GUID-1270CCEC-7836-51BA-99EA-9BD46CA4BBCA"><p>If a setting exists

in the upgrading keyspace but not in the existing keyspace, the upgrading

setting is created. </p> </li>

</ul> <p>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. </p> <p>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. </p> <p>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. </p> </section>

<section id="GUID-D3331692-F84F-4421-8314-E46FA17F02A4"><title>Firmware updates</title> <p>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 <codeph>SysUtil::GetSWVersion</codeph> 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. </p> <p>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. </p> <p>There are

two cases where a difference is resolved at the level of the file. </p> <ul>

<li id="GUID-8B050D35-F362-5B75-A779-DC162C3DFF79"><p>Where a keyspace is

non-persisted (ROM was never overridden), the ROM update replaces the current

ROM. </p> </li>

<li id="GUID-5388506C-9908-518E-A3B4-63E609E0BB55"><p>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. </p> </li>

</ul> <p>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. </p> <ul>

<li id="GUID-D50380BB-2DBC-5320-8221-54DCE3A3C235"><p>If a setting is created

by the firmware update it is simply added to the keyspace. </p> </li>

<li id="GUID-AE312886-DDB5-5B9F-9D73-97741AD8324D"><p>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. </p> </li>

<li id="GUID-91A7F55A-60BD-5267-97F1-BD88F241C2FC"><p>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. </p> </li>

<li id="GUID-ADF63BBA-0F4C-558A-9CC2-8A330F4A3C4A"><p>If a setting was present

in existing ROM, these rules apply: </p> <ul>

<li id="GUID-D4FA6716-FEC9-5A84-9C32-C429D6C105A0"><p>A modification by the

user overrides a modification by FOTx. </p> </li>

<li id="GUID-6CA71AAD-41F6-5CBA-8F2C-36FABA542A6E"><p>A modification by the

user overrides a deletion by FOTx. </p> </li>

<li id="GUID-7F619ECB-A5CE-5D42-B3AE-C261FD6222F1"><p>A deletion by the user

is cancelled by a modification by FOTx. </p> </li>

<li id="GUID-CE7F094E-4270-535D-8198-71C8D021A8C3"><p>A deletion by the user

is confirmed by a deletion by FOTx. </p> </li>

<li id="GUID-F49E35FF-22E1-5D53-ACE8-551B5B08C41D"><p>A modification by the

software installer overrides a modifcation by FOTx. </p> </li>

<li id="GUID-708220F5-90AD-56F5-B11C-CF178F3B56CB"><p>A modification by the

software installer overrides a deletion by FOTx. </p> </li>

<li id="GUID-12B84510-4DB5-530B-B21A-B17E7FEED881"><p>Deletions by the software

installer do not occur. </p> </li>

</ul> </li>

<li id="GUID-75404D8E-11D5-53EE-963A-53C3E1E9A720"><p>Conflicts between user

modified keyspaces and SWI modified keyspaces were covered in the previous

section. </p> </li>

</ul> </section>

<section id="GUID-01DD59CD-E22D-43C5-8E62-2271F176C705"><title>Restore factory settings</title> <p>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. </p> <p>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. </p> <ul>

<li id="GUID-95098D31-07C2-508A-A5C0-F2A9E9191306"><p>If a setting was created

by the user, a restore factory settings operation deletes the setting. </p> </li>

<li id="GUID-771F205B-218A-50E2-A18B-F4FCE751905E"><p>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. </p> </li>

<li id="GUID-E325ABDC-1286-5763-8C01-6D99662C20B6"><p>If a setting was created

in existing ROM and modified by the user only, the setting reverts to its

original value. </p> </li>

<li id="GUID-4DAA44F5-218D-52A1-BE53-688B3FF4540F"><p>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. </p> </li>

<li id="GUID-09EA88F1-2A32-5207-B6FE-FF9E0B3C9F85"><p>If a setting was created

in existing ROM and modified or deleted by SWI or firmware upgrade, the changes

are not reversed. </p> </li>

</ul> </section>

<section id="GUID-D02F0D21-6081-4C5C-B9E1-63DE65C7DF82"><title>Backup and restore</title> <p>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. </p> <p>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. </p> <ul>

<li id="GUID-11F0ED5C-0C50-55F3-886D-E65042DAAE63"><p>A backed up setting

is restored to its value at the time of backup. </p> </li>

<li id="GUID-F1383EFE-D685-5923-AF99-1181E34860BB"><p>A non-backed up setting

retains its current value. </p> </li>

<li id="GUID-943725DE-9598-5ADF-B3B3-36DA8EE6FA26"><p>A backed up setting

is restored after a deletion, but only if the backup took place before the

deletion. </p> </li>

<li id="GUID-3ECAB92B-B9B3-5F01-801F-5FEA81A632CD"><p>A non-backed up setting

is never restored after a deletion. </p> </li>

</ul> </section>

</conbody><related-links>

<link href="GUID-1C683226-C142-5C7B-BD20-060058352B08.dita"><linktext>Central Repository

Guide</linktext></link>

<link href="GUID-724BA3CD-7648-51DF-9285-3AA7470987F4.dita"><linktext>Optimising

Repository                 Access</linktext></link>

<link href="GUID-E87018CD-01B4-5886-87FC-CD25EE90587D.dita"><linktext>Central Repository

                Transactions</linktext></link>