2 Application building

The target type for applications has been changed from APP to EXE.

UIQ 2.1:

TARGET          HelloWorld.app
TARGETTYPE      APP

UIQ 3:

TARGET          HelloWorld.exe
TARGETTYPE      EXE

The vendor ID (VID) is new in Symbian OS v9 and specifies the vendor of the application executable. In most cases, this will be zero, which means that the source of the executable is not required for security checks. VIDs are allocated to Symbian licensees, partners, operators and Independent Software Vendors through sign-up programs.

UIQ 3:

VENDORID            0

From Symbian OS v9, applications need to specify the directory for the built resource. This is done by using the start resource syntax.

Application information files (AIF) are no longer used. Instead, registration and localization resource files are used. See the section on the .aif file.

UIQ 2.1:

RESOURCE        HelloWorld.rss

AIF             HelloWorld.aif . HelloAif.rss c8,1 hello.bmp hellom.bmp

UIQ 3:

// The application main resource file
START RESOURCE      HelloWorld.rss
HEADER
TARGETPATH          \resource\apps
LANG                SC
END

// The application registration file containing non-localizable
// application information
// All registration files should be located in the same target path
START RESOURCE      HelloWorld_reg.rss
TARGETPATH          \private\10003a3f\apps
END

// The file containing the application caption and name of icon file
START RESOURCE      HelloWorld_loc.rss
TARGETPATH          \resource\apps
LANG                SC
END

New in Symbian OS v9 is the introduction of Platform Security and the capability model. The CAPABILITY statement is included in the .mmp file.

UIQ 3:

CAPABILITY              LocalServices ReadUserData

The application information file (AIF) has been replaced by a pair of resource files: a registration resource file and a localizable resource file.

UIQ 2.1:

// helloaif.rss
//
// Copyright (c) 2000 Symbian Ltd. All rights reserved.

#include <aiftool.rh>

RESOURCE AIF_DATA
    {
    caption_list =
        {
        CAPTION { code = ELangEnglish; caption = "HelloWorld"; }
        };
    app_uid = 0x101f6163;
    num_icons = 1;
    }

UIQ 3:

Registration resource file:

// HelloWorld_reg.rss
//
// Copyright (c) Symbian Software Ltd 2005. All rights reserved.
//

#include <AppInfo.rh>

UID2 KUidAppRegistrationResourceFile
UID3 0x101F6163 // application UID

RESOURCE APP_REGISTRATION_INFO
    {
    app_file = "HelloWorld"; // Application binary (minus extension)
    localisable_resource_file = "\\Resource\\Apps\\HelloWorld_loc";
    }

Localizable resource file:

// HelloWorld_loc.rss
//
// Copyright (c) Symbian Software Ltd 2005. All rights reserved.
//

#include <AppInfo.rh>
#include "HelloWorld.rls"

// This file localizes the application's icons and captions
RESOURCE LOCALISABLE_APP_INFO
    {
    short_caption = STRING_r_helloworld_short_caption;
    caption_and_icon =
        {
        CAPTION_AND_ICON_INFO
            {
            caption = STRING_r_helloworld_caption;
            number_of_icons = 3;
            icon_file = "\\Resource\\Apps\\default_app_icon.mbm";
            }
        };                          
    }

The installation locations have changed since the introduction of Platform Security, see the section on Platform Security.

Also, the product ID for UIQ 3 has been updated.

UIQ 2.1:

[…]

; Name,UID,Major,Minor,Build
#{"HelloWorld"},(0x101F6163),1,0,0,TYPE=SA
; ProductID for UIQ 2.1
(0x101F617B), 2, 1, 0, {"UIQ21ProductID"}

[…]

; UIQ 2.1 installation locations

"\epoc32\release\armi\urel\HelloWorld.app"-"!:\system\apps\HelloWorld\HelloWorld.app"

"\epoc32\data\z\system\apps\HelloWorld\HelloWorld.rsc"-"!:\system\apps\HelloWorld\HelloWorld.rsc"

"\epoc32\data\z\system\apps\HelloWorld\HelloWorld.aif"-"!:\system\apps\HelloWorld\HelloWorld.aif"

"\epoc32\data\z\system\apps\HelloWorld\HelloWorld.mbm"-"!:\system\apps\HelloWorld\HelloWorld.mbm"

"\epoc32\data\z\system\apps\HelloWorld\SomePrivateFile.txt"-"!:\system\apps\HelloWorld\SomePrivateFile.txt"

