F O R U M N O K I A

Symbian OS: Getting Started with C++

Application Development
Version 1.0; November 21, 2003

Symbian OS
 Forum.Nokia.com

Copyright © 2003 Nokia Corporation. All rights reserved.

Nokia and Nokia Connecting People are registered trademarks of Nokia Corporation. Java and all Java-based
marks are trademarks or registered trademarks of Sun Microsystems, Inc. Other product and company names
mentioned herein may be trademarks or trade names of their respective owners.

Disclaimer
The information in this document is provided “as is,” with no warranties whatsoever, including any warranty of
merchantability, fitness for any particular purpose, or any warranty otherwise arising out of any proposal,
specification, or sample. Furthermore, information provided in this document is preliminary, and may be changed
substantially prior to final release. This document is provided for informational purposes only.
Nokia Corporation disclaims all liability, including liability for infringement of any proprietary rights, relating to
implementation of information presented in this document. Nokia Corporation does not warrant or represent
that such use will not infringe such rights.
Nokia Corporation retains the right to make changes to this specification at any time, without notice.

License
A license is hereby granted to download and print a copy of this specification for personal use only. No other
license to any other intellectual property rights is granted herein.

Symbian OS: Getting Started with C++ Application Development 2

 Forum.Nokia.com

Contents

1 Overview ..................................................................................................................................................... 5
2 What You Should Know ........................................................................................................................... 5
3 The Symbian OS Platform and Application Development............................................................... 5
3.1 Kernel and User Library ..........................................................................................................................5
3.2 Files and Directories ................................................................................................................................5
3.3 Target Platforms and Variants .............................................................................................................6
3.4 Symbian OS Target Types ......................................................................................................................6
4 SDKs and Tools for Application Development .................................................................................... 7
4.1 Directory Structure of an Installed SDK .............................................................................................7
4.1.1 The root directory..................................................................................................................7
4.1.2 Epoc32\......................................................................................................................................8
4.1.3 Epoc32Ex\ .................................................................................................................................9
4.2 Application Build Tools...........................................................................................................................9
4.2.1 The project definition file....................................................................................................9
4.2.2 The component description file (bld.inf) .......................................................................9
4.2.3 The bldmake command.................................................................................................... 10
5 Step-by-Step Guide..................................................................................................................................11
5.1 Console Application .............................................................................................................................. 11
5.2 Basic Source Files................................................................................................................................... 11
5.3 Building the Application ..................................................................................................................... 11
5.4 Running the Application ..................................................................................................................... 12
6 Where to Go Next.....................................................................................................................................14
7 Terms and Abbreviations ......................................................................................................................15
8 References .................................................................................................................................................16

Symbian OS: Getting Started with C++ Application Development 3

 Forum.Nokia.com

Change History

November 21, 2003 Version 1.0 Initial document release

Symbian OS: Getting Started with C++ Application Development 4

 Forum.Nokia.com

1 Overview
This document provides an introduction to Symbian OS application development with the C++
programming language. It does not, however, refer to any specific Software Development Kits (SDKs).
Rather, it describes the key components of the Symbian OS platform and the conventional structure
and tools that are required in any product’s SDK for Symbian OS.

2 What You Should Know

A good background for getting started with developing native applications for Symbian OS is
knowledge of C++ programming techniques and object-oriented design principles. Familiarity with
EPOC (a previous name for the Symbian Operating System) Release 5, the platform that runs in Psion
Series 5 handheld devices, will also be helpful. EPOC Release 5 is often abbreviated and simply referred
to as ER5.

All beginners should read the very first book about Symbian OS, Professional Symbian Programming –
Mobile Solutions on the EPOC Platform (ISBN – 1-861003-03-X).

3 The Symbian OS Platform and Application Development

The Symbian OS platform was previously known as the EPOC platform (for example, EPOC release 5 or
ER5). Although the name of the system has been changed, the term EPOC still appears in many places,
such as in the structure of directories of an installed SDK for Symbian OS (Epoc32\), or even in some
documents. Most of the components added to the platform have the prefix "E", which stands for EPOC,
e.g., ESOCK means EPOC Socket and ETEL means EPOC Telephony.

3.1 Kernel and User Library

Built on 32-bit code base, the Symbian OS platform offers a number of key features that have a
significant impact on mobile application development. First of all, Symbian OS is a true microkernel
with highly object-oriented design and preemptive multitasking. The kernel runs in privileged mode;
it has access to the entire memory space.

The process is a unit of protection in Symbian OS. Each process has its own virtual address space. The
kernel assumes the existence of a Memory Management Unit (MMU), which is responsible for
translating virtual addresses. The thread is a unit of execution in Symbian OS. A process has one or
more threads.

