symbian os getting started v1 0 en

8/8/2019 Symbian OS Getting Started v1 0 En

http://slidepdf.com/reader/full/symbian-os-getting-started-v1-0-en 1/16



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 otherlicense 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




Forum.Nokia.com

Change History

November 21, 2003 Version 1.0 Initial document release




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 structureand 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, andpreemptive 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




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 writtento 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 areintroduced below.




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 includeMessaging, 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 pathwhere 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




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 islong; 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.




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.exeTARGETTYPE exeUID 0SOURCEPATH .SOURCE HelloWorld.cppUSERINCLUDE .

SYSTEMINCLUDE \Epoc32\includeLIBRARY 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




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.




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 thisLOCAL_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 objectconsole=Console::NewL(KTxtExampleCode,TSize(KConsFullScreen,KConsFull

Screen));CleanupStack::PushL(console);// printing the Hello world stringconsole->Printf(KHelloWorldText);// printing the press any key stringconsole->Printf(KTxtPressAnyKey);// get and ignore characterconsole->Getch();CleanupStack::PopAndDestroy(); // close console}

/* main function******************/TInt E32Main(){ __UHEAP_MARK;

CTrapCleanup* cleanup=CTrapCleanup::New(); // get clean-up stackTRAPD(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




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 ispresent 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\ .




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 developan application of type .app for Developer Platform 1.0 for Series 60.




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/symbianunder Getting Started

• Developer Platform 1.0 for Series 60: Getting Started with C++ Application Development






• Coding Idioms for Symbian OS C++ Programmers

http://www.forum.nokia.com/symbianunder 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


http://www.forum.nokia.com/symbian





http://www.symbian.com/


http://www.forum.nokia.com/series60

http://www.forum.nokia.com/series60


http://www.symbian.com/








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 compilingand 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.




Forum.Nokia.com

8 References

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