<?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-D8302B04-D850-5FA7-A1AD-F5C40CF6A1EF" xml:lang="en"><title>Porting

Data-caged Applications</title><shortdesc>This document describes the changes required to migrate exe-apps

to a data caged directory structure. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<section><title>Introduction</title> <p>In Symbian OS v8.0 and earlier, application

specific information (for instance captions and icons) was provided by a combination

of the AIF (Application Information File) and the caption file. Both of these

files were optional. </p> <p>Migrated applications must provide a registration

file, and may optionally provide localizable application information resource

files and icon files. Localizable application information resource files provide

localizable application information (for instance captions and icons), whereas

an application's localizable UI resource file provides UI resources such as

menus and dialogs. </p> <p>The localizable information that was previously

provided by a combination of AIF and caption files, has been split into two

categories: </p> <p>The diagram below shows the new file structure used to

provide application information. </p> <fig id="GUID-7C0D7121-43A4-5C29-86E6-A92F753D29A4">

</fig> <ul>

<li id="GUID-0D14076A-26FE-5E6A-BF57-69B169287BF1"><p>A registration file

which 'points' to one of three localizable resource files provided. If the

current language is <filepath>01</filepath> or <filepath>02</filepath>, the

system will load the corresponding version of <filepath>AppName_loc</filepath>,

otherwise <filepath>AppName_loc.rsc</filepath> will be loaded. </p> </li>

<li id="GUID-AF8CD591-A112-5AF3-92CD-97ADD83C277C"><p> <filepath>AppName_loc.r01</filepath> and <filepath>AppName_loc.r02</filepath> share

the same icon file. </p> </li>

</ul> <p>Migrated applications may be used with or without data caging enforced. </p> </section>

<section><title>Procedure</title> <p>The following sections detail the mandatory

and optional steps required to migrate an application. </p> <p> <b>Mandatory

steps</b>  </p> <ol id="GUID-8CCDDC52-4EB1-567A-A9F5-A480E9912B66">

<li id="GUID-27A355EC-835B-59AC-8B40-B855BCB1BD34"><p>Provide a registration

file. </p> <p>A registration file is a standard Symbian platform compiled

resource file (<filepath>.rsc</filepath>). The <filepath>.rss</filepath> file

used to build the registration file should be named <codeph>AppName_reg.rss</codeph> and

contain at least the following lines: </p> <codeblock id="GUID-192653ED-EF93-566D-907F-46462D825B96" xml:space="preserve">#include &lt;appinfo.rh&gt; 

UID2 KUidAppRegistrationResourceFile 

UID3 0x01000000 // application UID 

RESOURCE APP_REGISTRATION_INFO

    {

    app_file="AppName"; // filename of application binary (minus extension)

    }</codeblock> <p>To build the registration file, add the following lines

to the application's MMP file: </p> <codeblock id="GUID-2C8C8693-E881-578B-91CB-FDC17C357CDA" xml:space="preserve">START RESOURCE    AppName_reg.rss 

TARGETPATH        \private\10003a3f\apps 

END</codeblock> <p>The <filepath>_reg</filepath> filename suffix is used as

a naming convention only and is not mandatory. </p> <p>Note that any lines

in the MMP file that are used to build an AIF file should be removed. </p> </li>

<li id="GUID-B5D1F806-91F1-5326-8026-D1E36C30889E"><p>Build the application

binary to a new location. </p> <p>The following line should replace the <codeph>TARGETPATH</codeph> line

associated with the <codeph>TARGET</codeph>, <codeph>TARGETTYPE</codeph> and <codeph>UID</codeph> lines: </p> <codeblock id="GUID-5BD260BF-9A9D-5998-83AE-667D9C3B1A96" xml:space="preserve">TARGETPATH        \sys\bin</codeblock> </li>

</ol> <p> <b>Optional steps</b>  </p> <ul>

<li id="GUID-967BFB2B-6862-5C79-A89F-F897F2036415"><p>A UI resource file whose

location is provided by <codeph>CEikApplication::ResourceFileName()</codeph>  </p> </li>