The EUser library provides a large set of services to user mode programs. Commonly used services
include exception handling, descriptors, memory management, client/server framework, and
preemptive and cooperative multitasking through active objects.

Active objects are widely used in Symbian OS. They provide an efficient mechanism for multitasking
without the need for an expensive context switch. Each active object is given a task to complete. Each
thread has an active scheduler, which is responsible for running a waiting active object. A thread may
contain one running active object and many active objects waiting to be run. Unlike multi-tasking
with threads, once an active object has started to run, it cannot be pre-empted by another active
object.

3.2 Files and Directories

In a Symbian OS-based device, files and programs are stored in either RAM or ROM memory.
Conventionally, on a target device, the Z: drive represents the ROM and the C: drive is part of the

Symbian OS: Getting Started with C++ Application Development 5

 Forum.Nokia.com

available RAM memory space. A Symbian OS-based device ROM comes pre-installed with numerous
programs and files. Third party programs and files are typically installed on to the C: drive.

Under the emulator environment, drives are mapped onto the Windows directories, where the Z: and
C: drives are emulated from \epoc32\release\wins\variant\z and \epoc32\wins\c
respectively. Variants are described in the following section. The role of Z: drive and C: drive is
different on the emulator. On the target device, the z: drive is the ROM drive so no data can be written
to it and neither can a third-party program be installed to it. However, the emulator has no such
restrictions and in practice, third party programs are by default, installed to z: drive.

Each drive contains two standard directories, \System and \Document at the root level. The
\System path is used for system files while the \Document path is mainly for user files. There are
several subdirectories within the \System directory, each devoted to some particular usage:

\System\Libs: Location for system shared libraries (.DLLs, .LDDs, etc.)

\System\Data: Location for system shared data (e.g., calendar database, contact database, dll
resource files, etc.)

\System\Apps: Location for application programs

\System\Apps\AppName\AppName.app: Each application is stored within its own subdirectory

named with the exact application’s name

3.3 Target Platforms and Variants

Applications can be built for different target platforms, to serve different purposes. There are two
main target platforms written in short terms as WINS and MARM, where WINS denotes a Windows
Single process platform running under an emulator within the Windows environment, and MARM
means a Multiprocess ARM platform running in a real target device. In addition, the WINC platform is a
target build for Windows Connectivity application engines.

Under Symbian OS v6.0 and later releases, the MARM target is no longer supported. Instead, it has been
expanded to ARMI, ARM4, and THUMB. The ARM7 and ARM9 processors support two instruction sets –
ARM4 and THUMB. ARM4 uses 32-bit instructions, which generally results in faster code. THUMB uses
16-bit instructions, which generally results in a smaller, on-disk footprint, but slower execution. ARM4
compiled code cannot be linked with THUMB compiled code, and vice versa. Code compiled for ARMI
can be linked against THUMB or ARM4 compiled code. For a third-party developer, ARMI is the safest
choice when building for the target device.

Each platform may provide two variants: udeb and urel for programs debugging and for release
mode, respectively. Both udeb and urel are Unicode builds (u denotes Unicode and deb indicates
debug). In the days when Symbian OS supported only narrow builds, these variants were seen as deb
and rel.

Although the code may be 100 percent identical, applications that are built for the WINS platform
cannot run on an ARM-processor target device.

3.4 Symbian OS Target Types

Symbian OS defines a number of different ways source code can be built, in other words, the target
type of the compiled binaries. The target type of a software component is defined by its requirements.
For example, if the software component requires a separate single process and does not require a
user interface, it could be implemented as a .exe. The target type for a software component is defined
within its .mmp file (see Section 4.2.1, "The project definition file"). Some important target types are
introduced below.

Symbian OS: Getting Started with C++ Application Development 6

 Forum.Nokia.com

EXE (.exe) – A program with a single main entry point E32Main(). If an EXE has a user interface, it is
limited to a console window. When an exe is launched, the system creates a new process and within
it a new thread. Some examples include Console programs and EPOC servers.

Dynamic Link Library (.dll) – A library of program code with multiple entry points. DLLs are loaded by
other programs and exist within the context of that program’s thread. There are two types of DLL:
static interface and polymorphic interface. DLLs with a static interface export a table of methods,
which can be linked against by specifying the import library at the link step. Static interface examples
include euser.dll and cone.dll. DLLs with a polymorphic interface usually export a single method at a
well-known entry point. For example, all GUI applications export a NewApplication() method,
which, when called, starts the application.

