This document describes the changes required to migrate exe-apps to a data caged directory structure.

• Application changes

  • Mandatory steps

    • The registration file

    • Build the application binary to a new location

  • Optional steps

    • Default UI resource file location

    • Default MBM file location

    • Application information

      • Registration file

      • Localisable resource file

• Software install package file requirements

• Data caged file locations

• Example files

  • AppName_reg.rss

  • AppName_loc.rss

    • AppName01.rls

    • AppNamesc.rls

  • AppName2_reg.rss

  • AppName.rss

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.

Migrated applications must provide a registration file, and may optionally provide localisable application information resource files and icon files. Localisable application information resource files provide localisable application information (for instance captions and icons), whereas an application's localisable UI resource file provides UI resources such as menus and dialogs.

Migrated applications may be used with or without data caging enforced.

The following sections detail the mandatory and optional steps required to migrate an application.

The following steps represent the minimal changes required to migrate an application.

All applications must provide a registration file.

A registration file is a standard Symbian OS compiled resource file (.rsc). The .rss file used to build the registration file should be named AppName_reg.rss and contain at least the following lines:

#include <appinfo.rh> 
UID2 KUidAppRegistrationResourceFile 
UID3 0x01000000 // application UID 
RESOURCE APP_REGISTRATION_INFO
    {
    app_file="AppName"; // filename of application binary (minus extension)
    }

To build the registration file, add the following lines to the application's MMP file:

START RESOURCE AppName_reg.rss 
TARGETPATH      \private\10003a3f\apps 
END

The _reg filename suffix is used as a naming convention only and is not mandatory.

Note that any lines in the MMP file that are used to build an AIF file should be removed.

The following line should replace the TARGETPATH line associated with the TARGET, TARGETTYPE and UID lines:

TARGETPATH      \sys\bin

The following steps are only required if the application provides one or more of the following:

• A UI resource file whose location is provided by CEikApplication::ResourceFileName()

• An MBM file whose location is provided by CEikApplication::BitmapStoreName()

• Application information via an AIF and/or caption file.

When building the application UI resource file, the TARGETPATH must be specified as follows:

TARGETPATH      \resource\apps

When building the application's MBM file, the TARGETPATH must be specified as follows:

TARGETPATH      \resource\apps

The localisable information that was previously provided by a combination of AIF and caption files, has been split into two categories:

• Non-localisable information (provided by the registration file)

• Localisable information (localisable resource file and icon file)

The diagram below shows the new file structure used to provide application information.

The diagram shows:

• A registration file which 'points' to one of three localisable resource files provided. If the current language is 01 or 02, the system will load the corresponding version of AppName_loc, otherwise AppName_loc.rsc will be loaded.

• AppName_loc.r01 and AppName_loc.r02 share the same icon file.

Registration file

The registration file provides non-localisable application information. For an example registration file see AppName_reg.rss in the Example files section.

Localisable resource file

Localisable application information can either be provided in a separate resource file (see AppName_loc.rss), or as a resource within the application UI resource file (see AppName.rss and AppName2_reg.rss in the Example files section).

When providing the information as a resource within the application UI resource file, the registration file's APP_REGISTRATION_INFO struct must contain the following lines:

    localisable_resource_file="\\resource\\apps\\AppName";    
localisable_resource_id = R_LAI;

where R_LAI is a named LOCALISABLE_APP_INFO resource struct within the UI resource file.

The localisable_resource_file 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).

To build a resource file for language 01, add the following to the MMP file:

start resource AppName_loc.rss
targetpath      \resource\apps 
lang            01 
end

The _loc filename suffix is used as a naming convention only and is not mandatory.

Icon files referenced in the localisable resource should also be built to \resource\apps\.

When creating a PKG file (software install package file) for an application, the registration file must be installed to the \private\10003a3f\import\apps\ directory.

The application binary must be installed to \sys\bin\ on the same drive as the registration file.

The localisable resource files must be installed to \resource\apps\ on the same drive as the registration file.

To comply with the directory structure imposed by data caging, many of the files associated with an application need to be relocated.

Care should be taken to ensure application code which overrides the following APIs uses appropriate file locations:

CEikApplication::ResourceFileName() 
CEikApplication::BitmapStoreName() 
CEikApplication::OpenIniFileLC(RFs& aFs)

When specifying the location of files on a target device, application IBY files should explicitly specify \sys\bin as the destination location for application binary files instead of using SYSTEM_BINDIR.

#include <appinfo.rh>

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"; }
        };
    }

#include <appinfo.rh> 
#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";
                    }
                };
            }
        };
    }

Note: in the above example, RLS files have been used to demonstrate how resource files for different languages (AppName_loc.r01 and AppName_loc.rsc) can be built from a single RSS file.

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"

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"

#include <appinfo.rh> 
#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;
    }

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       { }