This section first describes the similarities and differences between S60 and UIQ platforms. It then moves on to examine what you need to develop an application on each, and what you need to know to start work.

Contents

• Symbian OS and the S60 and UIQ mobile phone platforms

• What you will need to start development

• SDK contents

• The emulator

• Compilers and IDEs

• Symbian OS development tools

Symbian OS has a flexible architecture which allows different mobile phone platforms to run on top of the core operating system. The two most widely of used of these are S60 (formerly known as Series 60) and UIQ, which are both discussed in this tutorial.

Platforms provides a graphical user interface (GUI) framework, applications which use it, such as messaging or calendar, and can supply additional application and middleware services.

The platforms are said to be open because, in addition to these built-in applications, a user may additionally install others such as games, enterprise applications, like push e-mail, or utilities. This tutorial explains the process of creating such distributable applications.

S60

The Nokia S60 platform is used in the majority of Symbian OS smartphones shipped to date. S60 has been designed for easy one-handed use. It does not have a touch screen but instead has various input keys, including two soft keys, a five-way navigator pad (4 ways plus a centre selection button), the number keys and several dedicated keys such as the menu key.

When programming for S60, since there is no touch screen, pointer events are not supported. Another consequence of having no touch screen input is that developer should consider the type of user input required. For example, in some situations it may be appropriate to replace a text entry box with a pre-filled list, from which a selection can be made.

Phones built on the S60 3rd Edition Platform have high quality, high-resolution colour screens. Possible layouts include:

• Double Resolution Portrait (352x416)

• Double Resolution Landscape (416x352)

• QVGA Portrait (240x320)

• QVGA Landscape (320x240)

• Low Resolution Portrait (176x208)

• Low Resolution Landscape (208x176)

UIQ

The UIQ Platform originates from a Symbian reference design and supports both keypad and touchscreen input (through virtual keyboard, handwriting recognition or interaction with typical UI controls). It can be configured with respect to touch/non-touch screens, screen size, the use of a menu bar or the use of soft keys.

Like S60, UIQ supports a range of screen sizes defined using a combination of four UI parameters called a UI Configuration. The parameters are:

Parameter Configuration options Screen layout Portrait (240x320) Landscape (320x240) Portrait Small (240x256) Landscape Small (256x240) Touch screen Yes or No Interaction style Menu or Soft key Orientation Normal or Inverted

When writing an application for either platform, you should make its style and user experience consistent with other applications so it is not confusing for a user. Both S60 and UIQ have style guide documents which you should consult before designing your application. By adhering to the "Look and Feel" guidelines, you will give your application the best chance of success amongst users of any particular platform or smartphone. The guides are also a good way to learn about the types of controls available and the UI techniques commonly used on each platform.

You will need

• a PC running Windows NT or better

• an SDK (S60 or UIQ)

• a C++ development IDE supported by your SDK.

• the appropriate phone handsets on which to test your application

• The ability to deploy code onto the phone (for example, a removable media card, for example, MMC or Memory Stick, or a connection between your development PC and the handset using USB or Bluetooth).

To install code which requires particular privileges, such as access to certain areas of the filesystem or to have high priority use of the multimedia hardware, you will also need a level of trust. The first step to attain this is to acquire an ACS Publisher ID. You can find more information about this requirement from the Application signing section of this tutorial and from Symbian Signed.

Finally, you will need to have some knowledge about C++ programming and the basic principles of object-oriented design. You do not necessarily need prior information about the S60 or UIQ Platforms, or extensive experience of working with Symbian OS. If this tutorial takes you ‘out of your depth’, there is a list of books and other Symbian OS resources in the Additional resources section at the end of this tutorial. You can also find an extensive glossary of Symbian OS terms in the Symbian OS Library.

Downloading the SDKs

Before you can build any of the code that accompanies this guide, you must have installed the appropriate SDK for the platform you wish to work with. These can be downloaded as follows:

For the UIQ platform - a UIQ 3.0 SDK for Symbian OS v9.1.

For the S60 platform - a S60 3rd Edition SDK

Each SDK provides the tools, libraries and application programming interfaces required to build C++ applications for handsets based on S60 or UIQ