Application (.app) – Programs with a user interface. As mentioned previously, applications are
implemented as polymorphic interface DLLs. Each application runs within a separate process, with its
own virtual address space. Applications generally provide an Application Information File (.aif), which
can contain an application’s icons, support for multiple languages, and the list of supported MIME
types. Applications also own resource files, which contain localizable strings, menu items, dialog
definitions, etc. In order to aid portability, application developers are encouraged to design their
applications in two parts: application engine and application UI. Some application examples include
Messaging, Contacts, and Calendar.

4 SDKs and Tools for Application Development

To start developing applications for a particular Symbian OS-based device, you need to install a
product-specific SDK, normally provided by the device manufacturer. For example, the Nokia 9210
Communicator runs Symbian OS v6.0; the Nokia 9200 Communicator series SDK is provided by Nokia to
help third-party developers develop add-on applications for the Nokia 9200 Communicator series. The
SDK includes an emulator for testing applications in the Windows environment during the
development phase. Other tools, such as a bitmap converter, Application Information File (AIF) builder,
build scripts, etc., are also included in the SDK.

4.1 Directory Structure of an Installed SDK

Symbian OS SDKs share a common directory structure. The following sections list some of the most
commonly used directories and their associated functions.

4.1.1 The root directory

The root directory is a path to a Symbian OS SDK installed in a local PC. All necessary tool components,
developer libraries, and information about the SDK are stored in subdirectories under this root. The
whole path leading to this root directory must be declared to the Windows system via the
Environment Variables settings. The variable name is EPOCROOT and the variable value is the full path
where a Symbian OS SDK is installed in the Windows system. Figure 1 illustrates the declaration of the
Nokia 9200 Communicator series SDK to be installed in the Windows 2000 system.

Figure 1: Declare the root directory to Windows system via Windows Environment Variables settings

Symbian OS: Getting Started with C++ Application Development 7

 Forum.Nokia.com

4.1.2 Epoc32\

Under the root directory, Epoc32\ is the path to other subdirectories where header files and libraries
for different target platforms are stored.

4.1.2.1 Epoc32\include\

All of the system’s include headers are found from here. This path must be declared in a project .mmp
file in order to avoid failure from compiling a project (see Section 4.2.1, "The project definition file").

4.1.2.2 Epoc32\release\

There are five different platform builds under the release\ subdirectory, as listed below:

wins\: Build target for an emulator; a single process environment running in a PC

armi\: Build target for ARM processor-based hardware; recommended for third-party developers

arm4\: Build target for ARM processor-based hardware; binaries are optimized for performance

thumb\: Build target for ARM processor-based hardware; binaries have a smaller on-disk footprint

winc\: Special build for Symbian tools and connectivity applications

Each build may provide utilities libraries for different variants: for release mode under urel\ or for
debug mode under udeb\ subdirectory. The most typical platform builds to be used by a third-party
developer are ARMI and WINS, for a target device and the WINS emulator, respectively.

From each build variant under the epoc32\release\wins\ directory, you can find the z
subdirectory. When running the emulator, this subdirectory will be mapped to emulate the drive Z: ,
and the emulator treats this drive as the ROM of a target device.

4.1.2.3 Epoc32\wins\

You can find the c subdirectory under the wins\ directory. When the emulator is run, the c
subdirectory is mapped to emulate the drive C: , where the Symbian OS system and Symbian OS-
based applications can store their data. The emulator treats this drive as the RAM of a target machine.

4.1.2.4 Epoc32\build\

Created by the bldmake tool, \epoc32\build\ is followed by a dynamic path, where project control
files and intermediate files for Microsoft Visual C++ are stored. Normally the full path to a project is
long; for example, when an example project is built under the Epoc32Ex\ subdirectory, the full path
after build\ starts from the root directory and ends with the directory that contains the project
.mmp file.

Symbian OS: Getting Started with C++ Application Development 8

 Forum.Nokia.com

Figure 2: MENUITEMS project control files are stored within the WINS subdirectory, and project
intermediate files are stored under the UDEB subdirectory.

4.1.3 Epoc32Ex\

Most Symbian OS SDKs also provide a number of sample applications. Essential example programs
with source code are good assets for beginners.

4.2 Application Build Tools

In addition to source files such as .cpp and .h, Symbian OS projects minimally require a project
definition file and a component description file (bld.inf). These additional files are required to define
your project in a platform- and compiler-independent fashion.

4.2.1 The project definition file

The project definition file is used by the bldmake tool to generate platform-specific makefiles. A
project definition file has the file extension .mmp. The file name should match the name of the target
software component. In the following example, the target software component is named
HelloWorld.exe, therefore the project definition file is named HelloWorld.mmp.