<li id="GUID-0B7D3B27-0D56-50E5-9EE0-9084FE138FD9"><p>An MBM file whose location

is provided by <codeph>CEikApplication::BitmapStoreName()</codeph>  </p> </li>

<li id="GUID-AF83E0ED-F59E-5BFC-9C58-1DED13A78645"><p>Application information

through an AIF and/or caption file. </p> </li>

</ul> <p>The following steps are only required if the application provides

one or more of the following: </p> <ol id="GUID-42AA9F22-B442-5972-985F-6F629C257093">

<li id="GUID-1706E3AD-7343-56EA-8E74-977E7F033E08"><p>Specify the default

UI resource file location. </p> <p>When building the application UI resource

file, the <codeph>TARGETPATH</codeph> must be specified as follows: </p> <codeblock id="GUID-9429B307-D5F6-5EEF-8FDD-FA2E962E1695" xml:space="preserve">TARGETPATH        \resource\apps</codeblock> </li>

<li id="GUID-A21B102D-7C2A-562A-80A5-464EE0F42C56"><p>Specify the default

MBM file location. </p> <p>When building the application's MBM file, the <codeph>TARGETPATH</codeph> must

be specified as follows: </p> <codeblock id="GUID-E7A8DD91-70AA-519E-91EB-493EFCF9302A" xml:space="preserve">TARGETPATH        \resource\apps</codeblock> </li>

<li id="GUID-1E07FA6D-F5E1-524D-AD7C-E6CAD3E8F5E5"><p>Specify the application

information by providing the following files: </p> <ul>

<li id="GUID-619E778D-E4E5-5755-B6F1-E02C047C4BEE"><p>Non-localizable information

(provided by the registration file) </p> <p>The registration file provides

non-localizable application information. For an example registration file

see <codeph>AppName_reg.rss</codeph> in the <xref href="GUID-D8302B04-D850-5FA7-A1AD-F5C40CF6A1EF.dita#GUID-D8302B04-D850-5FA7-A1AD-F5C40CF6A1EF/GUID-52802361-8A7A-5C8A-ACC1-F41E50CFD1CF">Example

files</xref> section. </p> </li>

<li id="GUID-38C4EF86-05A7-5D95-BB04-644DEC26C582"><p>Localizable information

(localizable resource file and icon file) </p> <p>Localizable application

information can either be provided in a separate resource file (see <codeph>AppName_loc.rss</codeph>),

or as a resource within the application UI resource file (see <codeph>AppName.rss</codeph> and <codeph>AppName2_reg.rss</codeph> in

the <xref href="GUID-D8302B04-D850-5FA7-A1AD-F5C40CF6A1EF.dita#GUID-D8302B04-D850-5FA7-A1AD-F5C40CF6A1EF/GUID-52802361-8A7A-5C8A-ACC1-F41E50CFD1CF">Example

files</xref> section). </p> <p>When providing the information as a resource

within the application UI resource file, the registration file's <codeph>APP_REGISTRATION_INFO</codeph> struct

must contain the following lines: </p> <codeblock id="GUID-EF9F185B-FBF7-52BA-B218-4B3DF2FC8A40" xml:space="preserve">localisable_resource_file="\\resource\\apps\\AppName";

localisable_resource_id = R_LAI;</codeblock> <p>where <codeph>R_LAI</codeph> is

a named <codeph>LOCALISABLE_APP_INFO</codeph> resource struct within the UI

resource file. </p> <p>The <codeph>localisable_resource_file</codeph> field

should not include a drive in the path, or a file-extension, but it should

provide a full directory path and a file name (without extension). </p> <p>To

build a resource file for language <filepath>01</filepath>, add the following

to the MMP file: </p> <codeblock id="GUID-8ECAB691-7720-5B7C-AD77-AF706AE621B8" xml:space="preserve">start resource    AppName_loc.rss

targetpath        \resource\apps 

lang              01 

end</codeblock> <p>The <filepath>_loc</filepath> filename suffix is used as

