EPOC
Application development in C++ : Overview
Written
by Onkar
Singh Parhar
Introduction
Scope
Concept
Of UIDs
The
Begining
Summary
Introduction
EPOC
is a real time operating system developed by Symbian
targeting small handheld devices like Communicater and Smartphone. EPOC was
designed keeping in view the requirement of these types of Wireless
Information Devices or just WID?s which have their own limitations as small,
different screen sizes, Less battery power
and less memory and processing power. The operating system is developed
using Object-Oriented technology implemented in C++. Besides this Java Virtual
Machine (JVM) is also implemented. EPOC provides an Application development
framework which can be used for developing applications. Since the OS
intrinsically supports Object Orientation, powerful, compact and efficient
applications can be developed. The components could easily be reused as
well.
In
this article, we will learn about developing a minimal application. Though
Java and OPL can be used as programming languages, we will work on ground level
with C++.
For
development of our application we need :
?
EPOC C++ SDK installed on the machine. It has a PC-based
emulator which gives us a chance to develop and test our application before
transferring it to actual device running on EPOC. If you don?t have
this installed, you can download the SDK from EPOC
World.
? Microsoft
Visual Studio 5.0 or 6.0
The core components of
EPOC are :
Figure 1
Details
of above components are available here.
At this time EPOC Release 5 is out and it is significantly different
and improved than its predecessors.
Before we go ahead with our first EPOC application, I would like you to
understand a very important concept - Memory management in case of EPOC.
Wireless Information devices are not like BIG desktop PC?s where sufficient
memory ( or even more than that ) is available. WID?s have less memory and
the device itself is very much personalized. Application failure which causes
any type of data loss will make
the user unhappy. We as developers should keep this in mind while writing
applications for EPOC devices. Here are some golden rules :
1.
Don?t allocate memory more than what you need.
2.
Release all resources as soon as you are done with them. Any type of
memory leak may cause failure of applications which may run in future.
3.
Handle every operation where memory is involved. Check every condition
where a failure can occur.
4.
In case of failure, gracefully come back and report it to the user.
Scope
:
The
Application will be developed to run on the Windows-based Emulator only. Once
an application has been tested with the Emulator, it can be recompiled for
native using GNU C++ compiler. The machine code then can be transferred to the
device using EPOC Connect.
Concept
of UIDs:
A UID is an identifier which uniquely identifies an object to
which it is associated. UID?s are one of the basic features of EPOC. A UID
is a 32-bit number which is there because of following reasons.
1.
UIDs identify different objects at runtime and load time. E.g. Files,
Executables and Dll?s.
2.
When associated with a document, it is easy for the system to identify
the application with which that document can be opened.
3.
UID?s are used to verify object interfaces at runtime and at load
time.
But to use non-native data files , EPOC does allow using them without UID?s.
For more information, you can look at EPOC System Documentation.
The
Begining :
Now let?s start writing our first EPOC program. We will call it
?Welcome to EPOC World?. This will be a console application which
runs on EPOC shell. The program uses
E32 user library which provide basic functionalities that can used by
all applications running on EPOC.
We
first create a directory named ?MYEPOC? in root of where EPOC is
installed. (Remember the EPOC drive is a mapped one). Create a subdirectory
?welcome?. Project information is maintained in .mmp file. Create a file welcome.mmp
in any text editor. Type following lines and save it in ?welcome?
subdirectory.
TARGET
welcome.exe
TARGETTYPE
exe
UID
0
UNICODEUID
0
PROJECT
myepoc
SUBPROJECT
welcome
SOURCE
welcome.cpp
USERINCLUDE
\welcome
SYSTEMINCLUDE
\epoc32\include
LIBRARY
euser.lib
Anatomy of welcome.mmp
is as follows :
?
TARGET specifies the name of the final output.
?
TARGETTYPE specifies whether the final output is exe or dll.
?
UID is Unique Identifier. We keep this 0
?
UNICODEUID is Unicode Unique Identifier.
?
PROJECT specifies a directory name where all sub-projects are
kept. We take it as MYEPOC.
?
SUBPROJECT is one of the project directories present in PROJECT (
In our case, MYEPOC). Our subproject is ?welcome?
?
SOURCE specifies all .cpp source file names.
?
USERINCLUDE takes path where the .h files of the project are present.
?
SYSTEMINCLUDE is path where system .h files are located.
?
LIBRARY specifies which system libraries are used in the
project. In our welcome project, we need only euser.lib.
We can now use this .mmp file to
generate .dsp and .dsw files. Makmake.pl is a utility available
with the EPOC SDK for this purpose. The generated files can be used for further development
in Visual Studio IDE.
- Goto
command prompt and Change directory to EPOC drive (Mapped drive name).
Move to directory where welcome.mmp file is present, i.e, \MYEPOC\welcome
directory.
- If
you are using Visual Studio 5.0 or 6.0, type the following at the command
prompt. In case of VC6, VC 6.0 patch must have been installed.
(EPOC drive):\MYEPOC\welcome> makmake welcome vc5
But if you have VC4, your command will change to,
(EPOC drive):\MYEPOC\welcome> makmake welcome vc4
This
will generate two Visual Studio project files and a file named
welcome.uid.cpp. A warning "welcome.cpp not
found!" would also occur. Ignore it.
You are now ready
to write actual
working code. Create and add a new source file welcome.cpp into the
welcome project.
Type
the following lines.
#include "welcome.h"
// Actual code that welcomes
void doWelcomeL()
{
_LIT(KHelloWorldText,"Welcome to EPOC World!\n");
console->Printf(KHelloWorldText);
}
First line in the function doWelcomeL() copies a C-like string
"Welcome to EPOC World!\n?, to a EPOC literal identifier KWelcomeText.
The second line outputs it to the EPOC console.
But how EPOC comes to know when to execute doWelcomeL(). For
this we need to instruct the system as follows.
Create a new file named ?welcome.h? and type the following code?.
#include <e32base.h>
#include <e32cons.h>
_LIT(KErrorText,"Program failed");
CConsoleBase* console; // console object
void doWelcomeL(); // our function implemented in welcome.cpp
void callExampleL(); // initialize with cleanup stack
TInt E32Main() // main function called by E32
{
CTrapCleanup* cleanup=CTrapCleanup::New(); // get clean-up stack
TRAPD(error,callExampleL()); // more initialization, then do example
__ASSERT_ALWAYS(!error,User::Panic(_L(""),error));
delete cleanup; // destroy clean-up stack
return 0; // and return
}
void callExampleL() // initialize and call doWelcome() under cleanup stack
{
console=Console::NewL(_L(""),TSize(KConsFullScreen,KConsFullScreen));
CleanupStack::PushL(console);
TRAPD(error,doWelcomeL()); // call doWelcomeL()
if (error)
console->Printf(KErrorText);
console->Getch(); // wait for any keypress
CleanupStack::PopAndDestroy();
}
Build the project with WIN32 Debug or Release as the Active
Configuration. If any errors comes, check if the SDK is installed properly or
not. Otherwise run ( CTRL+F5 ) the program in EPOC Emulator. It should display output as in Figure 2.
Figure 2.
In the code, you can see E32Main() function which is called by E32
library when the program starts. This is similar to Main() function. Inside
E32Main, we do some activities which make our program reliable, in the sense
that if it fails for any reason like out of memory conditions, it will exit
gracefully. The first statement instantiates an object of CTrapCleanup class
which is derived from CBase class. The instance variable cleanup is
returned. The second line is a macro call TRAPD. This macro calls the
doExampleL() function. The function has ?L? as last character in its name.
This specifies that this function can Leave if it fails. If failure occurs, a
panic is raised by the next statement. The fourth statement deletes the cleanup
object and the program returns. Details on cleanup-mechanism in EPOC is
available in EPOC C++ system documentation.
In the doExampleL(), the first statement returns console which a
pointer to instance of CConsoleBase class. This pointer will be used to
perform EPOC console activities like writing to and reading from the screen.
Second statement pushes the console object pointer to the cleanup stack. Again
a call to TRAPD macro is made. This time our function doWelocmeL() is
executed. The string ?Welcome to EPOC World!? is displayed. If failure
occurs, this function will Leave too and an error message will be displayed on
the console. The last statement in doExampleL() pops up all objects from the
Cleanup stack and destroys them releasing all memory allocated to them.
Summary
In this article, we discussed about writing a minimal application for
EPOC using E32 User Library. The techniques described here are basics of EPOC
programming like the cleanup mechanism and generating project information
files using makmake utility. Former is more important which should be
given most attention throughout the application development cycle.
