<?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>
</conbody></concept>