UIQ 3:

[…]

; Package header:
; Name,UID,Major,Minor,Build
#{"HelloWorld"},(0x101F6163),1,0,0,TYPE=SA

; ProductID for UIQ 3 (Must be defined after the package header)
(0x101F6300), 3, 0, 0, {"UIQ30ProductID"}

[…]

; UIQ 3 Installation locations

"\epoc32\release\armv5\urel\HelloWorld.exe"-"!:\sys\bin\HelloWorld.exe"

"\epoc32\data\z\resource\apps\HelloWorld.rsc"-"!:\resource\apps\HelloWorld.rsc"

"\epoc32\data\z\resource\apps\HelloWorld_loc.rsc"-"!:\resource\apps\HelloWorld_loc.rsc"

"\epoc32\data\z\resource\apps\HelloWorld.mbm"-"!:\resource\apps\HelloWorld.mbm"

"\epoc32\data\z\private\10003a3f\apps\HelloWorld_reg.rsc"-"!:\private\10003a3f\import\apps\HelloWorld_reg.rsc"

"\epoc32\data\z\private\101f6163\SomePrivateFile.txt"-"!:\private\101f6163\SomePrivateFile.txt"

At installation, the registration resource file should be placed in the apparc server’s import directory (\private\10003a3f\import\apps).

Any extra application private files should be installed in the application’s private directory (in this case \private\101f6163).

In UIQ 3.0 phone manufacturers can customize the names and locations of the default media folders on a per drive basis. On most phones, users are able to choose which drive to install media files on when the application uses the wildcard, "!", as the drive. This means that the name and location of the user’s media files cannot be known by an application. Applications that wish to pre-install media files in the user’s media folders need a way to refer to these folders indirectly.

The solution in UIQ 3.0 is for applications to use a set of six keywords in the package file, .pkg, to map media files included in the SIS file to the user's media folders:

\MMFH_PATH_ROOT\
\MMFH_PATH_IMAGE\
\MMFH_PATH_AUDIO\
\MMFH_PATH_VIDEO\
\MMFH_PATH_DOCUMENT\
\MMFH_PATH_OTHER\

These keywords will be replaced by the true path during application installation. These keywords represent the five default media folders, “Image”, “Audio”, “Video”, “Document” and “Other”, which are located at the MMFH (Multimedia File Handling) root, as well as the MMFH root itself.

Consider a phone that has the following MMFH folder structures. C is the internal drive and D is an external drive:

Here are some examples of how to use the new keywords in your .pkg file. The examples assume the drive and folder structure described above.

Example 1

You have a file you would like to place in the MMFH Image folder on the drive that is chosen by the user for storing image files. In the .pkg file declare:

"TestPicture.bmp"-"!:\MMFH_PATH_IMAGE\TestPicture.bmp"

The true path for the file will become "C:\Media Files\Image\TestPicture.bmp" or "D:\Media\Pictures\TestPicture.bmp" depending on which drive has been chosen for storing images.

Example 2

You want to store a file in new folder directly under the MMFH root. In the .pkg file declare:

"CoolSite.html"-"!:\MMFH_PATH_ROOT\WebSites\CoolSite.html"

The folder "WebSites" will be created on the phone. The true path for the file will become "C:\Media Files\WebSites\CoolSite.html" or "D:\Media\ WebSites\CoolSite.html" depending on which drive has been chosen for the MMFH root.

Example 3

You want to store a file in a new folder in the MMFH Audio folder. In the .pkg file declare:

"CoolTune.m4a"-"!:\MMFH_PATH_AUDIO\GoodMusic\CoolTune.m4a"

The folder "GoodMusic" will be created on the phone. The true path for the file will become "C:\Media Files\Audio\GoodMusic\CoolTune.m4a" or "D:\Media\Sounds\GoodMusic\CoolTune.m4a" depending on which drive has been chosen for storing audio files.

Example 4

You want to explicitly store a file on the internal drive. Replace the wildcard, “!”, with “C”. In the .pkg file declare:

"Tutorial.3gp"-"C:\MMFH_PATH_AUDIO\Video\Tutorial.3gp"

The true path for the file will become “C:\Media Files\Video\Tutorial.3gp".

IMPORTANT: You should never store a media file explicitly on an external drive because you can never be sure of which drive and folder are intended for storing media files.