<?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-7FD72D9F-D65E-5248-A296-F2196F1DF5CF" xml:lang="en"><title> Upgrade

Types</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>The PKG file supporting upgrades must contain package-header section with

definitions for different types of upgrades. For details see, <xref href="GUID-D9D20EE0-AC86-512A-91C0-EA0ACF3912A7.dita">Package-Header</xref>. </p>

<p>The following table lists the different types of upgrades possible: </p>

<table id="GUID-F082562E-66EA-58F7-A77A-ED512E9E7FA7">

<tgroup cols="6"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/><colspec colname="col3"/><colspec colname="col4"/><colspec colname="col5"/>

<tbody>

<row>

<entry><p> <b>Type</b>  </p> </entry>

<entry><p> <b>Package UID</b>  </p> </entry>

<entry><p> <b>Package name</b>  </p> </entry>

<entry><p> <b>Version</b>  </p> </entry>

<entry><p> <b>Global vendor name</b>  </p> </entry>

<entry><p> <b>Notes</b>  </p> </entry>

</row>

<row>

<entry><p> <codeph>SA</codeph>  </p> </entry>

<entry><p>Same </p> </entry>

<entry><p>Same </p> </entry>

<entry><p>Higher (not mandatory) </p> </entry>

<entry><p>Same </p> </entry>

<entry><p>Can overwrite (replace) files </p> </entry>

</row>

<row>

<entry><p> <codeph>SP</codeph>  </p> </entry>

<entry><p>Same </p> </entry>

<entry><p>Different </p> </entry>

<entry><p>Not required </p> </entry>

<entry><p>Not required </p> </entry>

<entry><p>Cannot overwrite (replace) files </p> </entry>

</row>

<row>

<entry><p> <codeph>PU</codeph>  </p> </entry>

<entry><p>Same </p> </entry>

<entry><p>Need not match </p> </entry>

<entry><p>Higher (not mandatory) </p> </entry>

<entry><p>Not required </p> </entry>

<entry><p>Can overwrite (replace) files </p> </entry>

</row>

</tbody>

</tgroup>

</table>

<section><title>SA - Full Upgrade</title> <p>The full upgrade is specified

using the <codeph>SA</codeph> tag in the package-header. In full upgrade,

the original package is entirely replaced by the new one. The original files

that are not available in the new package are removed from the Symbian device.

After upgrade, the new package cannot be removed separately from the original.

To remove the upgrade, the entire package must be removed. </p> <p>If the

upgrade causes an executable to be <i>removed</i>, the corresponding private

directory is deleted. Any folders and files that are created by the application

outside its private directory are not removed. The application must remove

these files. </p> <p> <b>Important:</b> It is recommended that files created

by an application be located in the private directory of the application. </p> <p>If

the upgrade causes an executable to be <i>replaced</i>, the private directory

is not removed. </p> <p> <b>Notes</b>: </p> <ul>

<li id="GUID-E726EE1F-F977-5DDA-9AFD-E0AEEC789D6D"><p>An upgrading package

of type <codeph>SA</codeph> cannot overwrite files installed by a patch. For

upgrading such packages, the patch must be uninstalled first. </p> </li>

<li id="GUID-18DB72B9-55EC-581C-B705-343720F62B34"><p>To be identified as

an upgrade, the upgrading package file must have the same package UID as the

original. If the package UID differs, it is considered to be an unrelated

package and not an upgrade. </p> </li>

<li id="GUID-76D8A7B8-3DD2-5D14-835A-031C2B1EE0C8"><p>If a patch upgrades

an <codeph>SA</codeph> package, the patch is not uninstalled by new <codeph>SA</codeph> upgrade. </p> </li>

<li id="GUID-EEEE413A-522E-52D2-9B8B-BA5933DD0000"><p>The <codeph>RR</codeph> and <codeph>RB</codeph> executables

in the base package are run during the upgrade. See, <xref href="GUID-B3BE018B-0EC5-5866-9BD7-50CBF5670324.dita#GUID-B3BE018B-0EC5-5866-9BD7-50CBF5670324/GUID-B913501B-A5AB-5ADB-96FF-8060DD45A87E">run-options</xref> for details. </p> </li>

</ul> </section>

