Porting -Data-caged Applications

Porting -Data-caged ApplicationsThis 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 { }

-Porting Applications -to EXEs + + + + + +Porting +Data-caged ApplicationsThis 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 { }

+Porting Applications +to EXEs

\ No newline at end of file