<?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>