free study activity fall 2006 day 3 – symbian...

http://mobiledevices.kom.aau.dk/

Mobile Phone ProgrammingMobile Phone Programming

Free Study ActivityFall 2006

Day 3 – Symbian OS


DAY3 DAY3 -- SymbianSymbian 2

Overview of this courseOverview of this course

» Module C - Symbian» 2 Days 9-12 and 14-17» Interested persons can borrow a mobile

phone (Nokia N70) for the duration of the course or to do the exam.

» ECTS points will be awarded from level of commitment and by a final test (write your own application in the programming language of the course you took).



Goal for this courseGoal for this course

» Learn enough about Symbian– To judge whether it is the right choice for a project.– To quickly start application development in

Symbian C++» Understand basic concepts of the Symbian

OS and Symbian C++.



AgendaAgenda

» Symbian OS Introduction– Why Symbian?– Overview– Development considerations– UI Platforms

• Series 60/80/90, UIQ etc.



AgendaAgenda

» Development for S60– Available IDE’s– Getting the SDK and using the Carbide.c++ IDE– Getting Help

» Symbian Fundamentals



Why Symbian?Why Symbian?

» Why are we here?– Symbian OS runs on ~75% of all smartphones

• Nokia expects the smartphone market to exceed 250 million units in 2008

• 82.8 million cumulative Symbian OS phone shipments since the formation of Symbian (as of Q2 2006).

– Symbian C++ gives• Maximum flexibility• Speed



Why Symbian?Why Symbian?



Why Symbian?Why Symbian?» Licence owners



OverviewOverview» Runs on battery powered devices

– has low power consumption

» Designed for devices with limited memory» Open Operating System

– 3rd party developers can write applications

» Reliable and stable– Applications can run for years without being closed or losing

user data

» Object Orientated from the “ground up”– Provides a C++ API

» Micro/nano kernel architecture



Development considerationsDevelopment considerations

» Native language Symbian C++– Writing of Epoc32 ER1 begins: September 1994– Psion Series 5 PDA ships containing the first

release of the Symbian OS in a product: June 1997

– ISO/IEC publication of the C++ standard: September 1998

» Thus Symbian does not support standard C++ features.




» Designed for devices with limited resources– E.g. Battery, CPU, Memory. – Example device: Nokia N70.

• 32 bit CPU 220 MHz (ARM).• C: Flash drive for our applications 20MB.• Z: ROM stores the OS and built in middleware and

applications. • RAM ~30MB free after boot (this is quite good).• Symbian OS v8.1a • S60 2nd Edition, Feature Pack 3




» Older models even fewer resources

Source: http://www.allaboutsymbian.com




» Limited resources results in:– Active Object Framework, Descriptors etc.

» Different screen sizes.» Numeric keyboard, pen based input, other..» Device specific capabilities.» The manufacture adjust the UI layer to match

the capabilities of their device.



Platforms: Series 60/80/90, UIQ etcPlatforms: Series 60/80/90, UIQ etc

» Series 60/80/90 (forum.nokia.com or s60.com) – Nokia, Simens, Sendo, Panasonic, Samsung, LG, Lenovo

» UIQ (uiq.com)– Sony Ericsson, BenQ, Motorola, Arima

» What’s the difference:– The base system is the same.– Main difference is the UI layer.



Platforms: Series 60/80/90, UIQ etcPlatforms: Series 60/80/90, UIQ etc» We can use a common code base.

Source: www.forum.nokia.com



Development for S60Development for S60

» Todays focus is on S60 2 Ed.» Moving to third edition.

– Code recompilation.– Platform security.

• Certificates and data caging.• More access.

– New Kernel.



Available Available IDEIDE’’ss

» Carbide – New generation of development tools. Released

beginning of 2006.

Carbide.c++ is a family of Eclipse-baseddevelopment tools supporting Symbian OSdevelopment on Series 60, Series 80and UIQ.

Carbide.vs is a plug-in that allows Visual Studio users to develop C++ codefor Symbian OS platforms including Series 60 and Series 80.



Available Available IDEIDE’’ss» Other alternatives

– CodeWarrior for Symbian OS

– Borland C++ Builder Mobile Edition

– Using command line tools.

» Note: Platforms– No official support for

anything but Windows.– Linux and Mac

development is possible.



IDE OverviewIDE Overview

» Questions?» Install the software (SDK, IDE, etc)



Getting help: Installation directoriesGetting help: Installation directories

» Dir: C:\Symbian\8.1a\S60_2nd_FP3– Epoc32 - cross compiler, emulator, include files, etc.– Examples - SDK examples– Series60Doc - SDK documentation– Series60Ex - Series 60 specific examples– Series60Tools – Tools

