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

  PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">

<task xml:lang="en" id="GUID-93F53961-9DA3-5D01-A881-D28E0EBF8B3C"><title>Upgrading ROM Plug-ins</title><shortdesc>Phone manufacturers sometimes require to provide installable upgrades to the existing ROM plug-ins delivered with the phone. The requirement arises to fix defects or add a new functionality. </shortdesc><prolog><metadata><keywords/></metadata></prolog><taskbody><context id="GUID-5DD9A8CE-B14D-5681-A6EA-39D4B2303CE0"><p>The plug-in framework identifies and uses the plug-in upgrades in the following scenarios: </p> <ul><li id="GUID-C70CF089-B48C-5CB8-BCD7-26D77B475383"><p>Client code uses the ROM-only plug-in resolver, as described in <xref href="GUID-08007041-CE18-5B1C-9AE6-042EBBFD1AB6.dita">Using the ROM-only resolver</xref>. </p> </li> <li id="GUID-5091E3A2-2382-5341-BAFF-E55C25714F0B"><p>The plug-in upgrade location is specified at ROM build time using the <filepath>SPI</filepath> (Static Plug-in Information) file. </p> </li> </ul> <p>For the upgrades to be successful, the existing ROM plug-in and the upgrade must meet certain conditions. When an upgrade is created, ensure the existing ROM plug-in and the upgrade meet the following requirements: </p> <ul><li id="GUID-50F1022F-D4D1-538A-B08A-3EEB74294555"><p>The name of the plug-in DLL and resource file of the upgrade must be the same as the existing ROM plug-in. </p> </li> <li id="GUID-802B0E54-6780-523F-8396-87689DB2FDAB"><p>The interface UID and implementation UID for the upgrade and the existing ROM plug-in must be the same. </p> </li> <li id="GUID-976DEBF1-D3DB-552D-8474-A818E729AA49"><p>The plug-in DLL's Vendor ID must be the same in the upgrade and the existing ROM plug-in. </p> </li> <li id="GUID-9372F89E-8A1F-59AC-8AE2-807CA94EF4D2"><p>The value of <codeph>version_no</codeph> member of <codeph>IMPLEMENTATION_INFO</codeph> must be higher for the upgrade than the existing ROM plug-in. For more details, see <xref href="GUID-9A9103E4-27B0-5CF3-855A-DCD44795A5C0.dita">Creating a Standard Registration Resource File</xref>. </p> </li> <li id="GUID-633E76F8-22F0-5852-BBCF-D8A20D1639BB"><p>The value of <codeph>VERSION</codeph> variable in the project file for the upgrade must be higher than the value for the <codeph>VERSION</codeph> variable in the project file (.mmp file) of the ROM plug-in. </p> <p>The <codeph>VERSION</codeph> variable normally has the default value of 10.0 and is not explicitly set. But for the upgrade it has to be set to a value higher than the ROM plug-in. For more details, see <xref href="GUID-B3BE018B-0EC5-5866-9BD7-50CBF5670324.dita">Language-Neutral Files </xref>. </p> </li> </ul> <p>If the values for plug-in DLL name ,interface UID and implementation UID differ, the plug-in framework treats the upgrade plug-in as a new implementation. </p> </context> <steps id="GUID-042C8B5D-5798-5CA2-992C-2C2E18B483AA"><step id="GUID-AE5911E0-6020-5DB5-A2B8-A5210E72C5DA"><cmd/><info>Provide a SIS stub package for the plug-in DLL of the upgrade on the same drive as the existing ROM plug-in. </info> <info>This step is a part of the general procedure that allows ROM-based files to be upgraded. </info> <info>The SIS file provides information that is utilized by the Software Installer program to identify the upgrade as a valid replacement for the original ROM plug-in. For more details, refer <xref href="GUID-B3BE018B-0EC5-5866-9BD7-50CBF5670324.dita">Language-Neutral Files </xref>. </info> </step> <step id="GUID-0D73CF5E-C668-54E1-BAF2-72BCEF5AF9CD"><cmd/><info>Set the <codeph>rom_only</codeph> member of <codeph>IMPLEMENTATION_INFO</codeph> to 0 in the registration resource file of the plug-in. </info> <info>  NOTE: If <codeph>rom_only</codeph> member is set to 1, upgrades are ignored. </info> <info>For more details, refer <xref href="GUID-08007041-CE18-5B1C-9AE6-042EBBFD1AB6.dita">Preventing a ROM-based implementation from being overridden</xref>. </info> </step> </steps> </taskbody></task>