<?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-188F9462-F805-522A-84FF-770EAB045504" xml:lang="en"><title>An

example registration file and icon/caption file</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<section><title>Introduction</title> <p>This document describes two methods

of defining application registration information. In both cases, a minimal

example registration file called <filepath>HelloWorld_reg.rss</filepath> 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. </p> </section>

<section><title>Registration file with an icon/caption definition file</title> <p><b>The

registration file </b> </p> <p>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: </p> <codeblock id="GUID-CA21DAF9-C789-54D3-B768-212F03EB8EAB" xml:space="preserve">START RESOURCE    HelloWorld_reg.rss

TARGETPATH        \private\10003a3f\apps

END</codeblock> <p>This will cause <filepath>HelloWorld_reg.rss</filepath> to

be compiled, creating <filepath>HelloWorld_reg.rsc</filepath>. On the Symbian

emulator, all registration files should be located in <filepath>\private\10003a3f\apps</filepath>.

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 <filepath>\private\10003a3f\import\apps</filepath>.

In all cases, the registration file must be located on the same drive as the

application. </p> <p>A minimal registration file looks like this: </p> <codeblock id="GUID-386B4305-538A-58B7-9908-34104EE20814" xml:space="preserve">#include &lt;appinfo.rh&gt;

UID2 KUidAppRegistrationResourceFile

UID3 0x10004299 // application UID

RESOURCE APP_REGISTRATION_INFO

    {

    app_file = "HelloWorld";

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

 }</codeblock> <p>All registration files must define <codeph>UID2</codeph>,

which is always <codeph>KUidAppRegistrationResourceFile</codeph>, and <codeph>UID3</codeph>,

which is the application's UID, and an <codeph>APP_REGISTRATION_INFO</codeph> resource

that minimally needs to provide the name of the application binary (using

the <codeph>app_file</codeph> statement). All registration files need to <codeph>#include</codeph>  <filepath>appinfo.rh</filepath>. </p> <p>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. </p> <p><b>The localisable icon/caption definition

file </b> </p> <p>This file defines the application's captions and the name

of the icon file. It is built to the <filepath>\resource\apps\</filepath> directory

on the same drive as the registration file; this applies both on the Symbian

emulator and target phone. By convention it has the same filename as the application,

but with a <filepath>_loc</filepath> suffix. </p> <p>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: </p> <codeblock id="GUID-FB3180D0-086E-5B3B-BC73-51BA723512D6" xml:space="preserve">start resource    HelloWorld_loc.rss

targetpath        \resource\apps

lang            01 02

end</codeblock> <p>These lines cause two versions of the file to be compiled,

called <filepath>HelloWorld_loc.r01</filepath> and <filepath>HelloWorld_loc.r02</filepath>. <filepath>HelloWorld_loc.rss</filepath> looks

like this: </p> <codeblock id="GUID-BFADC6C8-6D06-50A6-BB0E-CCE40C7D12D0" xml:space="preserve">#include &lt;appinfo.rh&gt;

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

            }

        };                            

    }</codeblock> <p>Unlike most resource files, because there is only one

resource defined in the file, it does not need to include a four character <codeph>NAME</codeph> or

an <codeph>RSS_SIGNATURE</codeph> resource, and the <codeph>LOCALISABLE_APP_INFO</codeph> resource

does not need an ID. </p> <p>The captions and the icon filename are referred

to by symbolic identifiers rather than by the strings themselves. The strings

are defined in <filepath>.rls</filepath> files (resource localisable string

files), as shown below and conditional compilation statements are used to

include the appropriate <filepath>.rls</filepath> file. For more information,

on localising strings in resource files, see <xref href="GUID-F35C5336-907C-5B2A-92C6-F8883D49996E.dita">How

to localise resources</xref>. </p> <p> <filepath>HelloWorld01.rls</filepath> contains: </p> <codeblock id="GUID-CC264837-CE3D-514A-A35A-032CE6F040C1" xml:space="preserve">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"</codeblock> <p> <filepath>HelloWorld02.rls</filepath> contains: </p> <codeblock id="GUID-941FDCF8-FAE9-5E3B-A5AA-FC85A6D6B9FA" xml:space="preserve">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"</codeblock> <p>The

mbm icon files are built by adding <xref href="GUID-B707887A-E0FA-5DF6-A906-A91E31E17321.dita">start

bitmap</xref> statements to the mmp file, for instance: </p> <codeblock id="GUID-B73430EF-510C-583E-B721-E82BB4BE1784" xml:space="preserve">START BITMAP    Hello.mbm

TARGETPATH        \Resource\Apps

SOURCE            c8,1 icon24.bmp icon24m.bmp icon32.bmp icon32m.bmp icon48.bmp icon48m.bmp

END</codeblock> </section>

<section><title>Registration file without an icon/caption definition file</title> <p>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 <codeph>LOCALISABLE_APP_INFO</codeph> 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 <codeph>LOCALISABLE_APP_INFO</codeph> resource as well as the

name and location of the UI resource file. In other words, the line: </p> <codeblock id="GUID-08AEB128-25E5-52DA-AD3E-C8733BA660A1" xml:space="preserve">localisable_resource_file = "\\resource\\apps\\HelloWorld_loc";</codeblock> <p>needs

to be changed to: </p> <codeblock id="GUID-3EE8477E-4FB1-51F9-AF42-42107FFA6933" xml:space="preserve">localisable_resource_file = "\\resource\\apps\\HelloWorld";

localisable_resource_id = R_LAI;</codeblock> <p>where <codeph>R_LAI</codeph> is

the ID of the <codeph>LOCALISABLE_APP_INFO</codeph> resource. Because the

registration file needs to give the resource ID, it must <codeph>#include</codeph> the

application's generated resource header file, <filepath>HelloWorld.rsg</filepath>.

Also, the UI resource file needs to <codeph>#include</codeph>  <filepath>AppInfo.rh</filepath> for

the <codeph>LOCALISABLE_APP_INFO</codeph> definition. </p> </section>