Hello Symbian vs Hello Windows
This part will describes the details of Symbian OS programming, You need to read the theory and check the necessary code, explanation and also you need to put the code in Carbide tools to compile and run it.
We can start with the tutorial with our famous hello Symbian example. This is a bit different from windows programming. The main reason for this is target hard ware is different than windows. Most time our handheld devices run for weeks or even months without reboot. That makes the difference between windows and mobile phones. Let's compare our hello world console application both in windows and in mobile phone environment
#include <iostream.h>
main()
{
cout << "Hello World";
return 0;
}
Very simple, is it not? Operating system call the method main and a string Hello world is printed to console and the program goes back to operating system. In some IDE you need to include explicitly all library which are used but in some IDE those are hidden with settings.
Now let's take a look a similar console application in Symbian environment. A line number is shown for later reference. For this simple console application we should create a folder structure as shown in the following picture.
Here are brief description of for those folder that are used in this simple client application. For very simple application like this one, we may not need these folder but it is good to have it. Since it allows us to organize our project.
- group:
- bld.inf and
- hellosymbian.mmp
- inc: In inc folder, we store our own header files those are used in our project. In our simple case we have only one file and it's name is hellosymbian.h See the contents of these files in later section.
- src: In src folder, we store our own source files those are used in our project. In our simple case we have only one source file and it's name hellosymbian.cpp See the contents of these files in later section.
- data: In data folder, we store resource related file. Resource are used to enhance the application. In our simple case we use a resource that will help us to register our hellosymbian application so we can see an default application icon in the application shell.
In group folder we keep mmp (make make project) file and bld.inf (build information) file. A mmp file describes the source files name and it's location information of source file and header files, library used and other resource related information. In our simple case we store two files in this folder.
See the contents of these files in later section.
////////////////////////////////////////////////////////////////////
//
//hellosymbian.h (main header file, contains class header and so on)
// This file should be in inc folder
//
////////////////////////////////////////////////////////////////////
1#ifndef __HELLOSYMBIAN__
2#define __HELLOSYMBIAN__
3#include <e32cons.h>
4CConsoleBase* Console; // Console window
5_LIT(KTitle, "HelloSymbian");
6 #endif //__HELLOSYMBIAN__
////////////////////////////////////////////////////////////////////
//
//hellosymbian.cpp (main source file, contains class implementation
//and so on)
// This file should be in src folder
//
/////////////////////////////////////////////////////////////////////
#include "hellosymbian.h"
7 LOCAL_C void LocalMainL()
8 {
9 Console = NULL;
10 Console = Console::NewL(KTitle, TSize(KConsFullScreen, KConsFullScreen));
11 Console->Printf(KTitle);
12 Console->Getch();
13 delete Console;
14 }
//
// Main function called by E32
//
15 GLDEF_C TInt E32Main()
16 {
17 __UHEAP_MARK;
18 CTrapCleanup* cleanup=CTrapCleanup::New();
// Catch any Leaves thrown
19 TRAPD(error, LocalMainL());
20 _LIT(KMsgPanic,"Error in HelloSymbian program: ");
21 __ASSERT_ALWAYS(!error, User::Panic(KMsgPanic, error));
22 delete cleanup;
23 __UHEAP_MARKEND;
24 return 0;
25 }
/////////////////////////////////////////////////////////////////
//
// BLD.INF (build information file)
// This file should be in group folder
//
/////////////////////////////////////////////////////////////////
26 PRJ_MMPFILES
27 hellosymbian.mmp
/////////////////////////////////////////////////////////////////
//
// hellosymbian.mmp (make make project file)
// This file should be in group folder
//
/////////////////////////////////////////////////////////////////
28 TARGET hellosymbian.exe
29 TARGETTYPE exe
31 UID 0x12344321 0x8FFF1002
32 CAPABILITY NONE
33 SOURCEPATH ..\src
34 SOURCE hellosymbian.cpp
35 USERINCLUDE ..\inc
36 SYSTEMINCLUDE \Epoc32\include
37 LIBRARY euser.lib
38 SOURCEPATH ..\data
39 START RESOURCE hellosymbian_reg.rss
40 TARGETPATH \private\10003a3f\apps
41 END
/////////////////////////////////////////////////////////////////
//
// hellosymbian_reg.rss
// This file should be in data folder
// This file normally located under data folder but some people put
// it also in group folder
/////////////////////////////////////////////////////////////////
42#include <appinfo.h>
43 UID2 KUidAppRegistrationResourceFile
44 UID3 0x8FFF1002
45 RESOURCE APP_REGISTRATION_INFO
46 {
47 app_file="hellosymbian";
48 }
Some explanation about our HelloSymbian
In statement 3:
we include header file that we need for these simple application, without this we can't compile this project
In statement 4:
we declare a pointer to CConsoleBase type which will be used for input and output. We need to allocate the memory for this and we have to delete the memory also.
In statement 5:
we declare a descriptor (roughly we say string or char array in Symbian but this is not exactly same) that we are planning to print to the console. More on this topics can be found from descriptor chapter.
In statement 7:
we define our own function that will be called from E32Main. When an application starts, it starts by calling this E32Main method by the Symbian OS. Then sequentially other methods are called and finally it is returned to OS by return statement.
In statement 9:
we initialize Console to NULL, though it is not necessary to a class that is derived from CBase.
In statement 10:
we allocate memory for Console variable by calling static function (NewL) with three parameters. We know more about object construction in cleanupstack chapter.
In statement 11:
We print the text HelloSymbian to console by calling Printf method. KTitle is a reference to HelloSymbian that is declared in statement 5.
In statement 12:
We wait for a character to be typed so we can see our HelloSymbian text on the screen.
In statement 13:
We delete the allocated memory so we don't waste any memory.
This is about our LocalMainL().
Now let's take a look in our E32Main() method. This is main function for Symbian OS. When an application is started it will be called.
In statement 17:
We use __UHEAP_MARK to start counting free memory cell at this point of execution. The reason we start this statement is that later we can use __UHEAP_MARKEND to check if the free memory cell is same. That means if we have allocated some memory and we forget to deallocate it then there will be mismatch in free memory cell and we get a panic. We can easily verify this if we comment out statement 13.
In statement 18:
We install cleanup stack (CTrapCleanup). System installs the cleanup stack for this thread. Main job of cleanup stack is that when some exception occurs then it destroys all objects that were pushed on the stack. In ideal situation we may leave without cleanup stack. More about this will be discussed in cleanupstack chapter.
In statement 19:
We call our LocalMainL() method under trap harness. More about this can be found in cleanupstack chapter. Main point here is that when some exception occurs in LocalMainL or in turn in Console::NewL()then the leave codes (thrown value inside these methods) are caught by TRAPD and the leave value is assigned to error. If no leave occurs (no exception was thrown) then the error variable is not updated. About C++ exception good information can be found about C++ exception.
In statement 20:
In this statement we declare a similar descriptor (for time being we say string) that will be printed if there were really any leave in any of the methods.
In statement 21:
By this statement we say if the value of error is other than 0 then it will call panic method (by default it will close the application). You may think where we declare the variable error? It is declared inside the TRAPD macro. To check what how error variable is updated you can make a bit modification to our program by putting a statement User::Leave(-1); between statement 9 and 10. If you check with debugger then you noticed that value of error is -1 and soon your application will be closed;
In statement 22:
We delete our cleanupstack, we are done with this.
In statement 23:
This end point where we again count the memory cell. If we have same memory cell at this point that means we have removed all our allocated memory for our application properly. For debug build if there is mismatch in number of free memory cell then we get a panic in our application.
In statement 26 and 27:
This are part of our bld.inf file. This file is used for organizing our projects in Symbian build system.
In statement 28:
We declare the name of target file (hellosymbian.exe) in our mmp file. Mmp file is used to manage our single project. For each Symbian project we should have one mmp file. TARGET keyword tell what kind of binary we are going to build. If we build dll then we can write somedllname.dll for example.
In statement 29:
By TARGETTYPE keyword we tell explicitly to build system what kind of binary we build.
In statement 31:
In Symbian we always use 3 UID (Unique identifier). First one is determined by the build system (exe or dll determine this) and then 2nd and 3rd can be declared in the mmp file explicitly.
In statement 32:
CAPABILITY key word is used to give some security token to application. This will be discussed later in Symbian OS security chapter.
In statement 33:
By SOURCEPATH keyword we can specify the source directory with relative path.
In statement 34:
By SOURCE keyword we can specify the name of source file, we can have multiple source files.
In statement 35:
By USERINCLUDE keyword we can specify the include directory with relative path. we tell the build system where we have stored our own header files that will be used by our application.
In statement 36:
By SYSTEMINCLUDE we said where the build system should search header file those are provided by SDK.
In statement 37:
By LIBRARY keyword we tell the build system what kind of library will be used.
In statement 38:
We have used SOURCEPATH previously. By using another times, we redefine the source path. This time we tell to build system that source are located in data folder.
In statement 39-41:
We provide information about registration file. By this file we register our application so that we can see an default application icon in installed folder.
In statement 42-47:
Contents of the registration file.
In statement 42:
Header file that is necessary for registration.
In statement 43:
We mention our 3rd UID that we have used in our mmp file.
In statement 47:
We tell our application name so the name can be visible in installed folder.
Now we have some basic understanding about our HelloSymbian project. If you download this example and compile/link it then see if it works like this.
Download area
Download Symbian_OS_Basics_Workbook_v3_1_en.pdf
Download the zip file and see the video in youtube. You need to change the pkg file to reflect your EPOCROOT. See youtube video http://www.youtube.com/watch?v=uji6apRskFU