// HelloWorld.mmp
TARGET HelloWorld.exe
TARGETTYPE exe
UID 0
SOURCEPATH .
SOURCE HelloWorld.cpp
USERINCLUDE .
SYSTEMINCLUDE \Epoc32\include
LIBRARY euser.lib bafl.lib efsrv.lib

4.2.2 The component description file (bld.inf)

Regardless of the project, the component description file is always called bld.inf. Bld.inf specifies a list
of one or more project definition files (.mmp).

// Component description file

PRJ_MMPFILES
HelloWorld.mmp

Symbian OS: Getting Started with C++ Application Development 9

 Forum.Nokia.com

4.2.3 The bldmake command

The bldmake command processes the component description file (bld.inf) in the current directory and
generates the batch file abld.bat, along with several other makefiles within the \epoc32\build\ project
directory. Typically the command bldmake bldfiles is called once at the start of a new project and
every time bld.inf is modified.

Symbian OS: Getting Started with C++ Application Development 10

 Forum.Nokia.com

5 Step-by-Step Guide

5.1 Console Application

A simple console application such as the HelloWorld example implemented below should work on
most Symbian OS devices. In Symbian OS, console applications are not a common application type for
user programs.

5.2 Basic Source Files

#include <e32base.h>
#include <e32cons.h>
_LIT(KTxtEPOC32EX,"EPOC32EX");
_LIT(KTxtExampleCode,"E32 SDK Example Code");
_LIT(KFormatFailed,"failed: panic code=%d");
_LIT(KTxtOK,"ok");
_LIT(KTxtPressAnyKey," [press any key]");
LOCAL_D CConsoleBase* console; // write all your messages to this
LOCAL_C void doExampleL(); // code this function for the real example
/* function to perform the printing
*************************************/
LOCAL_C void doExampleL()
{
_LIT(KHelloWorldText,"Hello world!\n");
// create the console object
console=Console::NewL(KTxtExampleCode,TSize(KConsFullScreen,KConsFull
Screen));
CleanupStack::PushL(console);
// printing the Hello world string
console->Printf(KHelloWorldText);
// printing the press any key string
console->Printf(KTxtPressAnyKey);
// get and ignore character
console->Getch();
CleanupStack::PopAndDestroy(); // close console
}

/* main function
******************/
TInt E32Main()
{
__UHEAP_MARK;
CTrapCleanup* cleanup=CTrapCleanup::New(); // get clean-up stack
TRAPD(error,doExampleL()); // more initialization, then do example
__ASSERT_ALWAYS(!error,User::Panic(KFormatFailed,error));
delete cleanup; // destroy clean-up stack
__UHEAP_MARKEND;
return 0;
}

5.3 Building the Application

There are two alternative ways to build applications for Symbian OS. The first option is to use
command line build tools at the DOS prompt. With this method, an application can be built for all
target platforms supported by the SDK (ARM4 and THUMB are not always supported in some SDKs). The
second option is to use the Microsoft Visual Studio compiler. This method is preferable since the tool
provides a code editor and the compiler is integrated into the GUI program to help the developing

Symbian OS: Getting Started with C++ Application Development 11

 Forum.Nokia.com

process be more visual and make it easier to trace out, line by line, possible incorrect code. However,
Microsoft Visual Studio mostly compiles Symbian OS applications for the WINS platform for debugging
purposes. For target platforms such as armi and thumb, command line build tools must be used.

To build an application using command line tools:

• Go to the subdirectory, where the project file .mmp file is located. Make sure that the bld.inf file is
present in the same location.
• Run bldmake bldfiles. This command will produce a batch file named abld.bat, which contains
the project’s information defined from the project file .mmp.

Note: This build command line must be rerun every time the project file .mmp is updated with new
information, such as adding a linking library or changing the application UID.
• Run abld build wins udeb. This command will build a Unicode version with debug information of
the for the WINS platform.
• Run abld build armi urel. This command will build a Unicode release version of the application
for the target device.
• After the exe is built, the exe is copied into Epoc32\release\wins\udeb\.

The following steps shows how to build a project file for Microsoft Visual C++ and how to build an
application for the WINS platform using the Microsoft Visual C++ compiler:
• Go to the subdirectory where the project file .mmp file is located. Make sure that the bld.inf file is
present in the same location.
• Run bldmake bldfiles. This command will produce a batch file named abld.bat, which contains
the project’s information defined from the project file .mmp.