» Lets quickly browse the directories



Using Using Carbide.cCarbide.c++ Express++ Express

» Demo– Find the steps at:

http://mobiledevices.kom.aau.dk/index.php?id=1086



Creating ApplicationsCreating Applications

» Application (.APP): – GUI,

runs in own process

» Engine (.DLL):– Separate DLL, algorithms of the application.

» Server (.EXE): – No GUI, provides services to other servers or applications.

» Kernel (nano kernel): – Access to hardware. Runs in privileged mode.

Privilege boundary

Process boundaries

.DLL

.APP.EXE



Our ApplicationOur Application

» If we look into the \src and \inc of our hello world application we’ll find a number of files with the following names:– HelloworldApp.{cpp | h }– HelloworldDocument.{cpp | h }– HelloworldAppUi.{cpp | h }– HelloworldContainer.{cpp | h }



Application FrameworkApplication Framework

Source: www.forum.nokia.com




» Application class - HelloworldApp.{cpp | h }

– Inherited from CAknApplication– Starts the application– Defines the application's properties. – Creates the Document class




» Document class - HelloworldDocument.{cpp | h }

– Creates the AppUi object in CreateAppUiLfunction

– Can store the applications persistent state.– The base class for document class is

CAknDocument




» AppUi class - HelloworldAppUi.{cpp | h }

– Inherited from CAknAppUi– Handling application-wide events– Handles menu commands and key events– Not responsible for drawing to the screen– Creates and destroys view classes that do the

drawing




» Container class - HelloworldApp.{cpp | h }

– Displays data on the screen – Can handle key events– There can be several different views– View is derived from CCoeControl

Note: this type UI is called control based – other types are dialog based and view based.




» Minimal GUI application» The structure is required for the Application

framework to correctly initialize our apps.» Ensures that the interplay between our

application and the OS is correctly initialized and ready for use.– We’ll start receiving user input etc.



Application FrameworkApplication Framework» Understanding the application flow

• Open HelloworldApp.cpp set the following breakpoints– Line 34 return CHelloWorldDocument::NewL( *this );– Line 47 return new CHelloWorldApp;– Line 58 return KErrNone;

• Open HelloworldDocument.cpp set the following breakpoints– Line 24 Opening brace of destructor– Line 36 CHelloWorldDocument* self = new (ELeave)

CHelloWorldDocument( aApp );– Line 51 return new (ELeave) CHelloWorldAppUi;

• Open HelloworldAppUi.cpp set the following breakpoints– Line 29 BaseConstructL();– Line 45 if (iAppContainer)– Line 85 Opening brace of switch command.

Debug the application in Carbide




» Understanding the application flow

Step until this window is shown:Our application is now running

Select the Test menu option:We now enter the void HandleCommandL() function which handles menu selections.

Finally exit

the application



Resource Resource files(.rssfiles(.rss))» Resource files contains data separate from the

executable code (typically in the data folder)» Resource files are used for defining user interface

components and text strings. » Benefits:

– Less C++ code– If the appearance of application is to be changed there is no

need to change the C++-code only structure of the resource file

» Source code is located in text file named as application_name.rss

» Compiled resource file in application_name.rsc



Resource filesResource files

» Each resource file has to begin with three standard resources– Each resource file must include a NAME

statement before the first resource definition.– RSS_SIGNATURE (this can be blank)– TBUF defines the name of the default document

file (not used)– EIK_APP_INFO defines the resources of menu,

CBA-buttons and hotkeys



Resource filesResource filesNAME HELL // 4 letter ID

// INCLUDES

#include <eikon.rh> // Resource structures .rh#include "HelloWorld.hrh" // Defines menu commands .hrh#include "HelloWorld.loc" // Used for localization .loc#include <avkon.rsg> // Compiled resource file.#include <avkon.rh>#include <avkon.mbg> // ID for bitmaps .mbg

RESOURCE RSS_SIGNATURE { }

RESOURCE TBUF { buf = "HelloWorld"; }

