Professional Symbian Programming: Mobile Solutions on the EPOC Platform

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

4

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

SDKs and Tools for Application Development .................................................................................... 7 4.1

4.2

5

Directory Structure of an Installed SDK .............................................................................................7 4.1.1

The root directory..................................................................................................................7

4.1.2

Epoc32\......................................................................................................................................8

4.1.3

Epoc32Ex\ .................................................................................................................................9

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

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

Symbian OS: Getting Started with C++ Application Development

Initial document release

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 OSbased 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 TARGETTYPE UID SOURCEPATH SOURCE USERINCLUDE SYSTEMINCLUDE LIBRARY 4.2.2

HelloWorld.exe exe 0 . HelloWorld.cpp . \Epoc32\include euser.lib bafl.lib efsrv.lib

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