Switching between the UIQ and S60 SDKs

There’s nothing to say that you can’t install both SDKs on the same PC. If you do so, you can switch between them by typing ‘devices’ at the command prompt. The command will list the SDKs installed on your PC – one of them will be marked as ‘default’. For example:

> devices

S60_3rd_Beta:com.nokia.series60

UIQ3:com.symbian.UIQ - default

To switch between them, and make the S60 SDK the default working SDK, you can use the devices command with the setdefault switch, passing in the SDK name. That is:

> devices –setdefault @S60_3rd_Beta:com.nokia.series60

Changing the default SDK using either technique sets up the build environment to point to the appropriate set of tools (so the correct commands are invoked) and identifies the root directory of the SDK (so that the correct include files and libraries are located).

NOTE: The names assigned to each SDK will change for different versions as they are released.

If you do plan to install both SDKs to write an application which will run on both platforms, you can’t use exactly the same code and expect it to run on both. The reason for this will be explained later in this tutorial which, after introducing the process for generic application development on Symbian OS, will describe the creation of an application for both S60 and UIQ, and describe the important differences between them.

The key elements of an SDK are:

• a Windows-based emulation of a phone. Programs are initially developed and tested on the emulator.

• header files and binary library files both for emulator development and for running the code on real ARM processor-based phones

• a GCC-based compiler for building for ARM-based targets

• additional tools for building and application deployment

• documentation (the Symbian OS Library) and examples

If you look at the directory into which you installed the SDK, you'll see a number of subdirectories and files. The following list gives a brief explanation of what each contains:

• Documentation\: On UIQ SDKs, Symbian OS and UIQ documentation.

• epoc32\: binaries and tools to support development, including emulator files, libraries, header files, and tools. The form of this directory is explained in detail in the following table.

  Directory Description BUILD Intermediate build files (makefiles, object code, project browsing information). This directory is created when a project is built. data Emulator configuration files. The files stored under the z subdirectory are combined with the \epoc32\release\winscw\udeb\z directory to make up the ROM drive for the emulator. See \release\ for more information. gcc GNU GCC toolchain required for various build utilities (this is not however the compiler now used for building application code). include UIQ or S60 and Symbian OS C++ system include files. localisation Localisable files. release This is where the executables will be placed when you build your project - build output files such as .exe or .dll are stored here. The directory has sub-directories for each build target. The armv5 and gcce directories contain files for ARM targets and winscw contains build output for the emulator. Each directory will have subdirectories for debug (udeb), and release (urel) builds. For emulator build targets, under udeb and urel there will be a subdirectory called z which contains the contents of the ROM drive for the emulator. For phone build targets, the release directory is used to store the executables before they are packaged into an install file for installation onto a phone. tools Windows-based SDK tools such as batch files, perl scripts, Windows, DOS and Java executables. winscw The emulated drives of the emulator (C:\ etc) are stored under here.

• examples\: generic Symbian OS example code. On UIQ SDKs, UIQ specific examples are contained in examples\UIQ.

• S60Doc: On S60 SDKs, S60 and Symbian OS documentation.

• S60Ex: On S60 SDKs, S60 example programs.

Once you’ve installed an SDK and familiarised yourself with its contents, it is worth taking some time to review the file layout of some of the example applications provided with each SDK. Besides getting accustomed to Symbian OS code, and the tools used to create, build and test it, it’s a good idea to use the examples to check that your SDK is correctly installed. For example, you may find it useful to take a look at the "Hello World!" example which comes with both the UIQ and S60 SDKs and experiment by

• modifying it to present a different message

• compiling and running the modified example on the emulator

• compiling the code and building an installation package to deploy it to an appropriate phone.

This tutorial will describe how to perform each of these steps, before moving on to a slightly more complex example than "Hello World!" which will examine common aspects of creating an application for S60 or UIQ and describe some of the differences.