a naming convention only and is not mandatory. </p> <p>Icon files referenced

in the localizable resource should also be built to <filepath>\resource\apps\</filepath>. </p> </li>

</ul> </li>

</ol> </section>

<section id="GUID-3C64BE3F-859A-5E81-BCBD-C4BF717D4439"><title>Software install

package file requirements</title> <p>When creating a PKG file (software install

package file) for an application, the registration file must be installed

to the <filepath>\private\10003a3f\import\apps\</filepath> directory. </p> <p>The

application binary must be installed to <filepath>\sys\bin\</filepath> on

the same drive as the registration file. </p> <p>The localizable resource

files must be installed to <filepath>\resource\apps\</filepath> on the same

drive as the registration file. </p> </section>

<section id="GUID-BB2F1E46-47CE-51F8-9020-D0D1DD9E06CB"><title>Data caged

file locations</title> <p>To comply with the directory structure imposed by

data caging, many of the files associated with an application need to be relocated. </p> <p>Care

should be taken to ensure application code which overrides the following APIs

uses appropriate file locations: </p> <codeblock id="GUID-4CED50C3-3B76-5FCD-8F22-0B1D051E1A7A" xml:space="preserve">CEikApplication::ResourceFileName() 

CEikApplication::BitmapStoreName() 

CEikApplication::OpenIniFileLC( RFs&amp; aFs )</codeblock> <p>When specifying

the location of files on a target device, application IBY files should explicitly

specify <filepath>\sys\bin</filepath> as the destination location for application

binary files instead of using <codeph>SYSTEM_BINDIR</codeph>. </p> </section>

<section id="GUID-52802361-8A7A-5C8A-ACC1-F41E50CFD1CF"><title>Example files</title> <p id="GUID-CDA35D97-FF46-5A5F-A57B-F3E93B935E1C"><b>AppName_reg.rss</b> </p><codeblock id="GUID-AE62EB61-5776-55D8-9CA3-DB18EAC00CC7" xml:space="preserve">#include &lt;appinfo.rh&gt;

UID2 KUidAppRegistrationResourceFile 

UID3 0x01000000 // application UID

RESOURCE APP_REGISTRATION_INFO

    {

    app_file = "AppName";

    //

    localisable_resource_file = "\\resource\\apps\\AppName_loc";

    //

    hidden = KAppNotHidden;

    embeddability = KAppNotEmbeddable;

    newfile = KAppDoesNotSupportNewFile;

    launch = KAppLaunchInForeground;

    group_name = "AppNameGroup";

    //

    default_screen_number = 2;

    //

    datatype_list = 

        {

        DATATYPE { priority=EDataTypePriorityNormal; type="image/jpeg"; },

        DATATYPE { priority=EDataTypePriorityNormal; type="image/gif"; }

        };

    //

    file_ownership_list =

        {

        FILE_OWNERSHIP_INFO {file_name="z:\\temp\\AppNameTempFile.txt"; },

        FILE_OWNERSHIP_INFO {file_name="z:\\temp\\AppName.txt"; }

        };

    }</codeblock> <p id="GUID-7F026167-77F9-5AC2-A68F-049DEC624A4E"><b> AppName_loc.rss</b> </p><codeblock id="GUID-E2F5C25C-206E-510F-BF8C-6E8EBA41F1DD" xml:space="preserve">#include &lt;appinfo.rh&gt; 

#ifdef LANGUAGE_01 

#include "AppName01.rls" 

#else 

#include "AppNamesc.rls" 

#endif 

