Porting Data-caged Applications

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

Introduction

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 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.

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

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

A registration file which 'points' to one of three localizable 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.

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

Procedure

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

Mandatory steps

Provide a registration file.

A registration file is a standard Symbian platform 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.
Build the application binary to a new location.

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

Optional steps

A UI resource file whose location is provided by CEikApplication::ResourceFileName()
An MBM file whose location is provided by CEikApplication::BitmapStoreName()
Application information through an AIF and/or caption file.

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

Specify the default UI resource file location.

When building the application UI resource file, the TARGETPATH must be specified as follows:
```
TARGETPATH        \resource\apps
```
Specify the default MBM file location.

When building the application's MBM file, the TARGETPATH must be specified as follows:
```
TARGETPATH        \resource\apps
```
Specify the application information by providing the following files:
- Non-localizable information (provided by the registration file)
  
  The registration file provides non-localizable application information. For an example registration file see AppName_reg.rss in the Example files section.
- Localizable information (localizable resource file and icon file)
  
  Localizable 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 localizable resource should also be built to \resource\apps\.

Software install package file requirements

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 localizable resource files must be installed to \resource\apps\ on the same drive as the registration file.

Data caged file locations

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.

Example files

AppName_reg.rss

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

AppName_loc.rss

#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.

AppName01.rls

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"

AppNamesc.rls

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"

AppName2_reg.rss

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

AppName.rss

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

Related concepts

Porting Applications to EXEs