The emulator is a Windows application which simulates the phone hardware on the PC. This enables the development of phone software to be substantially PC-based, with only the final development stages focussed on the hardware. Use of the emulator saves time in the early stages of development, since you can use the development IDE to debug the code easily and resolve most initial bugs and design problems. For example, if a panic occurs in your code, the debugger can provide comprehensive information to diagnose the error condition that caused it. Use of the emulator also reduces the number of times you need to create an installation package, transfer it to the phone and install it, which would otherwise be time consuming in the early phases of development.

The emulator provides as faithful an emulation as possible of Symbian OS running on target hardware, and has processes and scheduling that are almost identical to those on a real device. However, there are necessarily some differences, for example the memory model for a real phone is different to that of the emulator and the underlying hardware is different, so it is not possible to use the same device driver and hardware abstraction layer code on both the emulator and a real phone. For this reason, the emulator cannot be used for all development and, for low-level programming such as that for device drivers, target hardware cannot be emulated.

One of the differences between a phone handset and the emulator may be observed as a slight difference in the pixel sizes of each. Text may be displayed differently on the phone to the way it appears on the emulator. Another difference is that the emulator programming environment tends to be more forgiving than that of the target hardware. For example, code which uses non-constant static variables will compile for the emulator, but will not compile for the ARM platform. Sometimes code which may run successfully on the emulator will fail on the hardware.

To eliminate any issues that are caused by differences between the emulator and a real phone, all application code must be run and tested thoroughly on the phone itself as well as the emulator before it is released. You can find more detail in Deploying code on hardware.

The emulator is most commonly used as part of debugging a project, in which case it is usually started by using Run or Debug from within the IDE. On either platform, it can also be started from a command prompt by entering the command:

> epoc

EPOC was an earlier name for Symbian OS, and is used in various instances, such as in this executable name. The command runs a debug build of the emulator (epoc.exe, found in the SDK directory \epoc32\release\winscw\udeb), which is what you will normally work with, as it allows you to debug your programs through the IDE.

A new window should then appear showing an emulation of the phone’s display, plus a surround that includes some navigation and phone buttons. The S60 and UIQ SDKs each customise the display to mimic the smartphone types supported by that UI platform.

You'll find the emulator fairly straightforward to use. On both S60 and UIQ, you can use the PC’s mouse or the cursor keys and the enter key to navigate, and the keyboard and number pad to enter text. On UIQ, you can also click and draw on the screen with the PC's mouse, as if it were the stylus.

Additionally, the PC function keys are set to simulate certain hardware events (such as power on/off), and other special keyboard combinations provide options that are helpful for debugging, such as viewing and manipulating the memory heap and simulating rapid random keypresses to test application robustness. More information on the use of the debugging keys can be found in the Symbian OS Library in the Debug facilities section of the emulator guide.

The filesystem of the phone is mapped to the PC, with the internal writable drive (C:) usually mapped to \epoc32\winscw\c and the ROM mapped to \epoc32\release\winscw\udeb\z for the debug build. You can also add further virtual drives, and reconfigure the standard drives to map to alternative locations.

There is one exception to the filesystem mapping, which is the location of the executables. On the phone, all executables are stored in the \sys\bin directory, but on the emulator, the executables are loaded from where they are built, that is, the \epoc32\release\winscw\udeb or \epoc32\release\winscw\urel directory.

