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