Mobile and Devices Developer Center

Making a simple SWF launcher with Nokia Carbide.c++ IDE (for Symbian 3rd Edition)

In this tutorial, I show you how to create a standard Symbian application with a personalized icon in a smartphone's menu that simply starts the SWF file of a Flash project and then exits the Symbian application. You will do that using Carbide Express and a self-signed certificate.

This tutorial is not an installation and configuration process for Symbian SDK, Carbide, or other tools required for compiling smartphone applications. It assumes that you already have a minimal confidence with Symbian and the C++ language.

Note: With Carbide.c++ Express edition, only open source or noncommercial applications can be released. Self-signed certification can be used only by applications that don't require any of this capability.

Requirements

To complete this tutorial you will need to install the following software and files:

Symbian 3rd Edition (9.0 or later) SDK

• Download the SDK

Perl

• Learn more

Java Runtime version 1.4 (or later)

• Learn more

Carbide.c++ Express

• Download development tools

Flash Lite 1.1, 2.0, or 2.1 Player

• Download

Device compatibility

You must have a device that is compatible with Symbian 3rd Edition (9.0 or later) and Flash Lite 1.1, 2.0, 2.1 (or later).

Sample files:

• swf_launcher_symbian_3rd_edition_file.zip (ZIP, 1.2 MB)

Prerequisite knowledge

Familiarity with Flash Lite, Carbide, Symbian SDK, Java, Perl, and Carbide.c++ Express.

UID, certificate, and private key

Every GUI application should have its own unique identifier (UID). The unique identifier is a 32-bit number that you get directly from Symbian after a simple registration process. For a self-signed application, you can use a UID from the "unprotected range" because the application does not require any restricted capabilities (see the Symbian website for details). Once you have your personal UID, you need only the certificate to sign the SIS (Symbian installation) file.

The certification generator, MakeKeys.exe, is installed with the Symbian 3rd Edition (9.0 or later) SDK and is a PC-based command-line tool that creates a private/public key pair and issues certificate requests. The resultant private key is used to sign installation files digitally, enabling the install system to authenticate them.

The syntax for generating your private key and self-signed certificate is as follows:

makekeys -cert [-v] [-password <password>] [-len <key-length>] -dname <distinguised-name-string> <private-key-file> <public-key-cert>

For example:

makekeys -cert -password yourpassword -len 2048 -dname "CN=Leonardo Risuleo  OU=Development OR=mobile.actionscript.it CO=GB EM=byte.sm@gmail.com" mykey.key mycert.cer

Figure 1 shows a screen shot of the process.

Figure 1. Generating the private key and self-signed certificate

This tool outputs the following two files:

• Certificate file: *.cer
• Key file: *.key

Creating a new project

Now that you have the key, you are ready to begin!

1. Open Carbide and create a new Symbian project by selecting File > New > Symbian OS C++ Project (see Figure 2). The project wizard appears.

   

   Figure 2. Creating a new Symbian project in Carbide

   Note: Make sure your workspace path doesn't contain any spaces. Otherwise the Java virtual machine will not be able to compile your project.

2. From the project wizard, select "S60 3.x GUI application (EXE)" (see Figure 3).

   

   Figure 3. Selecting S60 3.x GUI application (EXE) in the project wizard

3. At this point Carbide prompts you to choose a target profile for compiling. Make sure that both Emulator and Debug Profile are checked before you continue.
4. Insert the application UID you received from Symbian when you registered, as outlined in the previous section.
5. Configure the project's directory structure. Leave this as the default. Once you have done this and completed the steps in the project wizard, you should see your new project in the left panel within the C/C++ Projects tab.
6. Right-click the project's folder, select Properties, and enter the C/C++ Build section.
7. Change the configuration to S60 3.0 Phone (GCCE) Release.

8. From Tool Setting tab, select CreateSis (Installation File Generator) > General Options and specify the location path and password for your certificate and key files (see Figure 4). You can also give the SIS file a different name.

   

   Figure 4. Configuring the Tool Setting tab

