Graphics and Drawing
On Symbian OS, applications do not draw directly to the window, but use a graphics context GC for drawing to the window. An area inside the physical screen the device's display first needs to be defined, any drawing occurs inside that defined window area, thus preventing an application from drawing outside its window area. In principle, all normal graphics drawing in Symbian OS takes place in an RWindow-derived window, owned by the window server WSERV . WSERV uses the font and bitmap server...
Running the Hello World Application on the Device
Running the Hello World application on the device requires a SIS installation file .sis file . The installation file is created from the PKG package file .pkg file , located in the sis folder of the project. More information about the syntax to use in a PKG file can be found in the Symbian Developer Library CHM documentation, found in each SDK. During the build process, the SIS file will be created automatically from the HelloWorld.pkg file. The result is HelloWorld.sis and HelloWorld.sisx. The...
Symbian OS Class Conventions
By convention, there are several class types on Symbian OS, each of which has different characteristics, such as where objects may be created on the heap, on the stack, or on either and how those objects should later be cleaned up. The classes are named with a prefix according to type, and this convention makes the creation, use and destruction of objects more straightforward. When writing code, the required behavior of a class should be matched to the Symbian OS class characteristics. Later, a...
PreInstalled Applications
One way to distribute your application to users while avoiding the complicated relationship between publishers, content aggregators and network operators is to get the application built onto a phone handset by the manufacturer or provided on a CD ROM in the box that contains the handset . Naturally, there are far fewer opportunities for built-in applications than there are developers who wish to get their application pre-installed onto a phone The market exposure of an embedded application is...
Threads
In many cases on Symbian OS, it is preferable to use active objects rather than threads, since these are optimized for event-driven multitasking on the platform. However, when you are porting code written for other platforms, or writing code with real-time requirements, it is often necessary to write multithreaded code. The Symbian OS class used to manipulate threads is RThread, which represents a handle to a thread the thread itself is a kernel object. The RThread class defines several...
Running the Hello World Application on the Emulator
Select the Run Run menu from the Carbide.c IDE to run Hello World on the emulator. You can select the Run Debug menu to debug the project. Alternatively, you can also right click the project name to select the same menus. Figure 2.9 shows the Hello World application running from the emulator. The S60 3rd Edition emulator is shown on the left, and the UIQ 3 emulator on the right. This Hello World application simply displays the text 'HelloWorld', which is the project name, on the screen, as can...
Required platform security capabilitys LocalServices Ynn
Problem You want to advertise Bluetooth server services. Solution After another Bluetooth device has found the listening Bluetooth server, it is necessary to check whether this server actually provides the required services. It would be useless if we connect to a device and then discover that it doesn't even supply the service that we require. The code listed below shows how to add FTP to the service discovery protocol database refer to the comments within the code for a more detailed...
Links
Code samples for Symbian Press books, including this one Forum Nokia wiki - Moving to Windows Vista wiki.forum.nokia. Figure 2.22 SIS Builder in Carbide.c IDE Figure 2.22 SIS Builder in Carbide.c IDE Q jIj Properties SIS File Creation Options PK j I ile sis HelloVVorld.pkg Output File Name Content Search Location Siqninq Options Don't sign sis tile vfli siyn '.is file O Sign sis file with certificate key pair Signed SIS File Nome Browse Browse Figure 2.23 Change the Certificate Key Pair in the...
The Cleanup Stack
If memory is allocated on the heap and referenced only by a stack-based local variable, what happens if a leave occurs For example, consider the following CAnotherClass theObject new ELeave CAnotherClass theObject- gt InitializeL Leave happens here theObject will be orphaned on the heap delete theObject This will never be called The memory allocated on the heap to store theObject will become inaccessible if the call to InitializeL leaves. If that happens, theObject can never be deallocated it...
Advanced Recipes Cls
Amount of time required 90 minutes Location of example code 3D animate Required libraries libgles_cm.lib Required header file s GLES egl.h Required platform security capability s None Problem You want to animate a 3D object that is, to make it move . Solution Animation in OpenGL ES is done by drawing the scene several times per second, modifying it a little bit every time. You can use an active object that regenerates its own request completion to continuously trigger redraw events Chapter 3...
File Handling
Almost all applications require access to the smartphone's file system. Many applications need to store a user's settings for example, a game may need to store high-score data a customizable dictionary application needs to store word entries. This section contains file system-related recipes, such as reading from and writing to the file. Symbian OS has a file server to handle all file-related aspects, such as creating, renaming, deleting and accessing files, creating and removing directories,...
Descriptors as Function Parameters and Return Types
As Sections 3.8.2 and 3.8.3 described, the TDesC and TDes descriptor base classes provide and implement the APIs for all descriptor operations. This means that the base classes can be used as function arguments and return types, allowing descriptors to be passed around in code transparently without forcing a dependency on a particular type. A function will simply declare whether a descriptor parameter should be modifiable or non-modifiable, and whether it should be 8 or 16 bits in width. It...
D Graphics Using OpenGL ES
OpenGL ES is the embedded software industry's standard of choice for displaying 3D graphics on the screen. It is a subset of the more widely known OpenGL standard, adapted to resource-constrained devices. You can find a link to the OpenGL ES specifications at the end of this set of recipes, in the Resources Section 4.6.6. There are not that many resources that cover OpenGL ES on Sym-bian OS, although you will find more information available in the recent Symbian Press book Games on Symbian OS A...
Tanzim Husain
Tanzim joined Symbian in 2004 as a member of the networking technology team and has worked there ever since, surviving two architectural changes and three team re-organizations. Before joining Symbian, he worked extensively on Windows Mobile, delivering pioneering applications in the areas of mapping and GIS. Tanzim holds a B.S. in Computer Science from NSU. Outside work, he likes to fiddle around with photography and enjoys escaping to the countryside. He tries to maintain an infrequently...
System Requirements
System requirements for C development on Symbian OS v9.x are as follows Microsoft Windows 2000 Professional with Service Pack 3 or MS Windows XP Professional with Service Pack 2, running on a laptop or desktop computer. At the time of writing this book, most Symbian OS SDKs do not support Windows Vista. At least 512 MB of RAM 1.5 GB recommended . 1-GHz or faster Pentium-class processor 2-GHz Pentium-class processor recommended . At least 1 GB of free disk space 5 GB recommended . 16-bit color...
Telephony
On earlier versions of Symbian OS, to access telephony services, it was necessary to use a number of different specialized classes, not all of which were available in the public SDKs. On Symbian OS v9, telephony is accessed using a convenience class called CTelephony. Some alternative classes can be used instead of CTelephony, such as RConnectionMonitor available in S60 , but you will find that they actually require more platform security capabilities and this may prevent you from experimenting...
LocationBased Services
Location-based services LBS offer the opportunity to extend applications, including, for example location-stamping artefacts such as photographs and notes, finding nearby services and facilities, Location-based services are enabled by the use of global positioning. The global positioning system GPS is a global network of at least 24 satellites orbiting Earth 24 hours a day. It provides positioning, navigation and timing PNT services for military and civil needs and is available all over the...
Why Does PushL Leave
In the examples above, you may have noticed that PushL is a leaving function, which at first sight appears to be self-defeating. If the cleanup stack is supposed to make pointers leave-safe, how can it cause a leave when you call it and yet still be helpful The reason PushL may leave is that it may need to allocate memory to store the pointers passed to it and in low-memory conditions this could fail . However, the object passed to PushL will not be orphaned if it leaves. This is because, when...
Changing the CertificateKey Pair
By default, Carbide.c creates a self-signed certificate key pair when creating a SIS file. A self-signed certificate is sufficient for many applications. However, there are cases when you need to apply for a developer cerificate at Symbian Signed www.symbiansigned.com , for example when using the Location API see Section 4.10 . The developer certificate allows your application to use restricted APIs that cannot be accessed using a self-signed certificate. Follow the instructions below to change...
Generating the Hello World Project
Follow the instructions below to create a new Hello World project. 1. From the Carbide.c main window, select the File New Symbian OS C Project menu. 2. On the New Symbian OS C Project dialog, select Quick Recipes on Symbian OS gt Hello World see Figure 2.3 . 0 Banc conicle application EXE J Bam. dynamically linked libraiy DLL 0 Banc static library LIB Empty Project Tor Symbian 0 Quick Recip on Symbian OS gt Hello World i SGO 3rd Edition 3id-Futuie Ed. GUI Application with LR Deiiqnei This...
Easy Recipes 1
Location of example code PIM ContactWriteNewField Required library s cntmodel.lib Required header file s cntdb.h, cntitem.h, cntfield.h, cntfldst.h Required platform security capability s ReadUserData WriteUser-Data Problem You want to add a text field to an existing contact item. Solution Modifying a contact data is not difficult in itself. You could think of it as executing an SQL UPDATE statement. Several of the next recipes in this section will show you ways of finding a contact to modify....
Modifying the Project Files
A Symbian OS project is represented by a build configuration file known as a bld.inf file and one or several project MMP files. Most examples in this book have only one MMP file. Both bld.inf and MMP files are ASCII text files. Carbide.c provides a user interface to edit them visually see Figure 2.15a . They can also be edited using the standard text editor see Figure 2.15b . a An MMP file in the GUI editor b An MMP file in the text editor Figure 2.15 Editing an MMP File using Carbide.c a An...
Multimedia
These recipes discuss aspects of working with multimedia files, such as playing and recording audio or video. Symbian OS provides a framework called MMF Multimedia Framework which supports the following audio playing, recording and conversion video playing and recording. The MMF is an extensible framework that allows phone manufacturers and third parties to add plug-ins to provide support for audio and video formats. For the application developer, it provides APIs that abstract the underlying...
Fundamental Data Types on Symbian OS
Symbian OS defines a set of fundamental types which, for compiler independence, are used instead of the native built-in C types. These are provided as a set of typedefs as shown in Table 3.1, and can be found in the Symbian header file e32def.h. The fundamental Symbian OS types should always be used instead of the native types that is, use TInt instead of int and so on . However, there is one exception, which is that you should always use void when a function or method has no return type,...
Easy Recipes
Amount of time required 10 minutes Location of example code Files Required library s efsrv.lib Required header file s f32file.h Required platform security capability s None Problem You want to get a handle to a file server session. Solution The file server handles all aspects related to files. It runs in its own process, EFILE.EXE. To call any API relating to file operations, you need a handle to a file server session, and must use class RFs, which is declared in f32file.h. The library name is...
List of Recipes
Read from and Write to a File Stream Force a Connection to Use a Specific Force a Connection to Use a Specific 4.5 Graphics and Drawing 194 4.5.1.1 Draw Lines and Shapes 197 4.5.1.2 Draw Background Color or Fill a Shape 198 4.5.1.3 Load and Draw MBM or MIF Images 199 4.5.1.4 Draw an Image with a Transparent 4.5.2 Intermediate Recipes 201 4.5.2.1 Load a JPG or PNG Image 201 4.5.2.2 Draw Text to the Screen 203 4.5.2.4 Draw Controls Inside Another Control 206 4.5.3 Advanced Recipes 208 4.5.3.1 Use...
Required platform security capabilitys Location Cii
Problem You want to obtain extended location information. Solution In addition to the general position classes, there are two other position classes TPositionCourseInfo and TPositionSatel-liteInfo. The latter class inherits from the former. TPositionCourseInfo incorporates a TCourse object, which provides information about the current speed at which the device is moving, the device's direction in terms of bearing, and also the accuracy of these parameters. In turn, TPositionSatelliteInfo...
Advanced Recipes Xjz
4.5.3.1 Use Off-Screen Images for Drawing Amount of time required 15 minutes Location of example code Graphics_Images Required library s efsrv.lib, bitgdi.lib, ws32.lib Required header file s f32file.h, bitstd.h, bitdev.h, w3 2std.h Required platform security capability s None Problem You want to implement double-buffering to ensure flicker-free graphics. Solution Double-buffering is an established technique for drawing flickerfree graphics. It is an essential idiom used for rendering fluid...
Intermediate Recipes How
4.8.2.1 Retrieve the Phone Number from an Incoming Outgoing Call Amount of time required 15 minutes Location of example code Telephony Telephony_Dialer Required library s etel3rdparty.lib Required header file s etel3rdparty.h Required platform security capability s ReadUserData Problem You want to get the phone number of an incoming outgoing call. Solution To retrieve a remote phone number from an incoming call, the call needs to be at least in the ringing state. To retrieve a remote phone...
Advanced Recipes Record Audio
Location of example code Multimedia AudioRecording Required libraries mediaclientaudio.lib Required header file s MdaAudioSampleEditor.h Required platform security capability s UserEnvironment Problem You want to record audio from the device microphone or telephone downlink. Solution The class to record audio is CMdaAudioRecorderUtility. Here are the steps to record audio Create a new instance of CMdaAudioRecorderUtility, which implements MMdaObjectStateChangeObserver. Open the file by calling...
Dynamic Descriptors HBufC and RBuf
The HBufC and RBuf descriptor classes are used for dynamic string data whose size is not known at compile time, and for data that cannot be stack-based because it is too big. These classes are used where malloc'd data would be used in C. The HBufC8 and HBufC16 classes and the neutral version HBufC, which is typedef'd to HBufC16 provide a number of static NewL functions to create the descriptor on the heap. These methods may leave if there is insufficient memory available. All heap buffers must...
Timers and Callbacks
The RTimer class provides a very useful service and one of the simplest ways of making an asynchronous request is to use an active object RTimer After is the asynchronous request and RTimer Cancel is used to cancel the request if, for example, the application is closed before the kernel completes the request. RTimer AtUTC is a good way to implement alarms on your phone and RTimer Inactivity can be used both to save battery life and to prevent the phone's keyboard and screen from locking....
Common Problems with Active Objects
The most common problem when writing active objects is when you encounter a stray signal panic E3 2USER-CBASE 46 . These occur when an active scheduler receives a completion event but cannot find an active object to handle it. Stray signal panics are notoriously extremely difficult to debug. Stray signals can occur because CActiveScheduler Add was not called when the active object was constructed. SetActive was not called after submitting a request to an asynchronous service provider. You...
Embedded Binaries
You can package a SIS file within another SIS file, just like any other binary. What this does is effectively embed the SIS file within the enclosing SIS file. At installation time, when the instruction to install the embedded SIS file is reached, the installation of other files within the enclosing SIS file is automatically interrupted in order to install the embedded SIS. At first sight, this doesn't really seem like a particularly important feature. One could ask, why not copy-and-paste the...
trap and trapd Macros
The TRAP and TRAPD macros can be used to 'catch' a leave and to extract the leave code integer. If a leave occurs in a function called within a TRAP, control will return immediately to the TRAP harness macro. The TRAP macro requires that the integer variable has been defined beforehand, while TRAPD defines the variable for you. The following code shows how to trap a leaving method If an error happened, handle it here. Alternatively, using TRAPD, the code is expressed as follows If an error...
Intermediate Recipes 1
4.3.6.1 Listen for an Incoming Connection Using TCP Location of example code Networking TCPListen Required library s esock.lib, insock.lib Required header file s es_sock.h, in_sock.h Required platform security capability s NetworkServices Problem You need to listen for an incoming connection using TCP. Solution Use RSocket Listen and RSocket Accept on an opened socket to listen for incoming TCP requests and establish connection with a remote peer. include lt es_sock.h gt RSocketServ, RSocket et...
Leaves and Exception Handling
Leaves can be thought of as the equivalent of exception handling on Symbian OS. Think of them as using just one exception class, and simply including an integer known as a 'leave code' inside the exception to identify its cause. Tip Symbian OS v9 also supports C standard exceptions. This makes it easier to port existing C code to Symbian OS. However, even if your code only uses standard C exceptions, leaves are a fundamental part of Symbian error handling and are used throughout the system, so...
Easy Recipes Axi
4.3.5.1 Send Receive Data Using TCP Sockets Location of example code Networking TCPSendReceive Required library s esock.lib, insock.lib Required header file s es_sock.h, in_sock.h Required platform security capability s NetworkServices Problem You want to send and receive data using TCP sockets. Solution Use RSocket Connect to connect to a remote peer and use RSocket Send and RSocket RecvOneOrMore to exchange data with the remote peer. RSocketServ, RConnection et al. link to esock.lib include...
Handling a Menu Event
1. Open data HelloWorld_01.rls to add the string that is going to be displayed when the menu item is selected. The two lines above added two strings to the localization file for UK English language. The first string is used as the title for the notification dialog and the second one is used as the content. 2. Open data HelloWorld_string.rss to add resources that point to the two strings above. The lines above added two string resources with the maximum length of 256 characters. 3. Open src...
Symbian Press Books
Symbian Press has published a range of books for beginners and advanced developers, and project managers. The following titles are a few examples that may be of interest if you are, respectively, new to Symbian OS, looking for a definitive Symbian C reference book, working on UIQ 3, a games developer or a project manager. Developing Software for Symbian OS, 2nd edition, by Steve Babin, is an excellent place to start if you have not used Symbian C before. It guides you through the basics,...
TwoPhase Construction
Consider the following code, which allocates an object of type CExample on the heap and sets the value of foo accordingly CExample foo new ELeave CExample The code calls the new operator, which allocates a CExample object on the heap if there is sufficient memory available. Having done so, it calls the constructor of class CExample to initialize the object. But if the CExample constructor leaves, the memory already allocated for foo and any additional memory the constructor may have allocated...
Recipes
4.4.5.1 Initialize your Application to Use Messaging Location of example code Messaging SmsManager Required libraries msgs.lib, smcm.lib Required header file s msvapi.h, smsclnt.h, msvids.h, smut.h Required platform security capability s Platform-dependent see example code Problem You want to start using messaging services. Solution We open a session with the message server and create member variables for classes which are heavy on RAM usage, like CMsvEntry and CSmsClientMtm. Description It is...
The RVCT Compiler
While the free GCC-E compiler produces EABI-compatible binaries that can be used for Symbian OS v9 application development, it cannot be used when developing code that runs kernel-side such as device drivers . Developers working within Symbian, and in Symbian's licensee or partner companies, opt instead to use the Real View Compilation Tools RVCT , available, at a charge, from ARM. In fact, if you want optimal code, when compared to GCC-E, the RVCT compiler binaries give better performance and...
Easy Recipes Rcj
Amount of time required 40 minutes Location of example code 3D Basic Required libraries libgles_cm.lib Required header file s GLES egl.h Required platform security capability s None Problem You want to take over the whole screen to display 3D objects. Solution Since we are going to display things on the screen, it just makes sense to run all our code inside the standard Symbian OS application framework.The application view is a CCoeControl and you can use the associated RWindow to initialize...
Required platform security capabilitys LocalServices
Problem You want to discover the Infrared-enabled devices in range. Solution To get the list of available IR-devices in range, you can use the ESOCK classes RSocketServer and RHostResolver declared in es_sock.h. For IrDA protocols the code is quite simple and is presented below. For Bluetooth it is a bit more complicated, as you will see in further recipes. As a first step, you need to fill in the TProtocolDesc structure which defines an address family and a protocol number. RSocket-Serv...
File Server Plugin Separate File System
By now, you already know that file access operations are centralized in the system's File Server process. Symbian OS allows you to create plug-ins for this file server to overwrite default behaviors. This feature is commonly used to protect parts of the file system through encryption, in case the handset is lost or stolen, but could also be useful for RAID data duplication or networked storage, and so on. As you can easily imagine, you will require a high level of platform security capability...
Intermediate Recipes
Amount of time required 40 minutes Location of example code PIM ContactSort Required library s cntmodel.lib Required header file s cntdb.h, cntitem.h, cntfield.h, cntdef.h Required platform security capability s ReadUserData WriteUser-Data Problem You want to sort the contacts in the database, by name, in alphabetical order. Solution What you want is a collection of TContactItemId objects. The elements are sorted according to your criteria. Once returned, the collection can be used to retrieve...
Acknowledgments
The authors would like to thank the Symbian Press team for allowing us this opportunity, for their patience and for making the process as smooth as possible. The authors would also like to thank all the technical reviewers for their invaluable comments and for stopping us from making fools of ourselves. Michael would like to thank my fellow authors on this book for making me look cleverer than I am, the kind people at Symbian Press for entrusting this project to a new author, David Wood for...
Externalize and Internalize
For an object to be written to a stream, its class must implement an ExternalizeL method, while for an object to be read from a stream, its class must implement an InternalizeL method. Here is an example of a class which supports both internalization and externalization void ExternalizeL RWriteStream amp aStream const void InternalizeL RReadStream amp aStream TInt iIntVal TBuf lt 64 gt iBuffer Assume we have the code for the rest of the class void SampleFuncL TAny aMemPtr, TInt aMaxLen...
Platform Security Data Caging
The Symbian OS file system is partitioned to protect system files critical to the operation of the phone , application data to prevent other applications from stealing copyrighted content or accidentally corrupting data and data files personal to the user which should remain confidential . This partitioning is called data caging. It is not used on the entire file system there are some public areas for which no capabilities are required. However, some directories in the file system can only be...