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