<?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><p>For Unicode text files to be displayed correctly, it is

recommended that the Byte Order Mark (BOM) be specified at the

beginning of the text files.</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>