Note: This build command line must be rerun every time the project file .mmp is updated with new
information, such as adding a linking library or changing the application UID.
• Run abld makefile vc6. This command will produce project and workspace files (.dsp and
.dsw). These files can be used in Visual C++ 6.0.
• Run Microsoft Visual C++ 6.0 and select Open Workspace from the File menu.
• Make sure the Files of type list box is set to Projects (.dsw). Browse in Look in to find the
subdirectory WINS\, where the project file .dsw is located (see Section 4.1.2.4, "Epoc32\build\").
• Locate and open the .dsw for the application.
• Select the Build menu of Visual C++ and click the Build or Rebuild All item to build the
application.

5.4 Running the Application

Once the console application has been built, it is ready to be run firstly on the emulator and
subsequently on hardware. In this document, we will only consider running the console application on
the Emulator. For information on how to run an application on a specific target device, please refer to
the Getting Started with C++ development document for the chosen target platform.

Just like there are two ways to build an application, there are two ways to run an application on the
Emulator. You can run your application either from the command line or from within Microsoft Visual
C++ 6.0.

To run your console application using the command line tools:

• After the exe is built, the helloworld.exe is copied directly into
Epoc32\release\wins\udeb\.

Symbian OS: Getting Started with C++ Application Development 12

 Forum.Nokia.com

• Since the built application is of type exe, it can be run directly. Go to the sub-directory
Epoc32\release\wins\udeb\ and run helloworld.

The following steps show how to run the console application using Microsoft Visual C++ 6.0.
• In Microsoft Visual C++ 6.0 application, Select the Build menu and click on Execute
HELLOWORLD.exe item.

Both of the above methods will result in an emulator window being launched and helloworld.exe
being run. After a few seconds, you will see a blue emulator screen similar to the one shown in Figure
3.

Figure 3: Screenshot of Helloworld.exe running on Developer Platform 2.0 for Series 60 Emulator.

Note: Applications targeted to specific Developer Platforms, of types other than .exe are discussed in
Getting Started with C++ development documents specific to those platforms. For example, Developer
Platform 1.0 for Series 60: Getting Started with C++ Application Development explains how to develop
an application of type .app for Developer Platform 1.0 for Series 60.

Symbian OS: Getting Started with C++ Application Development 13

 Forum.Nokia.com

6 Where to Go Next
For the further information:
• Nokia 9200 Communicator Series: Getting Started with C++ Application Development
http://www.forum.nokia.com/symbian under Getting Started
• Developer Platform 1.0 for Series 60: Getting Started with C++ Application Development
http://www.forum.nokia.com/symbian under Getting Started
• Developer Platform 2.0 for Series 60: Getting Started with C++ Application Development
http://www.forum.nokia.com/symbian under Getting Started
• Developer Platform 2.0 for Series 90: Getting Started with C++ Application Development
http://www.forum.nokia.com/symbian under Getting Started
• Coding Idioms for Symbian OS C++ Programmers
http://www.forum.nokia.com/symbian under Documents
• Browse the Symbian Web site http://www.symbian.com/
• Browse the Symbian section at the Forum Nokia Web site http://www.forum.nokia.com/symbian
• Browse the Series 60 section at the Forum Nokia Web site http://www.forum.nokia.com/series60

Symbian OS: Getting Started with C++ Application Development 14

 Forum.Nokia.com

7 Terms and Abbreviations

Term or Abbreviation Meaning

ARM ARM processor.
ARMI ARM instruction set. The ARMI instruction set allows interworking
between the ARM4 and THUMB instruction sets by providing an extra
instruction that will allow swapping between sets.
ARM4 ARM 32-bit instruction set.
CONE Control Environment.
GUI Graphical User Interface.
IDE Integrated Development Environment. A system for supporting the
process of writing software, including a syntax-directed editor,
graphical tools for program entry, and integrated support for compiling
and running the program and relating compilation errors back to the
source, e.g., Visual C++.
SDK Software Development Kit. Set of programming tools for creating
applications and enhancing the use of certain software.
THUMB ARM 16-bit instruction set.
UID Unique Identifier. A globally unique 32-bit number used in a compound
identifier to uniquely identify an object, file type, etc.
WINC An implementation of the non-GUI parts of Symbian OS. Its chief
purpose is to allow Symbian OS application engines to be used to access
application documents from programs running on a PC.
WINS The target platform for the Microsoft Windows-hosted emulator.

Symbian OS: Getting Started with C++ Application Development 15

 Forum.Nokia.com

8 References
Professional Symbian Programming – Mobile Solutions on the EPOC Platform (ISBN – 1-861003-03-X).

Symbian OS: Getting Started with C++ Application Development 16