<?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 reference
  PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
<reference id="GUID-B3BE018B-0EC5-5866-9BD7-50CBF5670324" xml:lang="en"><title>Language-Neutral
Files</title><abstract><p>Language-Neutral files are files that are required to be installed
irrespective of the languages supported on the Symbian device.</p><p>This
Language-Neutral files section specifies the location and name of each file
on the PC and its target location on the Symbian device. Files are installed
in the order in which they are specified in the PKG file. </p></abstract><prolog><metadata><keywords/></metadata></prolog><refbody>
<refsyn id="GUID-744D2F39-8483-44C0-B335-03882385063E"><title>Syntax</title> <codeblock id="GUID-8B696DC5-3F23-5AD6-AECC-651887995037" xml:space="preserve">"source-filename" - "destination-filename"[, install-options]</codeblock> <p>where </p> <table id="GUID-B9A07521-29B4-5F5C-925F-B261E52FB1D6">
<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
<tbody>
<row>
<entry><p> <b>Argument</b>  </p> </entry>
<entry><p> <b>Description</b>  </p> </entry>
</row>
<row>
<entry><p>source-filename </p> </entry>
<entry><p>Specifies the name and location of the file on computer that must
be included in the SIS file. </p> </entry>
</row>
<row>
<entry><p>destination-filename </p> </entry>
<entry><p>Specifies the location on the Symbian device, to which the file
must be installed. See, <xref href="GUID-B3BE018B-0EC5-5866-9BD7-50CBF5670324.dita#GUID-B3BE018B-0EC5-5866-9BD7-50CBF5670324/GUID-1584AED6-8583-51FC-AF7A-24C135DDC5AA">destination-filename</xref> for more information. </p> </entry>
</row>
<row>
<entry><p>install-options </p> </entry>
<entry><p>Specifies the type of file and how it affects the installation or
removal. It is an optional comma-separated list. See, <xref href="GUID-B3BE018B-0EC5-5866-9BD7-50CBF5670324.dita#GUID-B3BE018B-0EC5-5866-9BD7-50CBF5670324/GUID-E2911CFD-7B9D-55B7-86D1-4DA68870944D">install-options</xref>, for more information. </p> </entry>
</row>
</tbody>
</tgroup>
</table> <p id="GUID-1584AED6-8583-51FC-AF7A-24C135DDC5AA"><b>destination-filename</b> </p> <p>The <codeph>destination-filename</codeph> must
specify the full path. A <codeph>!</codeph> character can be used instead
of a drive letter to enable the Symbian device user to install the file to
any required location. As an alternative to <codeph>!</codeph>, the <codeph>$</codeph> character
can be used to denote the system drive. </p> <p>The <codeph>destination-filename</codeph> must
not be specified if the file is not required to be installed. For example,
a text file containing a licence agreement to be displayed during the installation
must not include destination-filename and can be specified with empty quotes. </p> <p>If
a file can be installed by other packages, for example, a shared DLL, it is
recommended to install it using an embedded SIS file. </p> <p>The <codeph>destination-filename</codeph> can
be specified in one of the following formats: </p> <codeblock id="GUID-D15405BA-B72F-5985-8713-966A33F4B257" xml:space="preserve">"drive:path"</codeblock> <codeblock id="GUID-96AF5EF7-B7BA-5B98-83E8-55D49A4C36AF" xml:space="preserve">"!:path"</codeblock> <codeblock id="GUID-50AA0C70-D535-5436-8732-875D24196EA0" xml:space="preserve">""</codeblock> <p id="GUID-E2911CFD-7B9D-55B7-86D1-4DA68870944D"><b> install-options</b> </p> <p>The
following table provides a list of the <codeph>install-options</codeph>. </p> <table id="GUID-947C0669-A1F7-52F7-985F-3F75FFBB17C4">
<tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/>
<thead>
<row>
<entry>Name</entry>
<entry>Abbreviation</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><p> <codeph>FILE</codeph>  </p> </entry>
<entry><p> <codeph>FF</codeph>  </p> </entry>
<entry><p>Specifies a standard installable file. For example: </p> <codeblock id="GUID-923A445F-87A5-5D0C-8B28-A6656D7D8830" xml:space="preserve">"text\file1.txt"-"!:\private\E800005A\file1.txt", FF</codeblock> </entry>
</row>
<row>
<entry><p> <codeph>FILETEXT</codeph>  </p> <p> <codeph>[,text-options]</codeph>  </p> </entry>
<entry><p> <codeph>FT</codeph>  </p> <p> <codeph>[,text-options]</codeph>  </p> </entry>
<entry><p>A text file that is displayed in a dialog box during installation.
The dialog type is determined by the <codeph>text-options</codeph> specified.
See, <xref href="GUID-B3BE018B-0EC5-5866-9BD7-50CBF5670324.dita#GUID-B3BE018B-0EC5-5866-9BD7-50CBF5670324/GUID-E6210579-BFAB-505B-A99F-99175FA0F572">text-options</xref> for
more information. </p> <p>Text files are not installed on the target device,
so the target location is empty. An example <codeph>FILETEXT</codeph> line
is: </p> <codeblock id="GUID-D0728FED-F1A1-5574-BC3B-A24B8A881760" xml:space="preserve">"text\textfilec.txt"-"", FT, TC</codeblock> <p>Any <codeph>FILETEXT</codeph> statements
present in a PKG file for a preinstalled application are ignored by the software
installer. </p> </entry>
</row>
<row>
<entry><p> <codeph>FILERUN</codeph>  </p> <p> <codeph>[,run-options][,RUNWAITEND]</codeph>  </p> </entry>
<entry><p> <codeph>FR</codeph>  </p> <p> <codeph>[,run-options][,RW]</codeph>  </p> </entry>
<entry><p>Specifies a file that is installed on the Symbian device and run
during installation or uninstallation of packages based on the <codeph>RI</codeph>, <codeph>RR</codeph> and <codeph>RB</codeph> arguments.
For details, 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>. </p> <p>For
example: </p> <codeblock id="GUID-D985FEB8-4E60-5897-AFE0-89D723EA9350" xml:space="preserve">"\epoc32\release\armv5\urel\zoom.exe"-"!:\sys\bin\zoom.exe", FILERUN, RUNINSTALL</codeblock> <p> <b>Notes</b>: </p> <ul>
<li id="GUID-62883591-AE70-5ABA-B86B-232084BCACF1"><p>The file can be an executable
or a document containing text. </p> </li>
<li id="GUID-84B90271-D1A2-578B-AC19-52B04DC9284C"><p>The untrusted applications
are run through the <codeph>FILERUN</codeph> (<codeph/><codeph>FR</codeph>)
or <codeph>FILEMIME</codeph> (<codeph>FM</codeph>) statements based on configuration
of the installation policy. </p> </li>
</ul> </entry>
</row>
<row>
<entry><p> <codeph>FILEMIME,</codeph>  </p> <p> <codeph>mime-type</codeph>  </p> <p> <codeph>,run-options</codeph>  </p> <p> <codeph>[,RUNWAITEND]</codeph>  </p> </entry>
<entry><p> <codeph>FM,</codeph>  </p> <p> <codeph>mime-type</codeph>  </p> <p> <codeph>,run-options
[,RW]</codeph>  </p> </entry>
<entry><p>Instructs the installer to associate the file with the default application
associated with the given MIME type, for example, <codeph>text or        
             x-vCard</codeph> is required to be open for contact details. </p> <p>The