RESOURCE LOCALISABLE_APP_INFO

    {

    short_caption = STRING_r_short_caption;

    caption_and_icon =

        {

        CAPTION_AND_ICON_INFO

            {

            caption = STRING_r_caption;

            number_of_icons = 2; // each icon must be a bitmap/mask pair

            icon_file = STRING_r_icon_file;

            }

        };                            

    //

    view_list =

        {

        VIEW_DATA

            {

            uid = 268123123;

            screen_mode = 0x00;

            caption_and_icon =

                {

                CAPTION_AND_ICON_INFO

                    {

                    caption = STRING_r_view_268123123_caption;

                    number_of_icons = 1; // each icon must be a bitmap/mask pair

                    }

                };                            

            },

        VIEW_DATA

            {

            uid = 268123124;

            screen_mode = 0x01;

            caption_and_icon =

                {

                CAPTION_AND_ICON_INFO

                    {

                    caption = STRING_r_view_268123124_caption;

                    number_of_icons = 1; // each icon must be a bitmap/mask pair

                    icon_file = "z:\\resource\\apps\\icon.svg";

                    }

                };

            }

        };

    }</codeblock> <p><b>Note</b>: In the above example, RLS files have been

used to demonstrate how resource files for different languages (<codeph>AppName_loc.r01</codeph> and <codeph>AppName_loc.rsc</codeph>)

can be built from a single RSS file. </p> <p id="GUID-E828B29C-35AC-50CA-8B76-FD626D825E1A"><b> AppName01.rls</b> </p><codeblock id="GUID-BB8CC777-51FC-5BFC-99B3-19D68C130458" xml:space="preserve">rls_string STRING_r_short_caption "English AppName" 

rls_string STRING_r_caption "English AppName Long Caption" 

rls_string STRING_r_icon_file "z:\\resource\\apps\\EnglishAppNameIcons.mbm" 

rls_string STRING_r_view_268123123_caption "caption for view 268123123" 

rls_string STRING_r_view_268123124_caption "English view 268123124"</codeblock> <p id="GUID-8E9F17B1-4A22-56EF-ACD8-0432F3BB9DBD"><b> AppNamesc.rls</b> </p><codeblock id="GUID-F5182C0B-1F5E-5F7A-9F10-C0DCA34E0B84" xml:space="preserve">rls_string STRING_r_short_caption "AppName" 

rls_string STRING_r_caption "Default AppName Caption" 

rls_string STRING_r_icon_file "z:\\resource\\apps\\DefaultAppNameIcons.mbm" 

rls_string STRING_r_view_268123123_caption "caption for view 268123123" 

rls_string STRING_r_view_268123124_caption "caption for view 268123124"</codeblock> <p id="GUID-065DF486-615D-55F1-8572-DF30E58927C3"><b> AppName2_reg.rss</b> </p><codeblock id="GUID-3B7C2951-9B1D-51FD-9AED-2B68EEE6CA62" xml:space="preserve">#include &lt;appinfo.rh&gt; 

#include <appname.rsg>

UID2 KUidAppRegistrationResourceFile 

UID3 0x01000000 // application UID

RESOURCE APP_REGISTRATION_INFO

    {

    app_file = "AppName";

    //

    localisable_resource_file = "\\resource\\apps\\appname";

    localisable_resource_id = R_LAI;

    }</codeblock> <p id="GUID-661C0B2C-9BA9-5168-B2A9-A2FA1F87B5D7"><b> AppName.rss</b> </p><codeblock id="GUID-54DDDB25-E66F-5CF1-ACA3-93244C44CC8D" xml:space="preserve">NAME APPN

#include <eikon.rh> 

#include <eikon.rsg> 

#include <appinfo.rh>

RESOURCE RSS_SIGNATURE                { } 

RESOURCE TBUF r_appname_default_file  { buf="default file name"; } 

RESOURCE EIK_APP_INFO                 { hotkeys=r_appname_hotkeys; menubar=r_appname_menubar; toolbar=r_appname_toolbar; } 

RESOURCE LOCALISABLE_APP_INFO r_lai

    {

    short_caption = "AppName";

    } 

RESOURCE TOOLBAR r_appname_toolbar        { } 

RESOURCE HOTKEYS r_appname_hotkeys        { } 

RESOURCE MENU_BAR r_appname_menubar       { }</codeblock> </section>

</conbody><related-links>

<link href="GUID-3CAD7211-2164-5F93-9EA7-7167E1C14012.dita"><linktext>Porting Applications

to EXEs</linktext></link>

</related-links></concept>