9. Select GCCE Linker > Libraries and add the string for the apgrfx library: ${EPOC32_RELEASE_ROOT}\ARMV5\LIB\apgrfx.dso (see Figure 5).

   

   Figure 5. Selecting GCCE Linker > Libraries and adding the string in the Tool Setting tab

10. Save your properties and close the panel.

Required changes to the source files

You want the GUI application to remain in the background while launching the SWF file. To do that, you simply add the launch property in the our_project_reg.rss file (located in data folder) as follows:

RESOURCE APP_REGISTRATION_INFO
  {
  app_file="HelloFlash";
  localisable_resource_file =  qtn_loc_resource_file_1;
  localisable_resource_id = R_LOCALISABLE_APP_INFO;

  embeddability=KAppNotEmbeddable;
  newfile=KAppDoesNotSupportNewFile;
  
  launch=KAppLaunchInBackground;
  }

Now edit the C++ file. You have to modify the AppUi class, which is located in scr folder (usually named our_projectappui.cpp). First, include the library required for launching a general document:

#include <apgcli.h>

Then modify the ConsructL() method as follows:

void Cvoid CHelloFlashAppUi::ConstructL()
{
// Initialise app UI with standard value.
BaseConstructL();

// Create view object
iAppView = CHelloFlashAppView::NewL( ClientRect() );

//initialization
01    TThreadId id;
02    RApaLsSession ls;
03    User::LeaveIfError(ls.Connect());
04    CleanupClosePushL(ls);
05    _LIT(KLitSwfFileToLaunch, "\\Others\\HelloFlash.swf");
06    TFileName fileName(KLitSwfFileToLaunch);
07    CompleteWithAppPath(fileName);
08    User::LeaveIfError(ls.StartDocument(fileName,id));
09    CleanupStack::PopAndDestroy(); //ls

Exit();
}>

Note: I am providing all the code here "as is," without warranty of any kind. Please check the Symbian SDK for further documentation and help if you run into any problems.

Lines 1–4 of the initialization block are for the instantiation of a target thread (the process that handles the SWF) and a session with the application architecture server. Line 5 defines the path of the Flash Lite application without any drive specification. In fact, the CompleteWithAppPath command on Line 7 does this for you. It depends on your preference during the installation process. Finally, the Lines 7–9 start the document and delete the application server.

Package file

The PKG file is a text file that specifies the installation information for applications and files. It is typically located in the SIS folder. In this file, you have to declare which files will be copied to the target device. In this project, only the SWF file needs to be copied:

"C:\workspace\HelloFlash\sis\HelloFlash.swf"  -  "!:\Others\HelloFlash.swf"

Here you can also decide to display additional information during installation, such as a license agreement or language localization. However, this is beyond the scope and purpose of this tutorial.

Icons

In the S60 3rd Edition, Nokia introduces a new Application Information File (AIF) framework that supports scalable application icons. You will use a single SVG-T file by simply editing the existing one in the gfx directory. You can edit the icon's file using any software capable of saving graphics in SVG Tiny1.1+ format, such as InkScape or Adobe Illustrator. Here are some resources for learning more about editing SVG files:

• S60 Platform Vector Graphics Optimization on Forum .Nokia (PDF, 372 KB)
• Creating SVG with Adobe Illustrator CS 2 (PDF, 1.45 MB)

Finally, you are ready to build and test your work! Select Project > Build Project and wait for the process to complete. If all is OK, you now have your final, signed application file in the SIS directory.

Transfer the file to your Symbian 3rd Edition (9.0 or later) and Flash Lite 1.1, 2.0, 2.1 (or later) compatible device and test it. You should see something similar to what appears in Figures 6 and 7.

Figure 6. Installing the application

Figure 7. Final signed application

Where to go from here

This article includes the completed application, which is linked to at the beginning of this tutorial. To use the files, download them, unzip them, and follow these steps:

1. Select File > Import and select the downloaded archive.
2. Edit the SIS properties to reflect your certificate and key file.

About the author