--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-998DCA78-2488-5D6D-B5B3-D86C52F32823.dita	Thu Jan 21 18:18:20 2010 +0000
@@ -0,0 +1,271 @@
+<?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><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
+&amp;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
+"&lt;INSERT-LOCAL-PATH-HERE&gt;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\&lt;keyspace-file.ext&gt;"
+
+; 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><title>Firmware updates</title> <p>Symbian OS 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><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><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>
\ No newline at end of file