MIME type in quotes must be specified after the <codeph>FM</codeph> argument. <codeph>FILEMIME</codeph> is
intended for use with files that are launched during the installation or uninstallation
and not for standard installation files. For example: </p> <codeblock id="GUID-94D600A6-C80A-5EBB-8240-D481CD24E27B" xml:space="preserve">"my_picture.gif"-"", FM, "image/gif", RI</codeblock> <p>The Software Installer ignores any <codeph>FILEMIME</codeph> statements
present in a PKG file for a preinstalled application. </p> </entry>
</row>
</tbody>
</tgroup>
</table> <p id="GUID-E6210579-BFAB-505B-A99F-99175FA0F572"><b>text-options</b> </p> <p> <codeph>text-options</codeph> can
be used after <codeph>FT</codeph> is specified. It is used by the UI to determine
the type of dialog that is used to display the text. It can have one of the
following values. </p> <table id="GUID-2DDEC392-244A-505C-B102-EBE19D8A3CC3">
<tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/>
<thead>
<row>
<entry>Name</entry>
<entry>Abbreviation</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><p> <codeph>TEXTCONTINUE</codeph>  </p> </entry>
<entry><p> <codeph>TC</codeph>  </p> </entry>
<entry><p>It is recommended that the UI displays a dialog containing a <codeph>Continue</codeph> button. </p> <p>The
installation continues regardless of the return value of the dialog. </p> </entry>
</row>
<row>
<entry><p> <codeph>TEXTABORT</codeph>  </p> </entry>
<entry><p> <codeph>TA</codeph>  </p> </entry>
<entry><p>It is recommended that the UI displays a dialog containing <codeph>Yes</codeph> /<codeph>No</codeph> buttons. </p> <p>The
software installer continues with the installation if the dialog returns true
(if the Symbian device user selects <codeph>Yes</codeph>). It aborts the installation
if the dialog returns false (if the Symbian device user selects <codeph>No</codeph>). </p> </entry>
</row>
<row>
<entry><p> <codeph>TEXTEXIT</codeph>  </p> </entry>
<entry><p> <codeph>TE</codeph>  </p> </entry>
<entry><p>Same as <codeph>TEXTABORT</codeph>. </p> </entry>
</row>
<row>
<entry><p> <codeph>FORCEABORT</codeph>  </p> </entry>
<entry><p> <codeph> FA </codeph>  </p> </entry>
<entry><p>It is recommended that the UI displays a dialog containing a <codeph>ForceAbort</codeph> button. </p> <p>On
selecting this dialog, it aborts the installation. </p> </entry>
</row>
<row>
<entry><p><codeph>TEXTSKIP</codeph></p></entry>
<entry><p><codeph>TS</codeph></p></entry>
<entry><p>It is recommended that the UI displays a dialog containing <codeph>Yes</codeph> /<codeph>No</codeph> buttons. </p><p>The
software installer continues the installation without skipping
the file mentioned in the next statement if the dialog returns true (if the
Symbian device user selects <codeph>Yes</codeph>). It skips the installation
of the file mentioned in the next statement if the dialog returns false (if
the Symbian device user selects <codeph>No</codeph>).</p></entry>
</row>
</tbody>
</tgroup>
</table> <p> <b>Note</b>: UIs can implement installation dialogs differently,
so you must refer to the UI SDK for details about the actual behaviour. </p> <p id="GUID-B913501B-A5AB-5ADB-96FF-8060DD45A87E"><b>run-options</b> </p> <p> <codeph> run-options</codeph> can
be used after <codeph>FR</codeph> or <codeph>FM</codeph> has been specified.
It can be any of the following: </p> <table id="GUID-7B193CA1-4057-5680-93E3-9DC931924D3B">
<tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/>
<thead>
<row>
<entry>Name</entry>
<entry>Abbreviation</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><p> <codeph>RUNINSTALL</codeph>  </p> </entry>
<entry><p> <codeph>RI</codeph>  </p> </entry>
<entry><p>Run on install </p> </entry>
</row>
<row>
<entry><p> <codeph>RUNREMOVE</codeph>  </p> </entry>
<entry><p> <codeph>RR</codeph>  </p> </entry>
<entry><p>Run on uninstall and upgrade </p> </entry>
</row>
<row>
<entry><p> <codeph>RUNBOTH</codeph>  </p> </entry>
<entry><p> <codeph>RB</codeph>  </p> </entry>
<entry><p>Run on install, uninstall and upgrade </p> </entry>
</row>
<row>
<entry><p> <codeph>RUNBEFORESHUTDOWN</codeph>  </p> </entry>
<entry><p> <codeph>RBS</codeph>  </p> </entry>
<entry><p>Run on uninstall before the applications in the package are shut
down </p> </entry>
</row>
</tbody>
</tgroup>
</table> <p>Optionally, <codeph>RW</codeph> (or <codeph>RUNWAITEND</codeph>)
can be specified in addition to the <codeph>run-options</codeph>. If this
option is specified, the installation server waits for the program to terminate
before continuing with the install. If this option is not specified, the installation
server runs the program and continues with the installation. The program is
shut down after the installation is complete. </p><p>When uninstalling a package
with a <codeph>RUNREMOVE</codeph> or <codeph>RUNBOTH</codeph> executable specified,
the installation server always waits for the executable to terminate or timeout
before continuing with the uninstall.</p> <p><b>Verification options</b> </p> <p>The
following option is available for checking the integrity of a file at restore
time: </p> <table id="GUID-78249B09-3D1C-5A89-AC4B-BA53DA2ACA4F">
<tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/>
<thead>
<row>
<entry>Name</entry>
<entry>Abbreviation</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><p> <codeph>VERIFY</codeph>  </p> </entry>
<entry><p> <codeph>VR</codeph>  </p> </entry>
<entry><p>This flag is necessary if the integrity of a file installed in a
directory outside <filepath>\sys</filepath> or <filepath>\restore</filepath> needs
to be verified at restore time. For example, an application can check this
flag to verify that a security policy file restored to its private directory
is identical to the file delivered by the SIS file. </p> <p>The following
example illustrates the usage of this option: </p> <codeblock id="GUID-1E310E2B-94BB-5877-91E6-14C5895BCF91" xml:space="preserve">"data\ups_01041000_01041001.rsc"-
"$:\private\10283558\policies\ups_01041000_01041001.rsc", VERIFY</codeblock> </entry>
</row>
</tbody>
</tgroup>
</table> <p id="GUID-90E6B97B-3A6A-5D88-80D1-B66248C82543"><b>Import and Private
Directories</b> </p> <p>The software installer ensures that files are placed
in appropriate areas of the file system. The following rules are applied: </p> <ul>
<li id="GUID-F92635A7-7B97-5CA8-8C2C-E2E52CBB279C"><p>A package can only deliver
a data file into the private directory belonging to any executable in the
package. If a package delivers three executables: <codeph>SID1</codeph>, <codeph>SID2</codeph>, <codeph>SID3</codeph> (where
SID stands for Secure ID), then data files can be delivered to <filepath>/private/SID1/</filepath>, <filepath>/private/SID2/</filepath>,
or <filepath>/private/SID3/</filepath>. In an upgrade, this is possible by
associating the upgrade package with the SIDs present in the original package
unless one of the original executables is to be removed during the upgrade. </p> </li>
<li id="GUID-AB6861A6-C1DB-5F82-B621-798D8C131417"><p>Any package can deliver
a file into the <filepath>//private/SID/import</filepath> of an entirely unrelated
package. However, replacement and eclipsing rules apply. </p> </li>
</ul> </refsyn>
</refbody></reference>