<section><title>SP - Patch Upgrade</title> <p>The patch upgrade is specified

using the <codeph>SP</codeph> tag in the package-header. This is an augmentation

to an existing package (<i>base package</i>). A typical example for this requirement

is to provide additional levels of a game. A patch upgrade cannot overwrite

files in RAM, however, it can eclipse files in ROM. A patch can be uninstalled

separately from the base package. The installation fails if a patch modifies

or replaces an existing file in the base package. </p> <p>A patch can only

add files to a base package and cannot overwrite files. This is the only difference

between patch upgrade and partial upgrade. </p> <p> <b>Notes</b>: </p> <ul>

<li id="GUID-BDE060BA-2846-5E05-93BD-CEE9136651A7"><p>If two patches with

same package name and UID are installed, the second patch is treated as an

upgrade of the first patch. The second patch replaces the first patch entirely. </p> </li>

<li id="GUID-92611923-8DEB-5E45-89D5-9712C1C26CD4"><p>An OS component does

not need a Stub SIS file to be patched. However, if the requirement is to

patch files in the private directory of the component, a stub SIS file is

required which specifies the relevant executables (<filepath>.exe</filepath>). </p> <p> <b>Important</b>:

If the patch installs files to more than one private directory, all relevant

EXEs must be specified in the Stub file. </p> <p>If a Stub SIS file is required,

the patch must have the same package UID and non-localized vendor name as

the package it is upgrading. The package name must be different to distinguish

the patch from the existing component. </p> </li>

<li id="GUID-ED91317F-65E8-5E52-AFE4-5D5A94126AA1"><p>A patch can install

files to the import directory of the component (<filepath>\private\</filepath> <i>&lt;SID&gt;</i> <filepath>\import\</filepath>)

without the requirement of a Stub SIS file. However, the import directory

must already exist. The software installer does not create it. </p> <p>The

purpose of the import directory is to enable other packages to install files

to it. </p> </li>

</ul> </section>

<section><title>PU - Partial Upgrade</title> <p>The partial upgrade is specified

using the <codeph>PU</codeph> tag in the package-header. This upgrade is a

variation of <codeph>SA</codeph> in that any files present in the base package

that are missing in the new package are not removed. A partial upgrade can

only add or overwrite files. This allows an upgrading SIS file to replace

just the parts of a base package which requires replacement. </p> <p> <b>Notes</b>: </p> <ul>

<li id="GUID-3EAFFA91-9929-5E94-825C-6CF648886A77"><p>When creating a <codeph>PU</codeph> package,

the drive selection dialog must be suppressed, so that the upgrade is installed

on the same drive as the existing package and not to the drive selected by

the Symbian device user. </p> </li>

<li id="GUID-349A16C1-3876-5B90-AD15-56027407EA08"><p>Unlike packages installed

using the <codeph>SA</codeph> or <codeph>SP</codeph> options, a partial upgrade

package is not listed as a removable component after installation, so the

base package must be removed and reinstalled to remove the changes. </p> </li>

<li id="GUID-3E6FDB35-55D5-5BD7-9E0E-C60F5D6B7476"><p>A partial upgrade cannot

overwrite files installed by a patch. </p> </li>

<li id="GUID-B335BF5B-B45C-558F-BDEE-09C2676AC133"><p>The <codeph>RR</codeph> and <codeph>RB</codeph> executables

in the base package are run during the upgrade. See, <xref href="GUID-B3BE018B-0EC5-5866-9BD7-50CBF5670324.dita#GUID-B3BE018B-0EC5-5866-9BD7-50CBF5670324/GUID-B913501B-A5AB-5ADB-96FF-8060DD45A87E">run-options</xref> for details. </p> </li>

<li id="GUID-CCCCE6F7-EA61-5617-A692-D57EB856C133"><p>It is not mandatory

to specify the RU option for upgrading applications on the ROM. </p> </li>

</ul> </section>

</conbody><related-links>

<link href="GUID-D9D20EE0-AC86-512A-91C0-EA0ACF3912A7.dita"><linktext>Package-Header</linktext>

</link>

<link href="GUID-7F65B69A-6AC1-509C-91E8-9E49ED0BFEC0.dita"><linktext>Upgrading

OS Components</linktext></link>

</related-links></concept>