An example registration file and icon/caption file

This document describes two methods of defining application registration information. In both cases, a minimal example registration file called HelloWorld_reg.rss is used. In the first method, the icon/caption information is defined in its own file. In the second, it is defined in the application's UI resource file. The registration file is largely the same in both cases.

The registration file

A registration file is a resource file that is compiled by the resource compiler in the standard way, by including lines like the following in the application's mmp file:

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

This will cause HelloWorld_reg.rss to be compiled, creating HelloWorld_reg.rsc. On the emulator, all registration files should be located in \private\10003a3f\apps. This is also true on real hardware for registration files built into the ROM. For applications installed onto a phone using the standard software installation method, their registration files should be installed into \private\10003a3f\import\apps. In all cases, the registration file must be located on the same drive as the application.

A minimal registration file looks like this:

#include <appinfo.rh>

UID2 KUidAppRegistrationResourceFile
UID3 0x10004299 // application UID
RESOURCE APP_REGISTRATION_INFO
    {
    app_file = "HelloWorld";
    localisable_resource_file = "\\resource\\apps\\HelloWorld_loc";
 }

All registration files must define UID2, which is always KUidAppRegistrationResourceFile, and UID3, which is the application's UID, and an APP_REGISTRATION_INFO resource that minimally needs to provide the name of the application binary (using the app_file statement). All registration files need to #include appinfo.rh.

If a localisable icon/caption definition file is provided, as in this example, its full path and filename must be specified, excluding the drive letter and file extension.

The localisable icon/caption definition file

This file defines the application's captions and the name of the icon file. It is built to the \resource\apps\ directory on the same drive as the registration file; this applies both on the emulator and target phone. By convention it has the same filename as the application, but with a _loc suffix.

It is a standard localisable Symbian resource file, so it is compiled by the resource compiler by including lines like the following in the application's mmp file:

start resource HelloWorld_loc.rss
targetpath      \resource\apps
lang            01 02
end

These lines cause two versions of the file to be compiled, called HelloWorld_loc.r01 and HelloWorld_loc.r02. HelloWorld_loc.rss looks like this:

#include <appinfo.rh>
#ifdef LANGUAGE_01
#include "HelloWorld01.rls"
#elif defined LANGUAGE_02
#include "HelloWorld02.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 = 3; // each icon must be a bitmap/mask pair
            icon_file = STRING_r_icon_file;
            }
        };                          
    }

Unlike most resource files, because there is only one resource defined in the file, it does not need to include a four character NAME or an RSS_SIGNATURE resource, and the LOCALISABLE_APP_INFO resource does not need an ID.

The captions and the icon filename are referred to by symbolic identifiers rather than by the strings themselves. The strings are defined in .rls files (resource localisable string files), as shown below and conditional compilation statements are used to include the appropriate .rls file. For more information, on localising strings in resource files, see How to localise resources.

HelloWorld01.rls contains:

rls_string STRING_r_short_caption "Hello"
rls_string STRING_r_caption "Hello World"
rls_string STRING_r_icon_file "z:\\resource\\apps\\Hello.mbm"

HelloWorld02.rls contains:

rls_string STRING_r_short_caption "Bonjour"
rls_string STRING_r_caption "Bonjour tout le monde"
rls_string STRING_r_icon_file "z:\\resource\\apps\\Bonjour.mbm"

The mbm icon files are built by adding start bitmap statements to the mmp file, for instance:

START BITMAP   Hello.mbm
TARGETPATH      \Resource\Apps
SOURCE          c8,1 icon24.bmp icon24m.bmp icon32.bmp icon32m.bmp icon48.bmp icon48m.bmp
END

As an alternative to defining the icon/caption information in an icon/caption definition file, it can be defined in the application's existing UI resource definition file. In this case, the LOCALISABLE_APP_INFO resource must be given an ID, because it is no longer the only resource defined in the file. The registration file is as before, except that it must now specify the ID of the LOCALISABLE_APP_INFO resource as well as the name and location of the UI resource file. In other words, the line:

localisable_resource_file = "\\resource\\apps\\HelloWorld_loc";

needs to be changed to:

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

where R_LAI is the ID of the LOCALISABLE_APP_INFO resource. Because the registration file needs to give the resource ID, it must #include the application's generated resource header file, HelloWorld.rsg. Also, the UI resource file needs to #include AppInfo.rh for the LOCALISABLE_APP_INFO definition.