RESOURCE EIK_APP_INFO{hotkeys = r_HelloWorld_hotkeys;menubar = r_HelloWorld_menubar;cba = R_AVKON_SOFTKEYS_OPTIONS_BACK; // Find more in the avkon.rsg}



..hrhhrh filesfiles

» Helloworld.hrh file defines the commands used in resource file.

» Command values must be unique.» When user invokes a command, it is passed

to HandleCommandL-function located in AppUI-class– Must be written so that it handles all the

commands usen by the application



..hrhhrh filesfiles

#ifndef HELLOWORLD_HRH#define HELLOWORLD_HRH

enum THelloworldCommandIds{EHelloworldCmdAppTest = 1};

#endif // HELLOWORLD_HRH



#ifndef HELLOWORLD_HRH#define HELLOWORLD_HRH

enum THelloworldCommandIds{EHelloworldCmdAppTest = 1,ENewMenuItem};

#endif // HELLOWORLD_HRH

RESOURCE MENU_PANE r_Helloworld_menu{items =

{MENU_ITEM { command = EHelloWorldCmdAppTest; txt = qtn_appl_test; },MENU_ITEM { command = EAknCmdExit; txt = qtn_appl_exit; },MENU_ITEM { command = ENewMenuItem; txt = "new item"; }};

}

void CHelloworldAppUi::HandleCommandL(TInt aCommand){switch ( aCommand )

{case ENewMenuItem:

{_LIT(KTest, "Test");CAknInformationNote* note = new (ELeave) CAknInformationNote;note->ExecuteLD(message->Des());break;}

Helloworld.rss

HelloworldAppUi.cpp

Helloworld.hrh

Edit the following files:



Import Project into Import Project into Carbide.cCarbide.c++++

» Using the “obsolete” mmp and bld.inf files» Place your directory with the files in a path

without spaces e.g. C:\CourseFall» Import wizard doesn’t import .pkg file. » Start import select:

– File->Import» No export functionality




» Get the CourseFall application.» Import it into Carbide.» We now have a test application, where we

can test our stuff.



Next upNext up

» Symbian OS fundamentals– Basic types– Naming conventions– Exception handling– Memory management

» Tomorrow– Descriptors– Client/server Framework– Active Object Framework



Symbian OS fundamentals.Symbian OS fundamentals.

» Naming conventions– Helps preserve maintainability, consistency and readability.

» Basic types– Some are simple typedefs, but they can be much more

complex.– Pitfall: TFileName (256 charaters = 512B), default stack size

8-12KB.

» See naming convention and types on refcard.



ExerciseExercise

» Open the CourseFall project» In the CourseFallAppUi.cpp find the function

UseBasicTypesL() and complete the instructions.



Next upNext up





ExceptionsExceptions

» Reliability and robustness must generally bevery high in mobile applications.

» Effective memory management is also vitaldue to– Devices may be on several weeks– Limited memory

Memory leaks must not occur! » NewL and ConstructL methods are for

reliable memory management



WhatWhat areare exceptionsexceptions??– Exception is an indication of some error or problem during

execution. – The bigger the application, the more propable it may have

problem situations.– Typical problems are e.g. out of memory situations or lack of

some resource, e.g. network not available.– In e.g. Java, exceptions are used in many kinds of errorous

situations, e.g. overindexing table, divide by zero etc.– In Symbian OS, exceptions are used in ”lack of resource”

situations.– Symbian OS ”exception” is called leave.



An An exampleexample of of standardstandard C++ C++ exceptionexceptionhandlinghandling

1 int foo(){

2 try {3 ...4 throw 2;

5 throw 14;6 ...7 }

8 catch (int) {9 // the code of exception handler10 }

11 catch (...) {12 // catches all13 throw;

14 }15 }



SymbianSymbian OS OS exceptionexception mechanismmechanism

» Symbian OS exception mechanism differsfrom standard C++

» Symbian OS does not support standardC++ throw-catch mechanism (so it does notmatter if you never coded C++ exceptions).

» The C++ standardization was in progresswhile Symbian OS was developed so theycreated their own mechanism.



PrincipalsPrincipals of of SymbianSymbian OS OS exceptionsexceptions1. Throwing an exception (note. naming convention ’L -leavable’ for

exception throwing method)void COwnClass::SomeMethodL(){

… common code… problem…throw an exceptionUser::Leave( KErrFileNotFound ); // KErrFileNotFound exception identifier

// starts going up}

2. Catching an exceptionvoid COwnClass ::SomeOtherMethod(){

…TInt err = KErrNone; // If SomeMethodL throws an exception, the exception identifier is assigned// to err variable (int). If an exception is not thrown, err is still KErrNoneTRAP( err, SomeMethodL() ); if( err != KErrNone ){

//Exception occurred-> check it…if( err == KErrFileNotFound ){

// Handle an errorous situation where file not found…}

}}



SymbianSymbian OS OS exceptionexception mechanismmechanism

» In Symbian OS, exceptions are used in ”lack of resource” situations. These can be divided into two categories:

1. Memory is tried to be allocated and there is notenough

2. Connecting a resource does not succeed. e.g. • File server• Network connections



TermsTerms

Errorous situationexception

A stack which contains pointers to objects to free if leaveoccurs. Cleanup Stack stores pointers and deletes themwhen a leave occurs.

cleanup stack

Macro, which catches the exception if leave occurred, e.g. TRAP( err, SomeMethodL() );

trap harness

Symbian OS ”exception”. In code: User::Leave() whichthrows a leave, which causes the execution to jump up in the function call hierarchy to first trap harness, where the function was called.

leave

MEANINGTERM



Out of Out of memorymemory situationssituations in C++in C++

» In ’normal’ C++ you allocate an object as follows:if ((myObject = new CSomeObject() == NULL) {

//Out of memory. Handle it somehow, e.g. give errormessage

}

» Out of memory situations are very uncommon in desktop Windows environments.

» If memory can not be allocated, new operatorreturns NULL or throws



new (new (ELeaveELeave))» Symbian OS has its own overloaded new operator for

creating objects: new (ELeave)» new (ELeave) is similar to new but it throws

KErrNoMemory leave if new operation fails due to lack of free memory.

» Next code demonstrates new (ELeave) in Symbian OS compared to standard C++://Creating object with ’standard’ new

CSomeObject* myObject = new CSomeObject; if (myObject == null) User::Leave(KErrNoMemory);

//Creating object with Symbian OS new (ELeave).

CSomeObject* myObject = new (ELeave) CSomeObject;



ProblemProblem situationsituation::» If a leave occurs, the control moves straight up to first

TRAP macro. Let’s take a look at the following code.TRAPD(error,doExampleL());…void doExampleL() {

// Allocating memory for the first object…CSomeObject* myObject1=new (ELeave) CSomeObject;// Allocating memory for second… What happens if memory//is not enough…CSomeObject* myObject2=new (ELeave) CSomeObject;delete myObject1; // These lines will never be executeddelete myObject2; // because leave occurred.

}

» Problem: myObject1 remains in memory…memory leak!!



SolutionSolution: : usingusing CleanupStackCleanupStack» CleanupStack is a stack where you can store pointers of allocated

objects e.g. myObject1 pointer in the scenario in previous slide.» If a leave occurs, TRAP macro frees the memory deleting the pointers

in CleanupStack» You can store pointers by pushing them to CleanupStack as follows:

– CleanupStack::PushL( myObject1 ), pushes objectmyObject1 to the CleanupStack.

» You can remove pointers by popping them from the CleanupStack as follows:– CleanupStack::Pop()

» You can pop and destroy objects in cleanup stack by calling:CleanupStack::PopAndDestroy()

» Pop and PopAnDestroy operations are always for the last object put on the CleanupStack.



CleanClean--up stack and Trap harnessup stack and Trap harness

Programstack

MemoryMore and more dataends up in programstack.

Dynamic data in the heap is referred to via pointers.

Source: T.Mikkonen, 2004



CleanClean--up stack and Trap harnessup stack and Trap harness

Error results in exit for several functions

Memory

Programstack

Trap harness




CleanClean--up stack and Trap harnessup stack and Trap harnessCleanUp stack

Memory

Programstack

Error results in exit for several functions… but clean-up stack remembers reserved

memory blocks




» The previous example with cleanup stack:TRAPD(error,doExampleL());…void doExampleL() {

// We create objects and put them to the cleanup stack.CSomeObject* myObject1=new (ELeave) CSomeObject;CleanupStack::PushL( myObject1 );// If out of memory occurs next, we have myObject1 in the // cleanup stack so it is freed automatically.CSomeObject* myObject2=new (ELeave) CSomeObject;CleanupStack::PushL( myObject2 );………

// At the end we can take objects from the cleanup stack and// free the memory.CleanupStack::Pop();CleanupStack::Pop();delete myObject1; delete myObject2; // The previous four lines could be replaced by// CleanupStack::PopAndDestroy(); // Pop and delete// CleanupStack::PopAndDestroy(); // Pop and delete

}



CanCan alsoalso bebe usedused for for e.ge.g. . closingclosingsessionssessions

void DeleteFileL(const TDesC& aName){

RFs fileserver;User::LeaveIfError(fileserver.Connect());CleanupClosePushL(fileserver);User::LeaveIfError(fileserver.Delete(aName));CleanupStack::PopAndDestroy(); // calls fileserver.close

}



» In some class constructors, you need to dynamicallycreate other objects, which are owned by the class. An example of that kind of class.class CMyCompoundClass : public CBase{public:

CMyCompoundClass();~CMyCompoundClass(); …

private:CMySimpleClass* iSimpleClass1; // owns an instance of another classCMySimpleClass* iSimpleClass2; // owns an instance of another class };

class CMySimpleClass : public CBase{public:

CMySimpleClass();~CMySimpleClass();…

private:Tint iSomeData;

};



» What happens in out of memory situation:CMyCompoundClass::MyCompoundClass(){

iSimpleClass1 = new (ELeave) CMySimpleClass();// What happens if memory is out here??

iSimpleClass2 = new (ELeave) CMySimpleClass();}

» Answer: First new (ELeave) leaves and iSimpleClass1 leaks.



SolutionSolution» Two phased construction:

1. Allocate the object itself without creating the dynamically allocated instances. Now we have a pointer to this object.• This is done in the ’normal’ constructor.

2. After that we create the dynamical members.• This is done in ConstructL method.

– If something goes wrong, we have the pointer sowe can delete all allocated memory.

» These two phases are done in NewL –method.



An An exampleexample

» In the next example we have two classes1. CSmallClass, which does not have dynamic

members. So CSmallClass does not need twophased constructor mechanism (NewL and ConstructL).

2. CBigClass, which has 2 CSmallClass instacevariables. So CBigClass needs two phasedconstruction mechanism (NewL and ConstructL).



// File OwnClasses.h#include<e32base.h>

class CSmallClass : public CBase{public:

CSmallClass ( TInt aNr );~CSmallClass ();

private:TInt iNr;

};



class CBigClass : public CBase{public:

static CBigClass * NewL();~CBigClass ();

private: CBigClass ();void ConstructL();

private:CSmallClass * iSmallClass1;CSmallClass * iSmallClass2;

};



#include"OwnClasses.h"

CSmallClass::CSmallClass( TInt aNr ){

iNr = aNr;}

CSmallClass::~CSmallClass(){}



// CBigClass NewL, ConstructL, constructor and destructorCBigClass* CIsoLuokka::NewL(){

CBigClass* self = new (ELeave) CBigClass();CleanupStack::PushL( self );self->ConstructL();CleanupStack::Pop();return self;

}// ConstructL allocates for dynamic resources.void CBigClass ::ConstructL(){

iSmallClass1 = new (ELeave) CSmallClass( 3 );iSmallClass2 = new (ELeave) CSmallClass( 5 );

}



// Normal constructor. Here we can initialize othermember variables.CBigClass::CBigClass() {}

// Destructor. Free allocated memory.CBigClass::~CBigClass(){

delete iSmallClass1;delete iSmallClass2;

}



NotesNotes» Now, if you want to create an instance of CBigClass you

must do it as in following method :void SomeMethodL(){

// Create CBigClassCBigClass* big = CBigClass::NewL();

}

» CBigClass instance is created by calling its static NewLmethod, which then calls constructor and ConstructL. Ifeverything went ok, big points to the new instance. Failcauses leave.

» NewL is static which means it is a so called class methodmeaning that it can be called without creating the instance first. Static methods can be called by writing: CBigClass::NewL()



SummarySummary of 2of 2--phased phased constructionconstruction

» Create instances by calling NewL if the objectto be created has one.

» NewL method calls first the constructor and so the object is created except its dynamicallyallocated members.

» NewL puts the created object to the CleanupStack and calls its ConstructL.



SummarySummary of 2of 2--phased phased constructionconstruction

» ConstructL method creates the dynamically allocatedmembers. (If there is no enough memory, it leavescausing NewL to leave and CleanupStack to beemptied.)

» After this the execution goes back to NewL, whichpops the object from the cleanup stack and returnsthe pointer to the caller.

» SUMMA SUMMARUM: Two phased constructionguarantees that memory leaks will not occur at anystage of object memory allocation!!



Next upNext up





Additional resourcesAdditional resources

» See slides from day 1» Great books:

» Remember the IRC channels– Freenode #symbian– EFNet #symbian.dev



Literature and sourcesLiterature and sourcesBooks:- Leigh Edwards, Richard Berker, et al.: Developing Series 60 Applications AGuide for Symbian OS Developers, Addison-Wesley, 2004- Richard Harrison: Symbian OS C++ for Mobile Phones, Volume 1, Wiley,2003/2004- Jo Stichbury: Symbian OS Explained – Effective C++ Programming forSmartphones, Wiley, 2004

Slides:- Michael Rohs: Application Development for Mobile Devices, MobileHCI, 2005 - Andreas Jakl: Workshop: Getting started with Symbian OS and Nokia's Developer Suite, 2005- Symbian OS Basics: Workbook www.forum.nokia.com



FinallyFinally

» Questions / comments?» Exam projects.

free study activity fall 2006 day 3 – symbian...

Documents