<?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">
<image href="GUID-E4B5C7CE-7820-5D80-8CD1-DCD692C11F23_d0e115649_href.png" placement="inline"/>
</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 &lt;appname.rsg&gt;

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 &lt;eikon.rh&gt; 
#include &lt;eikon.rsg&gt; 
#include &lt;appinfo.rh&gt;

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>