For example, a program called helloworld.exe, built into the phone's ROM, will be stored in z:\sys\bin or, if it is installed onto the phone's internal drive will be located at c:\sys\bin (other drives can map to the phone's removable memory card). For the same application on the emulator, helloworld.exe will always be stored in \epoc32\release\winscw\udeb or \epoc32\release\winscw\urel for debug or release builds respectively.

A more detailed description of the typical Symbian OS file locations for both the emulator and phone can be found in a section of the File Server guide within the Symbian OS Library.

Some programs, such as test programs, don't require the full GUI to start up, and instead run inside a simple text console. This is useful for automated testing, for example, to check for code regressions by running a suite of console tests after each build. The code required for a console test application is described in The filesystem browser engine class and console test code. You can also experiment with the test console by running eshell, which provides a simple text shell.

Emulator know-how

The UIQ SDK includes a configuration tool called UiqEnv to help set up the emulator environment for various UI styles, determine which communication ports to use and to provide connectivity through the PC. For example, to change to the pen style UI configuration, call the following on the command line, before starting the emulator:

uiqenv -ui pen

To switch to the soft key style UI configuration, call the following:

uiqenv -ui softkey

More information about UIQEnv can be found in the UIQ SDK.

The S60 emulator can also be configured using the Tools menu on the emulator itself. The Preferences option allows configuration of a number of global emulator settings and network connectivity. More information is available from the S60 SDK, in the S60 Tools and Utilities Emulator Guide.

Comms setup

An application running on a smartphone will have access to various communication technologies. These can be emulated by attaching suitable hardware to a comms port on the PC, and making any necessary configuration changes.

Infra red

To use infrared, connect an IrDA COM-port serial adapter (or "pod"). Pods supported by the Symbian OS IrDA stack include: Extended Systems, Inc. Jeteye pods 7201, 7401 and 7501, iFoundry 8001A, Actisys 220L, Actisys 220L+, Actisys 220Li.

By default, the emulator looks for an infra-red device on COM port 2.

Bluetooth

Connect a Bluetooth module to the PC. The currently supported module is the Casira. The default port is COM1.

Telephony data calls

If you need genuine telephony protocols, such as SMS, you can connect a data-enabled mobile phone (as specified in the Knowledgebase entry What telephony hardware does Symbian use for testing the IP connectivity of the OS?) to the emulator via a COM port.

If you want to use TCP/IP (as if over a data call), a connected phone can be used, although most developers prefer, for convenience, and to avoid call costs, to instead set up the emulator to use the PC's own network connection. Both S60 and UIQ emulators are set up to enable this.

You can use the S60 and UIQ SDKs' set up utilities to configure Bluetooth, infrared, and network settings. For S60, use Tools | Preferences from the emulator; for UIQ, use the SDK Configurator program.

The emulator configuration file

The emulator can be configured through an initialisation file called epoc.ini located in \epoc32\data, which is where all configuration files are stored for the emulator. For normal use, you don’t to need modify epoc.ini, but you can make changes to customise it if you need to, for example, to add customised virtual drives, change the size of the heap or map hot keys on the PC keyboard to the phone keypad. If you do make changes to epoc.ini, it’s advisable to keep a back-up copy in case you need to revert your changes.

More information about the keywords supported by epoc.ini can be found in the Emulator reference in the Symbian OS Library.

Platform security configuration

Platform security is discussed in more detail later in this tutorial in Platform security and platform migration. The Platform security settings for the emulator can be configured by adding statements to epoc.ini. This can be useful in the early stages of development, for example, to suspend platform security checking. The default setting for the emulator (and, of course, for all phone hardware) is that platform security is fully enabled and enforced.

The flags to use in epoc.ini are described in detail in the Platform security section of the epoc.ini reference in the Symbian OS Library. The configuration options include:

• PlatSecEnforcement [On | Off]

  for switching off platform security policy enforcement so the system behaves as if all security checks have passed

• PlatSecDisabledCaps <capability> + <capability> + ...

  for switching off the checking of certain capabilities

• PlatSecDiagnostics [On | Off]

  for logging platform security diagnostic messages to the debug log file.

Platform security messages, among others, are written to the emulator’s debug log file which is described in more detail in the emulator debugging section later in this tutorial.

This section examines the compilers and IDEs that you can use when developing applications for Symbian OS.

CodeWarrior for Symbian OS

CodeWarrior for Symbian OS, which comes in several packages (personal, professional and OEM editions), supports C++ development on Symbian OS. The IDE integrates compilation for both emulator (using its own compiler) and hardware builds (using one of the hardware ‘cross’ compilers supported for Symbian OS), emulator debugging and, additionally, hardware debugging with the OEM package. More information is available from CodeWarrior for Symbian OS.

The GCC-E target compiler

To build binaries to run on phone hardware, which has an ARM processor rather than the Intel (or compatible) x86 processors used on PCs, different compilation tools are required. Such a compiler, GCC-E, is supplied free with the SDK and is taken from the free software GNU GCC. GCC-E can be used as either from the command line or invoked an IDE. You can find more information in the Native build targets section in the Symbian OS Library.

The RVCT target compiler

GCC-E supports the same Embedded Application Binary Interface (EABI) as the ARM Real View Compilation Tool (RVCT, version 2.2 or higher). RVCT is used by Symbian to compile Symbian OS and by S60 and UIQ licensees to develop ROM-based code. It gives the best performance and smallest code compared to other alternatives, but must be purchased separately. Like GCC-E, RVCT can be used as either from the command line or invoked from within the CodeWarrior IDE.

Carbide.c++ IDE

Nokia are releasing a suite of new developer tools for Symbian OS application development, called Carbide.C++, in 2006. Based upon Eclipse, the rapidly evolving Java-based open-source integrated development environment (IDE), the tools family contains three products:

Carbide.c++ Express

A free IDE with basic build and debug support for SDK platforms. This product will be suitable for phone and emulator target compilation and emulator debug.

Carbide.c++ Developer Edition

For more advanced application developers, this will include a new graphical Rapid Application Development (RAD) tool and support compilation and debugging for both emulator and phone targets.

Carbide.c++ Professional Edition

This product will be available to OEM developers who create phones and require early access to next-generation Symbian technical specifications and a low level hardware debugging facility.

More information about the Carbide.c++ family is available at Forum Nokia.

Microsoft Visual Studio .NET 2003 IDE using Carbide.vs

Carbide.vs (which was formerly known as Nokia Developer's Suite for Symbian OS) 2.0 is a set of tools to allow Symbian OS C++ application development using Microsoft Visual Studio .NET 2003. It can be used with the S60 Platform 2nd Edition and 3rd Edition, or the Series 80 Platform 2nd Edition. More information can be found at Forum Nokia.

The kits supply tools that allow projects to be built from the command line. This is not as easy as using the IDE to control a build, but it does allow for building from batch processes, such as automatic build and test scripts. The following table summarises the command line tools, most of which will be discussed further in the Building, debugging and deploying an application section of this tutorial.

Tool Description abld Build tool used to control all aspects of building a project. It is created in the current directory by the bldmake tool from a component description file—bld.inf. For a command line reference, see the abld command syntax. abld invokes the resource compiler and bitmap converter, described below. bldmake Build tool that processes the component description file (bld.inf) in the current directory and generates the batch file abld and several build batch makefiles (.make). For command line reference, see the Bldmake command syntax. bmconv Bitmap converter that takes one or more Windows bitmap files (.bmp) and generates a single Symbian OS multi-bitmap file (.mbm). For command line syntax, see the Bitmap converter syntax. cshlpcmp Context sensitive help compiler that builds .hlp help files using information defined in a project file, .rtf source file or files, and an optional customisation file. For command line reference, see the CS Help Compiler. cshlpcmp_gui is a GUI for this compiler (not used in S60). epocrc Combines the actions of passing a resource file through the C++ preprocessor, and then compiling it with rcomp. For command line reference, see Resource builder tool: epocrc. createSIS The createSIS tool creates and signs software installation packages (SIS files). It provides a wrapper around lower level installation tools such as makesis and makekeys. makeSIS Installation File Generator that creates software installation packages based on source PC/target Symbian OS file locations defined in a .pkg package file. For command line reference, see the Installation File Generator syntax. makekeys Certification Generator that creates a private/public key pair and issues certificate requests. For a command line reference, see the Certification Generator syntax. makmake Build tool that takes a .mmp project file which lists the components of the project, and produces a makefile. Uses GNU cpp to evaluate dependencies. Generated headers from resource compilation and multi-bitmap compilation, etc., should be available before makmake is run. For a command line reference, see the makmake command syntax. petran For Portable Executable Translation. The petran tool converts executables from Portable Executable format (the standard format for executable and object files) to the Symbian OS executable format. It is invoked at the final stage of the build process for ARM targets. rcomp Resource compiler that compiles source (.rss) resource files into a resource data file (default extension .rsc) which can be used by applications, and a resource header file (.rsg). The operation of the resource compiler is usually wrapped in an abld batch file. For command line reference, see the Resource compiler syntax.