|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-998DCA78-2488-5D6D-B5B3-D86C52F32823" xml:lang="en"><title>Modifications |
|
13 to Keyspaces</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>This topic describes the types of keyspace modifications </p> |
|
15 <p>Keyspaces are modified by operations including </p> |
|
16 <ul> |
|
17 <li id="GUID-3642D0A6-456B-55A8-8CDF-FE5E56C4C5BC"><p>installation of new |
|
18 software, </p> </li> |
|
19 <li id="GUID-8FEA1A45-CC2B-5346-8ABC-853CF3EC319D"><p>firmware updates, </p> </li> |
|
20 <li id="GUID-DDFAA956-9F88-5CE5-A00E-A6B7B90453AF"><p>the restore factory |
|
21 settings operation, and </p> </li> |
|
22 <li id="GUID-2948CF00-2335-51CF-A5A1-9746D62FAB53"><p>backup and restore. </p> </li> |
|
23 </ul> |
|
24 <p>The integrity of the keyspace is maintained over modifications of this |
|
25 kind by applying the appropriate rules for each operation and combination |
|
26 of operations. </p> |
|
27 <section id="GUID-95F7E0FB-1435-4B68-B246-9DB111C31FC2"><title>Installating keyspaces </title> <p><b>Steps to be taken at |
|
28 device creation</b> </p><p> There are two ways of equipping an application |
|
29 with a keyspace when the application is installed on the device. One is to |
|
30 save the keyspace to the directory <filepath>z:\private\10202BE9\</filepath>at |
|
31 ROM build, as explained above. This method has the disadvantage that a keyspace |
|
32 created in this way cannot subsequently be uninstalled, though it can be modified |
|
33 by the software installer or firmware upgrades. The other way is to install |
|
34 the keyspace along with the application using the software installer. Application |
|
35 writers cannot do this on their own because the process requires one of the |
|
36 necessary files, the stub .sis file, to be set up appropriately by device |
|
37 creators, and another, the upgrade .sis file, to be signed by Symbian. </p><p> |
|
38 You install a keyspace by placing a stub .sis file (installation file) |
|
39 in the <filepath>\System\Install</filepath><file>\System\Install</file> |
|
40 directory in ROM. This file is written by device creators rather than developers. |
|
41 It must contain the central repository server executable. It must list all |
|
42 the ROM-supplied keyspace files which are ntended to be upgradable. </p><p> |
|
43 The following template is supplied for use in device creation. Device |
|
44 creators are free to modify the major and minor version numbers but are strongly |
|
45 recommended to retain the UID 0x20007770 which is allocated for use with the |
|
46 central repository. </p><codeblock xml:space="preserve">; |
|
47 ; template_stub.pkg |
|
48 |
|
49 ; Template Central Repository Stub Package File |
|
50 |
|
51 ; Copyright (c) 2006 Symbian Software Ltd. All rights reserved. |
|
52 |
|
53 |
|
54 ; Language |
|
55 &EN |
|
56 |
|
57 ; Package Header |
|
58 |
|
59 ; #{"Package name"}, (Package UID), major-version, minor-version, build-number |
|
60 |
|
61 ; You are free to modify the version and build numbers but the package UID |
|
62 ; should NOT be altered. |
|
63 |
|
64 #{"Centrep Stub"}, (0x20007770), 0, 0, 0 |
|
65 |
|
66 ; Vendor |
|
67 %{"Symbian Software Ltd."} |
|
68 :"Symbian Software Ltd." |
|
69 |
|
70 ; Central Repository Server - this must be in the stub package file |
|
71 "<INSERT-LOCAL-PATH-HERE>centralrepositorysrv.exe"-"z:\sys\bin\centralrepositorysrv.exe" |
|
72 ; eg "\epoc32\release\armv5\urel\centralrepositorysrv.exe"-"z:\sys\bin\centralrepositorysrv.exe" |
|
73 |
|
74 ; List of upgradeable ROM keyspaces |
|
75 |
|
76 ; If you wish to provide the ability for a keyspace supplied in ROM to be upgraded |
|
77 ; by Software Install then list it below. Any keyspaces not included in this list |
|
78 ; may not be upgraded. |
|
79 |
|
80 ; Each entry in the list should take the following form: |
|
81 ; ""-"z:\private\10202be9\<keyspace-file.ext>" |
|
82 |
|
83 ; For example: |
|
84 ; ""-"z:\private\10202be9\ace1ace1.cre" |
|
85 REPLACE THIS LINE WITH THE KEYSPACE LIST OR REMOVE IF ROM KEYSPACES SHOULD NOT BE UPGRADED |
|
86 </codeblock> <p><b>How to upgrade a keyspace during software installation</b> </p> <p>Installing |
|
87 an application is explained <xref href="GUID-9C4C3F93-4F9F-5FE0-9979-7729CE255255.dita">here</xref> and |
|
88 upgrading is explained <xref href="GUID-0B9C52E5-490D-5CF0-9789-1EC50D6C7919.dita">here</xref>. |
|
89 Upgrading software in ROM is explained <xref href="GUID-30FFE6C4-FE79-55F9-A805-D98F83D90441.dita">here</xref>. |
|
90 It involves using the CreateSIS tool to compile files listed in a package |
|
91 (.pkg) file into an installation (.sis) file. A package file may refer to |
|
92 an existing .sis file: if so, the .sis file is said to be embedded. An upgrade |
|
93 is essentially the installation of a software patch. You upgrade a keyspace |
|
94 in the same way as you upgrade the associated application and the two operations |
|
95 are often combined. Installing a keyspace is the same as upgrading one: you |
|
96 are eclipsing the stub .sis file discussed in the previous section. To do |
|
97 this you need: </p> <ul> |
|
98 <li id="GUID-BCEB30EA-7C0F-5333-9033-0DA3521A56E7"><p>the upgrade .pkg file |
|
99 and corresponding .sis file, </p> </li> |
|
100 <li id="GUID-DA3E131F-98C3-57AF-BD28-C6858A2F53E4"><p>and the application |
|
101 .pkg file and corresponding .sis file if you are upgrading the application. </p> </li> |
|
102 </ul> <p>A third party developer cannot create a stub .sis file: it must have |
|
103 been created as part of the device's ROM. If one does not exist, you cannot |
|
104 upgrade a keyspace. </p> <p>The upgrade .sis file must be signed. </p> <p>You |
|
105 do not need the application .sis and .pkg files if you are installing or upgrading |
|
106 a keyspace without the associated application. </p> <p>In both cases you write |
|
107 a .pkg file with details of the software upgrade. It can upgrade the application |
|
108 and the keyspace at the same time or could upgrade the keyspace alone as shown |
|
109 in the following example: </p> <codeblock id="GUID-5436AF6A-5A82-51A4-BC52-3FEDFCBA431F" xml:space="preserve">&EN |
|
110 |
|
111 #{"Example new keyspace"}, (0x20007770), 1, 2, 3, TYPE=SP |
|
112 |
|
113 %{"Symbian Software Ltd."} |
|
114 :"Symbian Software Ltd." |
|
115 |
|
116 ; Install keyspace in Central Repository’s private data cage |
|
117 "12345678.cre"-"c:\private\10202be9\12345678.cre" |
|
118 </codeblock> <p>The important thing is that the package UID, (0x20007770), |
|
119 must match the UID in the stub package header. You compile the .pkg file into |
|
120 a .sis file and, if required, go through the signing process at this point. |
|
121 At this point you can deploy the keyspace .sis file on its own. However, it |
|
122 is more usual to embed the keyspace .sis file into your application .pkg file |
|
123 and install the application. </p> <p><b>How to uninstall a keyspace during |
|
124 software uninstallation</b> </p> <p>You uninstall a keyspace by uninstalling |
|
125 the application which it was embedded in. This has the effect of uninstalling |
|
126 all the software patches with which you upgraded the keyspace. If there is |
|
127 a version of the keyspace in ROM, placed there at device creation, it comes |
|
128 back into use. If the keyspace was installed subsequently then no version |
|
129 of it remains after uninstallation. It is not possible to remove individual |
|
130 upgrades, only the entire set of upgrades which have ever been applied. </p> <p><b>Effects |
|
131 of upgrading a keyspace during software installation</b> </p> <p>An upgrade |
|
132 to a keyspace may conflict with user modifications to the keyspace. In that |
|
133 case the existing settings are merged with those in the upgrading keyspace |
|
134 in accordance with the following rules. The keyspaces are merged in accordance |
|
135 with the principle that user modifications override upgrade modifications. </p> <ul> |
|
136 <li id="GUID-D0E7853C-D91D-53C4-9DA8-C581A9AB5A79"><p>If a setting exists |
|
137 in the existing keyspace on the phone and the upgrading keyspace and the existing |
|
138 setting has not been modified by the user, the upgrading setting replaces |
|
139 the existing setting. </p> </li> |
|
140 <li id="GUID-C94441FB-0967-53D5-9EAE-750BDABE48E2"><p>If a setting exists |
|
141 in the existing keyspace and the upgrading keyspace and the existing setting |
|
142 has been modified by the user, the existing setting is preserved. </p> </li> |
|
143 <li id="GUID-DEEF31A4-5CF6-540A-A81A-E43DF2026C77"><p>If a setting exists |
|
144 in the existing keyspace but not in the upgrading keyspace, the existing setting |
|
145 is preserved. </p> </li> |
|
146 <li id="GUID-1270CCEC-7836-51BA-99EA-9BD46CA4BBCA"><p>If a setting exists |
|
147 in the upgrading keyspace but not in the existing keyspace, the upgrading |
|
148 setting is created. </p> </li> |
|
149 </ul> <p>Upgrades preserve the existing platform security policies. Metadata |
|
150 values assigned by default or to a range remain unchanged, but metadata values |
|
151 of individual keys take their upgrade settings. </p> <p>The first time you |
|
152 upgrade a keyspace which is provided in ROM you only need to list the keys |
|
153 which are being added to or changed from the ROM keyspace. However, if you |
|
154 are performing an upgrade to a keyspace which has previously been upgraded, |
|
155 you must include all the changes in all the previous upgrades: this is also |
|
156 the case where the keyspace was originally installed as an upgrade to a stub |
|
157 .sis file. </p> <p>If there are notification requests on any of the keys, |
|
158 the requests will complete as a result of installation, upgrading and uninstallation. |
|
159 If transactions are pending during an upgrade or uninstallation, those transactions |
|
160 will fail. It is advisable to close all sessions on a keyspace before uninstalling. </p> </section> |
|
161 <section id="GUID-D3331692-F84F-4421-8314-E46FA17F02A4"><title>Firmware updates</title> <p>Symbian provides limited support |
|
162 for firmware updates to ROM over a serial connection or by FOTA (firmware |
|
163 over the air). The generic term for these firmware updates is FOTx. When this |
|
164 happens, the Central Repository detects the upgrade when the device is next |
|
165 restarted and makes corresponding updates to its keyspaces. A firmware update |
|
166 reboots the device: as part of this process the Central Repository gets the |
|
167 current ROM version using <codeph>SysUtil::GetSWVersion</codeph> and compares |
|
168 it with a previously saved version. Where the Central Repository detects a |
|
169 difference it merges the relevant keyspaces at the level of the file or of |
|
170 individual settings. </p> <p>The rule is that user values (settings modified |
|
171 by the user) override SWI values (settings modified by a software upgrade |
|
172 or installation) and that SWI values override ROM values. </p> <p>There are |
|
173 two cases where a difference is resolved at the level of the file. </p> <ul> |
|
174 <li id="GUID-8B050D35-F362-5B75-A779-DC162C3DFF79"><p>Where a keyspace is |
|
175 non-persisted (ROM was never overridden), the ROM update replaces the current |
|
176 ROM. </p> </li> |
|
177 <li id="GUID-5388506C-9908-518E-A3B4-63E609E0BB55"><p>Where the ROM update |
|
178 deletes an existing ROM file, any persisted keyspaces are removed along with |
|
179 the deleted file. This rule also applies when the user has modified the keyspace |
|
180 in existing ROM, but not when the software installer has modified the keyspace |
|
181 in existing ROM. </p> </li> |
|
182 </ul> <p>Where the ROM update conflicts with user-modified keyspaces or SWI-modified |
|
183 keyspaces, the new ROM is merged with the persisted file at the level of the |
|
184 setting. The rules for resolving conflicts involve creation, modification |
|
185 and deletion of settings and they vary according to the point at which a setting |
|
186 was created. </p> <ul> |
|
187 <li id="GUID-D50380BB-2DBC-5320-8221-54DCE3A3C235"><p>If a setting is created |
|
188 by the firmware update it is simply added to the keyspace. </p> </li> |
|
189 <li id="GUID-AE312886-DDB5-5B9F-9D73-97741AD8324D"><p>If a setting was created |
|
190 by the software installer, an attempted modification by FOTx is not applied. |
|
191 A FOTx update will have no impact on any settings created by the software |
|
192 installer that are not in ROM. </p> </li> |
|
193 <li id="GUID-91A7F55A-60BD-5267-97F1-BD88F241C2FC"><p>If a setting was created |
|
194 by the device user, an attempted modification by FOTx is not applied. A FOTx |
|
195 update will have no impact on any settings created by the user that are not |
|
196 in ROM. </p> </li> |
|
197 <li id="GUID-ADF63BBA-0F4C-558A-9CC2-8A330F4A3C4A"><p>If a setting was present |
|
198 in existing ROM, these rules apply: </p> <ul> |
|
199 <li id="GUID-D4FA6716-FEC9-5A84-9C32-C429D6C105A0"><p>A modification by the |
|
200 user overrides a modification by FOTx. </p> </li> |
|
201 <li id="GUID-6CA71AAD-41F6-5CBA-8F2C-36FABA542A6E"><p>A modification by the |
|
202 user overrides a deletion by FOTx. </p> </li> |
|
203 <li id="GUID-7F619ECB-A5CE-5D42-B3AE-C261FD6222F1"><p>A deletion by the user |
|
204 is cancelled by a modification by FOTx. </p> </li> |
|
205 <li id="GUID-CE7F094E-4270-535D-8198-71C8D021A8C3"><p>A deletion by the user |
|
206 is confirmed by a deletion by FOTx. </p> </li> |
|
207 <li id="GUID-F49E35FF-22E1-5D53-ACE8-551B5B08C41D"><p>A modification by the |
|
208 software installer overrides a modifcation by FOTx. </p> </li> |
|
209 <li id="GUID-708220F5-90AD-56F5-B11C-CF178F3B56CB"><p>A modification by the |
|
210 software installer overrides a deletion by FOTx. </p> </li> |
|
211 <li id="GUID-12B84510-4DB5-530B-B21A-B17E7FEED881"><p>Deletions by the software |
|
212 installer do not occur. </p> </li> |
|
213 </ul> </li> |
|
214 <li id="GUID-75404D8E-11D5-53EE-963A-53C3E1E9A720"><p>Conflicts between user |
|
215 modified keyspaces and SWI modified keyspaces were covered in the previous |
|
216 section. </p> </li> |
|
217 </ul> </section> |
|
218 <section id="GUID-01DD59CD-E22D-43C5-8E62-2271F176C705"><title>Restore factory settings</title> <p>The Central Repository |
|
219 can restore factory settings across all keyspaces. Only device creators can |
|
220 restore factory settings by starting the Central Repository in a special mode |
|
221 during a reboot. The restore does not affect all settings in the keyspace, |
|
222 only those which have the appropriate metadata bit set. </p> <p>The effect |
|
223 of restoring factory settings is to revert settings to their value at the |
|
224 most recent software install or firmware update, to reverse changes made by |
|
225 the user. It does not return the device to the state in which it was created. |
|
226 To reverse the effects of software installation and firmware updates an uninstall |
|
227 is required. </p> <ul> |
|
228 <li id="GUID-95098D31-07C2-508A-A5C0-F2A9E9191306"><p>If a setting was created |
|
229 by the user, a restore factory settings operation deletes the setting. </p> </li> |
|
230 <li id="GUID-771F205B-218A-50E2-A18B-F4FCE751905E"><p>If a setting was created |
|
231 by SWI, a restore factory settings operation reverts the setting to the value |
|
232 it last had after any modifications by SWI or FOTx. </p> </li> |
|
233 <li id="GUID-E325ABDC-1286-5763-8C01-6D99662C20B6"><p>If a setting was created |
|
234 in existing ROM and modified by the user only, the setting reverts to its |
|
235 original value. </p> </li> |
|
236 <li id="GUID-4DAA44F5-218D-52A1-BE53-688B3FF4540F"><p>If a setting was created |
|
237 in existing ROM and deleted by the user, the setting reverts to the value |
|
238 it last had after any modifications by SWI or FOTx. </p> </li> |
|
239 <li id="GUID-09EA88F1-2A32-5207-B6FE-FF9E0B3C9F85"><p>If a setting was created |
|
240 in existing ROM and modified or deleted by SWI or firmware upgrade, the changes |
|
241 are not reversed. </p> </li> |
|
242 </ul> </section> |
|
243 <section id="GUID-D02F0D21-6081-4C5C-B9E1-63DE65C7DF82"><title>Backup and restore</title> <p>The Central Repository can back |
|
244 up data in a repository. Backup does not affect all repository entries, only |
|
245 those which have the appropriate metadata bit set. </p> <p>The effect of a |
|
246 restore is to merge the backed up values of backed up settings with the current |
|
247 values of non-backed up settings. It does not mean restoring the device state |
|
248 at the time of backup. </p> <ul> |
|
249 <li id="GUID-11F0ED5C-0C50-55F3-886D-E65042DAAE63"><p>A backed up setting |
|
250 is restored to its value at the time of backup. </p> </li> |
|
251 <li id="GUID-F1383EFE-D685-5923-AF99-1181E34860BB"><p>A non-backed up setting |
|
252 retains its current value. </p> </li> |
|
253 <li id="GUID-943725DE-9598-5ADF-B3B3-36DA8EE6FA26"><p>A backed up setting |
|
254 is restored after a deletion, but only if the backup took place before the |
|
255 deletion. </p> </li> |
|
256 <li id="GUID-3ECAB92B-B9B3-5F01-801F-5FEA81A632CD"><p>A non-backed up setting |
|
257 is never restored after a deletion. </p> </li> |
|
258 </ul> </section> |
|
259 </conbody><related-links> |
|
260 <link href="GUID-1C683226-C142-5C7B-BD20-060058352B08.dita"><linktext>Central Repository |
|
261 Guide</linktext></link> |
|
262 <link href="GUID-724BA3CD-7648-51DF-9285-3AA7470987F4.dita"><linktext>Optimising |
|
263 Repository Access</linktext></link> |
|
264 <link href="GUID-E87018CD-01B4-5886-87FC-CD25EE90587D.dita"><linktext>Central Repository |
|
265 Transactions</linktext></link> |
|
266 </related-links></concept> |