Initial contribution of the Adaptation Documentation.
<?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><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. </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">&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>
</related-links></concept>