Lucian Piros
Lucian Piros has been working in telecommunications and embedded and mobile computing for over 10 years, after completing a mathematics and computer science degree at Babe -Bolyai University. He has worked in the Symbian ecosystem since 2006, in the PIM team of Symbian as well as for the Contacts team in Nokia. He provides extensive technical support to Symbian developers worldwide, through SDN SDN forums, and contributed to Symbian OS C forMobile Phones Volume 3. Lucian became an SDN...
Multiple Inheritance
On the Symbian platform, the use of multiple interface class M class inheritance is the only form of multiple inheritance that is encouraged. The following example illustrates a class which inherits from CBase and two mixin interfaces, MRadio and MClock. In this case, MClock is 18For a thorough discussion of this topic applied to the Singleton pattern, please refer to the April 2008 Code Clinic article at developer.symbian.org wiki index.php WSD_and_the_Singleton_Pattern. 19 See not a...
Untrusted Applications
Applications which do not need any capabilities and do not need the protection afforded by having a SID from the protected range do not need to be trusted. Additionally, untrusted applications are typically allowed the following set of capabilities 6 5 The reality is more complex, of course device manufacturers have an interest in promoting third-party development and developers have an interest in promoting confident users. 6 Until S60 3.2, the Location capability was not available to...
Expat
Next I ported Expat I had the advantage here that this library has already been ported to the Symbian platform several times. There is even a tutorial for porting an older version of the library to earlier versions of Symbian OS on the popular Symbian developer website called NewLC.11 I was 10 I call them external here but Bluemapia actually delivers versions of them in its source tree - they are only external in the sense that the source code has come from various third parties. 11 See able to...
Running and Testing 1
Most Symbian platform devices are not ideally suited to the use of command-line utilities the screen is usually on the small side and the input capabilities are rarely appropriate for that kind of user interaction. For this reason, initial testing of such programs is much easier on the emulator. To test SoundStretch, I used eshell, a basic text shell environment for the Symbian platform much like a UNIX Linux shell. The eshell program is provided for the emulator as part of Symbian SDKs....
Compiling
This is the easy part Simply press the Build button in your IDE and wait for it to spit out a great mass of errors. Unless you aren't expecting any problems or the project is very small and simple then it can be a very good idea to comment or ifdef out large sections of the code and focus on getting some core functionality working. Also, make sure you try building with both the emulator and target compilers regularly to ensure you aren't introducing anything that doesn't work in both...
Cocoa Foundation Framework and Qt Compared
The general-purpose data structures and access to some basic I O are encompassed by the Foundation framework in Cocoa Touch. In Qt the equivalents are mostly, but not exclusively, found in the QtCore library. Below, we take a quick look at these classes to see what you can map your Cocoa Foundation class into. It is not intended to be an exhaustive description of the classes. For details, please consult the Qt reference.18 17 See Section 6.4 and Chapters 10, 11 and 12 for more information. The...
Porting Middleware
I have always wished for my computer to be as easy to use as my telephone my wish has come true because I can no longer figure out how to use my telephone. This chapter is about porting middleware to the Symbian platform. We examine the subject via two case studies for middleware that is in the process of being ported. The first of these is an excellent example of platform-independent middleware, the open source Geospatial Data Abstraction Library GDAL .1 As it deals with converting and...
Types of Certificate
Both Windows Mobile and Symbian have different kinds of certificate and these restrict what classes of APIs can be called. Windows Mobile has a privileged mode certificate and a regular developer certificate, in addition to the Microsoft signed certificate for released code. Symbian has a similar set of certificates. If only user-granted capabilities are being used then a self-generated certificate may be used. If the application is being tested and is using enhanced set capabilities, then it...
Descriptors as Function Parameters
As I described earlier, the TDesC and TDes descriptor base classes provide and implement the APIs for all descriptor operations. This means that they can be used as function arguments and return types, allowing descriptors to be passed around in code without forcing a dependency on a particular type. An API client shouldn't be constrained to using a TBuf just because a particular function requires it, and function providers remain agnostic to the type of descriptor passed to them. Unless a...
Component Object Model
One of the key aspects of modern programming languages is the use of interface-based programming and the subsequent introduction of the use of shared modules. Windows particularly places a lot of emphasis on this and it is termed the Component Object Model COM . Much of the extensibility of Windows comes directly from the fact that objects can implement interfaces and the system can use and discover new implementations of interfaces. Symbian has adopted a similar model called the Epoc Component...
A Improved Heap Failure Tool
The OOM loop approach described in Section A.2 also had its issues 1. It was hard to determine where to set heap failure limits i.e. the maximum value of k. 2. Not all allocation failures resulted in observable bugs but they still made the system under test run in a slightly inconsistent state. 3. Some complicated bugs were hard to debug because the allocation failure and the observed error were highly decoupled i.e. very far from each other. 4. Some integration test cases would detect errors...
Getting It to Work 1
The first run of the application in the emulator reveals two extremely common problems for desktop applications ported to mobile devices Figure 10.2 CuteMaze running on Symbian, unmodified Figure 10.2 CuteMaze running on Symbian, unmodified the application's main window doesn't fit on the screen and many of the application controls are designed for use with a mouse. Figure 10.2 shows CuteMaze running in the emulator after the initial compilation attempt. Fortunately this project has already...
Working Out which Capabilities You Need
For EXEs, the capability set you need depends on what you want to do, in particular on which server APIs you need to call and what data you need to access. There are not many capabilities and their definition is, in general, clear so you should start off with a good idea of which capabilities your application is likely to need. If your thread fails a capability check, the server is likely to complete the request with an error code such as KErrAccessDenied -46 alternatively, it may panic the...
Debugging
The process of debugging ported code on the Symbian platform is not significantly different from debugging on other platforms. A key difference from a standard POSIX environment is the lack of stdout and stderr by default although you can have a console which provides them, it would be in the way of a graphical application . Instead, you can write debugging output to a file or include e32debug.h and use the native Symbian RDebug Printf as a direct replacement.21 Another important difference is...
Development Environments Compared
While developers can write programs for Android on their favorite desktop computer running Windows, Linux or Mac OS X, Symbian C development can take place only on Windows. Even though Symbian modules can be built on Linux machines, the set of development tools is incomplete on-device debugging is not possible, for example and are unofficial, thus they come with limited support. At the time of writing, the latest Android SDK is v1.1. This low version number alone clearly indicates that Android...
The CLSI
The Local System Interface class CLSI is the backbone of the backend component. A single instance of the class is created per process - either in the glue code or when the first P.I.P.S. API is invoked from a hybrid application. The CLSI object stores session handles to the various system servers RFs, RSockServ, etc. and P.I.P.S. support servers the stdio server, the IPC server, etc. . It also plays host to the file table. Nearly all of the functionality of the backend is implemented in methods...
Stack Size for Standard C and OpenSSL
For all existing versions of the Symbian platform, the default stack size is 8 KB, which is significantly smaller than for most other platforms. Some of the functions in the OpenSSL libraries need more than this default amount of stack. Additionally, standard C code often requires more stack space than native Symbian C . If you are using either of these then the recommended stack size is 64 KB. The default stack size for your project can be set to 64 KB by adding the following line to the MMP...
Using the Cleanup Stack with NonCBase Classes
Up to this point, we've only really considered one of the overloads of the CleanupStack PushL function, PushL CBase aPtr , which takes a pointer to a CBase-derived object. When Cleanup-Stack PopAndDestroy is called for that object, or if leave processing occurs, the object is destroyed by invoking delete on the pointer, which calls the virtual destructor of the CBase-derived object.10 If an object does not derive from CBase, there are two alternative overloads of PushL that may be used. The...
Packaging for Device Installation
Having created the build files and a project in your IDE, you should have everything you need to start working on the emulator. To get your code running on a real device, it also needs to be appropriately packaged and signed. For packaging, you need a PKG extension .pkg file, which specifies where to get the executables and resource files generated by your build and where to put them in the device's file system. It also includes information on any dependencies that must already be present on...
Certificates and PKI
A public key infrastructure PKI is a system that enables the recipients of signed messages to obtain authentic copies of public keys in order to verify them. In a PKI, there is an organization called a Certification Authority CA , which has a signing key pair. The public key is known to be authentic this is generally because it is embedded in the devices or programs which are used by the recipients of signed messages. The entity wishing to send signed messages generates a key pair, then applies...
Symbian OS v and Later Versions
From Symbian OS v9.3 which includes all versions of the Symbian platform , new target types stdexe, stddll and stdlib have been added, specifically for use with P.I.P.S. and Open C C . Some of the necessary libraries and include paths see Table 4.4 are automatically included when you use these target types they do not have to be added to the MMP file separately. New UID2 values are required for stdexe and stddll target types to distinguish them from the original EXE and DLL types. For a STDEXE,...
Vinod Vijayarajan
Vinod is the Technology Architect of Generic OS Services, a module in S60 that includes P.I.P.S. and Open C C . He has been associated with P.I.P.S. since its conception and helped it grow from a fragile, proof-of-concept port to a solid, stable foundation for technologies such as Qt and Python on S60. As lead and architect, he designed and implemented several key components in the libraries, drove releases, ran port-assistance programs, engaged with end users and application developers and...
Trapping a Leave Using TRAP and TRAPD
The Symbian platform provides two macros, TRAP and TRAPD, to trap a leave. The macros differ only in that trapd declares a variable in which the leave error code is returned, while the program code itself must declare a variable before calling trap. Thus the following statement TRAPD result, MayLeaveL if KErrNone result Handle error If a leave occurs inside the MayLeaveL function, which is executed inside the harness, the program control returns immediately to the trap harness macro. The...
Android and Symbian Compared
In this section, we compare the basics of the Android and Symbian platforms. Symbian has a multi-tasking, multi-threading operating system allowing more than one application to run concurrently, and this behavior applies to third-party software, too. Each application runs in a separate process, making code execution more robust and secure. This is the same on Android. However, a Symbian program has a main entry point, the E32Main function, which is called by the system upon application...
The Main Executable
The remaining libraries used by Bluemapia are included directly in the project that builds the main executable, rather than linked separately. To create the necessary build files for the main executable, I used the 'qmake -project' trick again with some extra options to avoid including Windows-specific files qmake -project -norecursive -nopwd SRC SRC Formats BSB INC Using these options allows you to specify that you don't want to include files from the current directory and qmake shouldn't...
How to Identify a Leaving Function
As I mentioned in Section 3.2.2, if a function may leave, its name must be suffixed with 'L'. You must use this rule of all Symbian C naming guidelines it is probably the most important. If you don't name a leaving function accordingly, callers of your code may not defend themselves against a leave and may potentially leak memory. The L suffix is not checked during compilation, so occasionally you may forget to append it to a function name or you may later add leaving code to a previously...
Secure ID SID
Every binary in the system - including Symbian platform and phone manufacturer code - contains a 32-bit secure identifier value, referred to as the SID. When an EXE is launched, the SID is copied from the EXE into the process. The EXE cannot change the SID. The process SID is always the same as the EXE SID. If the same EXE is launched multiple times, all the processes have the same SID. Exactly as for capabilities, servers can find out the SIDs of their clients and use this to decide whether or...
Tool Support
The makekeys command-line tool can be used to generate key pairs, certificates and certificate requests. To sign SIS files, you use the signsis tool. For details of the syntax of these tools, see the Symbian Developer Library. Carbide.c , the IDE for Symbian development, integrates signing SIS packages select Project, Properties, Carbide.c , Build Configurations and then the SIS Builder tab, as shown in Figure 14.6. When you click the Add button, a dialog appears in which you can supply your...
Open Signed Online
The Open Signed Online scheme operates without a Publisher ID 1. The developer creates an unsigned SIS file. 2. The developer uploads the SIS file to Symbian Signed, together with the IMEI of the target phone and the set of capabilities needed. 3. Symbian generates a signed SIS file. 4. The developer downloads the signed SIS file for distribution. The SIS can only be installed on a single phone the one whose IMEI matches the IMEI sent to Symbian Signed. Applications signed under this scheme get...
Integration with the Symbian Build System qmake
As they have to be built on all of the supported platforms, it is not surprising that the Qt libraries use the same platform-independent project files as all Qt applications. With the build files common across platforms, the task of integrating with the Symbian build system was reduced to porting the build tools and adding support for platform-specific extensions. The first step was to ensure that all of the existing tools could be compiled with the Nokia x86 compiler since it is the one most...
Integrating with the Symbian Build System
Prior to the introduction of Raptor11 in the latest version of the platform, the Symbian build system had been in roughly the same form since the early days of the operating system. This meant it was overdue a complete overhaul. Whatever platform you are porting from, you will need to adapt 11 to the build system. This can be a difficult area for larger projects and a major headache if you want to add Symbian to the platforms already supported by a project under a common build system.12...
Active Scheduler vs Main Loop
The vast majority of native Symbian C code is executed, indirectly, from the RunL method of some active object. As explained in Chapter 3, these active objects are non-preemptively scheduled by an active scheduler that is, the RunL functions are always allowed to run to completion before the scheduler selects the highest priority waiting active object to run next. This framework allows developers to implement multi-tasking systems and access resources asynchronously without having to deal with...
Leaves and the Cleanup Stack
We can now tie together the implementation of leaves in terms of standard C exceptions and the cleanup stack.11 When a leave occurs 11 See 1. The cleanup stack 'unwinds' and each item on it is cleaned up e.g. destructors are called for C classes, Close is called on any R class object made leave-safe by a call to CleanupClosePushL , etc. . 2. An XLeaveException is created and thrown to represent the leave, resulting in the unwinding of the stack. 3. The exception is caught by the trap handler....
The STLport uSTL and Open C
Historically, one of the main things that C programmers moving to the Symbian platform have missed is the Standard Template Library STL . In response to this, there have been two Symbian ports of open source STL implementations available for some time. First there was uSTL, a partial implementation of the STL, selected by Penrillian3 as most suitable for a mobile platform due to the small size of the generated object code. Then there's the STLport, one of the most popular and...
Trusted Computing Base
Trusted Computing Base TCB is a standard term referring to that part of a system responsible for ensuring the security of all other parts of the system. In the Symbian platform, the Trusted Computing Base comprises TCB capability has only an indirect relationship with the Trusted Computing Base itself. Not all components which require TCB capability are actually part of the Trusted Computing Base for example, an enterprise device management system may need tcb capability because it needs direct...
Interprocess and Interthread Communication
Symbian has a rich inter-process IPC and inter-thread ITC services API to support isolated and secure access to operating system and third-party services. Many system services in Symbian exist as a separate process and applications connect to the process, which decides on the basis of the security identifier, the vendor identifier and the caller's capabilities the functionality that is made available. For example, the graphics environment, the windows framework and the telephony services are...
OutofMemory Errors
Ported code must be aware that it is running in a memory-constrained environment. Out-of-memory situations can occur and need to be handled gracefully. By default, a process is restricted to a maximum of 1 MB of heap. You may increase this limit by using the EPOCHEAPSIZE directive in your MMP file see Section 2.7 for more on heap memory limits on the Symbian platform . In very low memory conditions, your P.I.P.S. application may crash at launch with a stdlibs-init panic. This indicates that the...
Vendor ID VID
Each binary in the system may optionally also contain a 32-bit vendor identifier value, referred to as the VID. As for SIDs and capabilities, the EXE VID is copied into the process, cannot be changed by the EXE itself, and can be queried by servers. VIDs are, of course, not unique all EXEs provided by a single organization will share the same VID value. All VIDs are protected, so if an EXE contains a VID it must be signed by an approved authority. A VID can be used by a device manufacturer to...
Open Mobile Development in CC
Lauri Aalto, Will Bamberg, David Caabeiro, Ivan Litovski, Gabor Morvay, Lucian Piros, Jo Stichbury, Paul Todd, Gabor Torok, Vinod Vijayarajan Nicholas Addo, Michael Aubert, Serage Bet-el-mat, Madhavan Bhattathiri, Robert Cliff, David Crookes, Biswajeet Dash, Craig Heath, John Imhofe, Mark Jacobs, Erik Jacobson, Pekka Kosonen, Ian McDowall, Lucian Piros, Mangesh Pradhan, Steve Rawlings, Salvatore Rinaldo, Espen Riskedal, Andy Sizer, Colin Ward Head of Technical Communications, Symbian Jo...
Porting from Linux to Symbian
The main porting goal is to simplify the task by using ported components such as Open C C and Qt for S60, or other existing components that are easier to manage in a Linux-based code base, for example, UNIX-like APIs such as Khronos' OpenKODE. Even though the libraries are available, not all may be present on devices currently in the market. While Open C C is present in all modern S60 phones see Chapter 4 for more details , Qt is currently not and requires either a separate SIS installation or...
Open Signed Offline
The Open Signed Offline scheme operates with a Publisher ID. The developer gets a Developer Certificate to re-sign the application when the code changes. 1. The developer generates a request for a Developer Certificate, signing it using the Publisher ID, and uploads it to Symbian Signed along with the list of IMEIs for the target phones. 2. Symbian Signed generates a Developer Certificate and associated key pair, which the developer can download and use to sign the application. Applications...
Paul Todd
Paul's first experience with Symbian was the very old Psion LZ64, which he used to interface to surveying instruments where the collected data was exported to Autocad and used to generate maps for quantity surveys. He emigrated to England in the early 1990s, where he did some work on developing quantity-surveying tools until he got involved with the first enterprise synchronization tool for PDAs ASL Connect . After a number of years of work on Windows Server and Windows Mobile CE, he was...
Architecture of Qt on the Symbian Platform
The Qt port was another of those made feasible by Open C. Although it was necessary to interface directly to the native Symbian platform code in a number of places, a large part of the port uses the same code as various Unix-compatible systems via the Open C APIs. However, as application code still runs natively and in the context of an active scheduler provided by the native application framework , it is very easy to mix Qt code with native Symbian C as well as using Open C C directly. These...
API Mappings
The following tables contain the most widely used APIs sorted by functionality. Android class names are listed along with their package names and then the corresponding Symbian class names with their appropriate 9 Nokia's Ovi Store can be found at https store.ovi.com. header files and library files in parentheses. These classes and APIs may not fully overlap each other's functionality, however, they're the closest to each other in terms of supported features. Table 9.1 File I O APIs Opening,...
Before Symbian OS v
Before Symbian OS v9.3, there are no special target types for standard C C projects. You either create a standard Symbian OS executable EXE , a dynamic link library DLL or a static library LIB then include headers and link with libraries from P.I.P.S. or Open C C . This results in some fairly common problems with porting. The first and most obvious of these is that the standard entry point for a Symbian executable is E32Main on almost all other platforms, it is called main . There are also...
Getting It to Work
As there is no test harness with the original project, I decided that some very simple manual tests would suffice. I used a signal generator program to produce sine waves across a range of frequencies and ensured that 16Another quirk discovered during this port relates to fonts. CWsScreenDevice GetNearestFontToMaxHeightInTwips returns a font that is missing most of the ASCII characters on S60 3rd Edition but is fine on S60 3rd Edition FP1. GetNearestFont-ToDesignHeightInTwips appears to work on...
Des Method
The stack- and heap-based constant buffer descriptor classes, TBufC and HBufC, provide a method that returns a modifiable pointer descriptor that references the data represented by the buffer. So, while the content of a non-modifiable buffer descriptor cannot be altered directly, except by using the assignment operator to replace the data completely, it is possible to modify the data indirectly by calling Des and then operating on the data via the pointer it returns. When the data is modified...