Developing Series 60 Applications: A Guide for Symbian OS C++ Developers: A Guide for Symbian OS C++ Developers

Often during the development of system components , communications modules, application engines and other self-contained functional units you may want a simple test application. Such "test harnesses" allow you to run and exercise your code as it develops.

GUI applications are often not the best option for this purpose; they can be too heavyweight just for testing, particularly so for regression testing (reproducible functional testing). Console applications are often a better option, and they have one key advantage. Since they are .exe 's rather than .app 's, and therefore do not need the GUI libraries, the emulator and application start up very much faster.

Console applications differ from GUI applications in the following ways:

• They provide text output only ”there are no menus , icons, dialogs and so on.

• Console applications are not suitable for deployment onto an end users device ”typically there is no way of locating or launching them.

• They must provide their own essential runtime objects, such as a Cleanup Stack and Active Scheduler ”UI applications have these provided by the framework classes from which they derive. Note that by examining the code in the console application example ( HelloWorldCon ) you can see how these objects are created.

• Console applications also do not have application information ( .aif ) files or resource ( .rsc ) files.

So, if like many developers you prefer to create and test your code incrementally, the fast start-up speed of a console application is an important consideration.

A key disadvantage of console applications (apart from the simple text interface) is that only one application can be running in the emulator at once. This is because the PC-based Series 60 emulator ( epoc.exe ) is single process, and Symbian OS .exe applications must run in their own process. Therefore console .exe 's are linked with eexe.obj , and this causes the emulator to be launched and to run the application as the main process.

The Hello World Console Application

An example console application, HelloWorldCon , is provided, and when built, it consists of a single executable file with a filename extension of .exe . In Symbian OS, such executables are used for two main purposes; as servers with no user interface or as test harnesses with very simple text-based interfaces.

Note that the project code in the HelloWorldCon.cpp file is quite brief and relatively simple. It implements a single function called doExampleL() , called from callExampleL() , a function defined in a header file CommonFramework.h . This header file is provided as part of the Series 60 SDK and is ideal as the basis for any other console-based test harnesses used during general development work.

The main entry point for .exe programs is E32Main() . This function sets up a memory leak macro, Cleanup Stack, and trap harness for handling any exceptions occurring in the callExample() function. This function creates a text console, a console class object derived from CConsoleBase , and calls doExampleL() . You should place or call your test code from within the doExampleL() function. Concepts such as trAP harnesses and the Cleanup Stack are explained in Chapter 3.

Build and Run the Console Application

Open a command prompt and navigate to the folder that contains the project code ”for example, \EMCCSoft\HelloWorldCon ”in the root of your SDK. This folder will contain three files:

This project also requires the CommonFramework.h header file, provided with the SDK. Depending on your SDK, this will be located in a folder like:

...\Epoc32Ex\Base\CommonFramework

or

...\Epoc32Ex\Basics\CommonFramework.

You can build and run this example either from the command prompt or from within an IDE. To create abld.bat , type:

bldmake bldfiles

To compile and link the project for the debug emulator, enter:

Then, to run the HelloWorldCon application, navigate to the folder that contains it ”for example, ...\Epoc32\release\wins\udeb and at the command prompt, type: HelloWorldCon

Alternatively, create the IDE project file (as described in Chapter 1), load and build the project from within the IDE. To run the console application you may have to specify the executable as HelloWorldCon.exe . The Series 60 emulator starts up, and the application will appear immediately as shown in Figure 2-4.

Note that HelloWorldCon starts up as the only application available. It displays "Hello World" and simply waits for any key press on the PC. Pressing any key will complete the application and close the emulator.

HelloWorldCon.mmp

The project definition ( .mmp ) file for console applications has a few key differences from the equivalent GUI project file as outlined here.

TARGET HelloWorldCon.exe TARGETTYPE exe UID 0 SOURCEPATH . SOURCE HelloWorldCon.cpp USERINCLUDE . USERINCLUDE \Epoc32ex\Basics\CommonFramework SYSTEMINCLUDE \Epoc32\include LIBRARY euser.lib

Note the name of the application executable and in particular its extension ( .exe ) as specified in the TARGET statement is HelloWorldCon.exe . The TARGETTYPE is exe and the UID line is set to zero, because UIDs are not required for .exe applications. A value of zero on the UID line will suppress a build tools warning. However, at install time supplying a nonzero UID has another very important effect ”it prevents one .exe replacing a previously installed one that also had a UID of zero ”see the section entitled Format of .pkg Files later in this chapter for more details.

None of the GUI libraries are required in the LIBRARY statement; only euser.lib is needed in this very simple example.

HelloWorldCon Emulator Executable Files

Under the Series 60 emulator the HelloWorldCon console application consists of a single executable file: HelloWorldCon.exe. It is generated in the \epoc32\release\wins\udeb folder for debug emulator builds and the \epoc32\release\wins\urel folder for release builds (emulator release builds are rarely created in practice). Under the emulator, these locations are essential for the correct execution of .exe files.

HelloWorldCon Target Executable Files

The HelloWorldCon console application built for a target hardware device consists of a single executable file: HelloWorldCon.exe . It is generated, on the PC, in the \epoc32\release\armi\urel for an armi release build (or \epoc32\release\thumb\urel for a thumb release build) ”the ARM build options for target devices are explained in Chapter 1.

On a target device, .exe executables would be located under a \system\programs folder by convention, but unlike .app programs, they can be run from any location ”in theory. The problem is that getting the .exe file onto a device, and then locating and launching this type of application on a Series 60 device, may not be straightforward. On most systems the target device's Messaging Inbox will recognize the Symbian OS executable ( .exe ) file format in an incoming message attachment, and may refuse to open the message and its attachments for security reasons.

It is not usual to supply .exe applications for installation by end users, but as a developer you may have legitimate reasons for wanting to do this. You could supply the .exe in a .sis file, but Series 60 does not automatically recognize and display an icon for .exe applications, so you still have the problem of launching the console application. There are two options:

• Install the executable, and select and launch it via a special utility application.

• Install the executable with an automatic launch by the installation process.

For the first option a GUI utility application called Exelauncher is provided to assist with this problem ”it is available as part of the example materials supplied online, as specified in the Preface.

You should package up the HelloWorldCon.exe application in an installation ( .sis ) file and then transfer it to the device from your PC via infrared or Bluetooth, followed by the .sis file for the Exelauncher utility. Read both messages and install both applications. Locate the Exelauncher icon and run it. You will then be presented with the option to select and launch the HelloWorldCon application. In order for Exelauncher to find the HelloWorldCon.exe file, it must be installed in c:\EMCC\Exes\ on the target device.

The second option has the disadvantage that it is a one-time operation, and the installation has to be repeated every time the application is to be run. All that is required to have the application run during the installation process is to specify one additional parameter ( FR ) after the name of the application file ( .exe ) in the .pkg installation package file. This process is shown later in this chapter under Running Executables During Installation , and the composition and use of .sis files is described in detail in the next section.

Everything required for building and running the HelloWorldCon project is supplied; including all of the source code, the installation system files, and the Exelauncher utility.