Handling Stylus Events
Stylus events can be detected using the Canvas class, which provides developers with methods to handle pointer events Canvas.hasPointerEvents indicates whether the device supports pointer press and release events e.g., when the user touches the screen with a stylus . indicates whether the device supports pointer motion events e.g., when the user drags the pointer . Canvas.pointerDragged int x, int y is called when the pointer is dragged. Canvas.pointerPressed int x, int y is called when the...
Series x Secure Sockets
Series 60 2.x adds some new classes to handle secure sockets. The main one is CSecureSocket, which is instantiated from an RSocket handle to represent a secure socket. Its API is derived from the new mixin interface MSecureSocket. The main shortcoming from Series 60 1 .x that is addressed by the new API is the lack of notification when the secure handshake completes. In Series 60 2.x, the handshake is initiated explicitly by means of an asynchronous function, and the corresponding Active Object...
Example SMS receiver
def message_received msg_id box inbox.Inbox appuifw.note uNew message s box.content msg_id app_lock.signal box inbox.Inbox box.bind message_received print Waiting for new SMS messages app_lock e32.Ao_lock app_lock.wait print Message handled The Inbox object's bind function binds a callback function to an event that is generated by an incoming message. In this example, the function message_received is called when a new message arrives. The callback function takes one parameter, namely the ID of...
Symbian OS kernel architecture
With those design goals in mind, we designed an operating system whose architecture, at the highest level, looked like that in Figure 1.1. You can see the major building blocks of the kernel. I've also included two other key system components that are usually considered to be part of the operating system, and that I will cover in this book the file server and the window server. I'll cover each of these building blocks and give you an idea of its basic functionality. The main function ofthe...
The Picture Puzzle
This case study describes a simple game that uses the Mobile Media API to take photographs using a camera phone. The sample MIDlet also illustrates using the RMS store to save, load and delete persistent records and makes use of a TiledLayer from the Game API. The Picture Puzzle MIDlet is a variation on the familiar Mix Pix native application that ships on Nokia Series 60 phones. In this sample MIDlet we use the on-board camera to capture a snapshot that acts as the original image. The MIDlet...
Receiving Messages
Symbian OS-based phones typically provide support for several different messaging technologies - built-in applications allow users to send and receive email, SMS and MMS messages. It is possible for third-party applications to use and extend this messaging functionality in order to add new and innovative features. Some possible messaging-aware applications might include an email management application that filters and arranges received email messages a subscription service that receives a news...
Polling
Avoid using loops that poll. The following is a snippet of code that polls the keepRunning flag. printText String just displays String in a UI component. printText Started while keepRunning Running the loop increased battery consumption from 66 mA to an unacceptable 163mA on my Psion Series 5MX unfortunately there is no easy way of monitoring battery consumption on more recent mobile phones . The battery consumption returned to 66 mA when keepRunning was set to false. Further, loops like this...
Executable Files
The EXE file is the basic executable image file for Symbian OS and all processes reside in one. For example, in Symbian OS v9 and above, GUI applications are EXE files. In Symbian OS releases before v9, a GUI application was actually a DLL, and was launched transparently from an EXE file called apprun.exe. You may need to implement your own EXE files for non-GUI processes as well, such as if you implement a server. The following example shows a simple EXE Tint ExtGlobal 0 ok to use here in EXE...
Enter Java ME on Symbian OS
Once you've read Part Two, you can proudly claim that you understand Java ME on Symbian OS. Thinking about it, why can't you do that already As you noticed, no new tricks were mentioned in Chapter 2. Java is Java, ME is ME and it is all too familiar. Even suspiciously familiar How can Java ME on Symbian OS be the same as everywhere yet more than anywhere And at the same time Well, it is true Just to confirm again, Java ME on Symbian OS is still Java ME. Only, there's much more Chapter 2 defined...
MMAPI and the MIDP Security Model
For reasons of privacy the following Mobile Media API calls are restricted under the MIDP 2.0 security model see Mobile Media API Specification 1.1 Maintenance Release at http jcp.org. locator stream type . Under the MIDP 2.0 security model, a signed MIDlet suite which contains MIDlets that make use of these APIs must explicitly request the appropriate permission in its MIDlet-Permissions attribute. The required MIDlet-Permissions attribute entries in the JAD file or manifest are as follows...
Debrief Summary
So far we have discovered two important concepts regarding game development with Java ME It is really easy to write Java games. It is really easy to write Java games badly. This is not all that surprising. The vast majority of mobile phones in the mass market at the time MIDP 2.0 was designed had a number of built-in limitations. So MIDlets did not have much memory, little local storage space and were rarely paused. Few mobile-phone operating systems are multitasking and MIDlets that lose focus...
The USB client LDD
The class DLddUsbcChannel is the USB client LDD channel object - an instance being created for each main interface that is set on the UDC. It is derived from logical channel base class DLogicalChannel - which means that channel requests are executed in the context of a kernel thread. A DFC queue is associated with the controller object, and this determines which kernel thread is used to process these requests. It is set on a per-platform basis, with the default being DFC thread 0. The channel...
Capturing any Key Event on Your Phone
The keycapture module offers an API for global capturing of key events. With this module, you can react to key events even if some other S60 application is active and your PyS60 program is running only in the background. For instance, you could have a key combination that triggers an action regardless of the application that you are using on the phone. The keycapture module provides a KeyCapturer object that is used for listening to the events by way of a callback function. The callback is...
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...
If Else Endif
The IF ELSE ENDIF construct is the third great building block of computing languages. At many points in your program, you'll have to check something and then execute different commands depending on the outcome. To check things you use the IF command. Hopefully, you should by now be able to make a good guess no pun intended as to what this code is attempting to do. If the variable Guess equals 1, then go to a procedure called GuessRight . If Guess equals 2, then go to a procedure called...
Martin Tasker
Martin joined Psion in 1995 after 13 years in the system-software industry. His first commercial software products were a graphics package and debugger for the BBC Micro in its early 1980s heyday, produced while studying Natural Sciences and Computer Science at Cambridge University. On graduation, he joined IBM where he worked in networking and storage management for eight years, programming mainframes in assembler, working on product development, and delivering performance, routing and...
The Descriptor Classes
In this section, we look closely at all of the descriptor classes. There are 12 descriptor classes available for the programmer to use. These are divided into three types buffer, pointer, and heap. Buffer descriptors contain their data buffers in the descriptor classes themselves their class names begin with TBuf. Pointer descriptors contain a pointer to a data buffer located outside the descriptor their names begin with TPtr. Heap descriptors are used for managing descriptors on the heap. Heap...
The execution model
When a device driver is loaded and a channel is opened to it, it is ready to handle requests. EKA2 provides two device driver models, which are distinguished by the execution context used to process requests from userside clients. In the first model, requests from user-side clients are executed in the context of these clients, in privileged mode. This functionality is provided by the DLogicalChannelBase class, as shown in Figure 12.4. DModeMChannel__ DLogicalChannelBase DModeMChannel__...
Evolution of Mobile Services
Mobile phone services and technologies have evolved rapidly, as has the global market for mobile phones, including significant cycles of boom and bust. Basic mobile network technologies have evolved from 'plain old' GSM through GSM Phase 2 , otherwise known as 2.5G GSM, GPRS, EDGE , to UMTS 3G, with similar evolutions from CDMA to 3G CDMA2000. Symbian OS has tracked these evolutions. It enables control of landline and mobile phone modems and supports wireless telephony standards for all...
Always Use an Active Scheduler
This can't be stated enough the multimedia subsystem cannot work without proper use of an active scheduler and associated active objects. Some APIs for example, within ICL explicitly use TRequestStatus to show asynchronous behavior and expect the client to drive them via an active object. With others, the behavior is callback-based and its asynchronous nature is hidden. Virtually all the APIs make extensive use of CActive-based active objects behind the scenes and need an active scheduler to...
JH Goldfuss
A description of how Symbian OS operates, manages hardware resources and provides services for application software is incomplete without an explanation of how it takes the hardware from an uninitialized, powered-off state to one in which the system is fully ready for action. In this chapter I will walk through the boot process for mobile phones that run the operating system from execute-in-place XIP Flash memory, such as NOR Flash, and then describe the differences needed to support non-XIP...
Toolkits
2.3.1.1 J2ME Wireless Toolkit 2.1 Overview The J2ME Wireless Toolkit 2.1 provides basic tools for developers to create MIDP 2.0 applications. The Wireless Toolkit WTK was created by Sun to facilitate MIDP development. At the time of writing, the production release can be obtained free of charge from Sun's website Amongst more advanced features, it provides the developer with the ability to compile, pre-verify and package MIDlet suites on the command line, as well as providing a simple GUI to...
Processing requests
The EKA1 version of the file server is single-threaded. This single thread processes all requests, for all drives. When the thread blocks, waiting on an I O operation on a particular drive, it is unable to process requests for any other drive. We took the opportunity to improve the file server design in EKA2. It is multi-threaded and allows concurrent access to each drive. As well as the main file server thread, there is normally a thread for each logical drive, and a thread for handling...
Naming Conventions
Like any system, Symbian OS uses naming conventions to indicate what is important. The Software Development Kit SDK and Symbian OS source code adhere to these conventions. Naming conventions are funny people tend either to love or hate them. Either way, I hope you'll find that the established naming conventions make understanding Symbian OS code much easier, and that, as these things go, they're not too burdensome. The fundamental rule is, use names to convey meaning. Don't abbreviate too much...
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...
Lucian Piros
Since joining Symbian, in January 2006, Lucian has worked with the PIM and Internet team on various releases of contact model architecture and has been involved in the latest contact model architecture design. Before joining Symbian, Lucian worked for two years as independent developer on core Symbian OS applications for a number of UI platforms based on Symbian OS. He has eight years industrial experience, most of them spent as a C programmer writing telecommunications applications. Educated...
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...
Capabilities for API Security
Platform security divides sensitive operating system functions into 20 named sets known as capabilities. You can think of each capability as a box of functions with a combination lock on it. An application can be given the combination for as many of these boxes as it is approved to use. In this way, capabilities provide for fine-grained control over API security. For an application to obtain a particular capability and use protected functionality i.e., for it to get the 'combination' it must be...
Features of an ECOM Interface
Let's start by considering the features of an ECOM interface As expected, the interface will define a set of pure virtual functions which a concrete instance will implement. In addition, the interface must also provide one or more factory functions that pass a cue to ECOM to enable it to instantiate an object of the correct implementation in the example below, the interface definition has two static NewL functions . The interface must also provide a means for its clients to release it, such as...
Test Driver
Considering the number of unit tests that need to be run on a device to ensure the quality of any production code being released, you will need to give yourself the means to achieve this as smoothly and as swiftly as possible. Running test code on a device and getting the results of the tests fed back to the developer so that he or she can process and use them can be a mammoth task if undertaken manually. In this particular case, automation is the solution and Test Driver provides the...
Symbols
.hrh files 188 control IDs 289 resource scripts 96 and operators data exchange 412 data, internalizing and externalizing 432 when to use 438 _assert_always macro 174 _assert_debug macro 174
File Conversion
CMdaAudioConvertUtility shares many of the calls of CMda-AudioRecorderUtility. They both derive from CMdaAudioClip-Utility, although the reasoning for the common base class is now not very clear. The two classes cover very different use cases - CMdaAudioConvertUtility is typically used to copy from one file to another, with some format conversion action. It is different from the other APIs in this section in that it does not involve using the microphone or the speaker. Because of their shared...
Observer Pattern
The observer defines a one-to-many dependency between collaborating objects. The observer enables the partitioning of a system into observers that react when their subjects change state. It is used in many event-based systems to separate the event source from the event monitors. The observer design pattern is shown in Figure 3.5. The concrete observers attach themselves to the subject in a way that the subject knows which observers to notify when its state changes. The observers register...
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...
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...
Building a Menu System in OPL Code Cascading Menus
As well as separate menu cards, there is another way to present information in a menu. This is through the use of cascading menus. A cascade in this respect is a menu option that, when selected, will pop up a second list of menu options the user can choose from. To use this feature, you firstly define the cascading menu by using the mCASC command, in the same way as you would use the mCARD system. The title first string in mCASC must be the same text as the menu option that will call up the...
Acknowledgements
Some people told me it would be hard to write this book in and around my real job in the System Management Group at Symbian and a few promised me that it would be impossible. They were all right, of course, although none of them tried to stop me. Many thanks to Wiley and Symbian Press therefore for their patience as I've stretched deadlines. Thanks to Fredrik Josephson for saying 'yes' to my starting the book as a 10 task and for turning a blind eye when it grew beyond that and to Geert Bollen...
Deviceindependent Drawing
Device-independent drawing is largely conducted by the cExample-HelloView class. Here is its declaration class cExampleHelloView public cBase void SetTextL const TDesC amp aText void SetFullRedraw TBool aFullRedraw void DrawInRect const MGraphicsDeviceMap amp aMap, CGraphicsContext amp aGc, const TRect amp aDeviceRect, CFont aFont const Firstly, note that it's derived from CBase, not CCoeControl. No CCoeControl-derived class can be device-independent, because controls are heavily tied to the...
Handling Input from the Screen
Some UIQ smartphones, such as the Sony Ericsson P1i, support touchscreen input, which can be used to add another mode of user interaction to a game. Screen events can be detected and handled in much the same way as keypad input, by overriding CCoeControl HandlePointer-EventL as shown below. In the example given, to capture events that occur in the close vicinity of a particular point on the screen, an area of the screen is constructed, ten pixels square, and centered on the point in question....
Handling Input from the Keypad
Handling user input made by pressing keys on the phone's keypad is quite straightforward in the Symbian OS application framework. The application UI class should call CCoeAppUI AddToStackL when it creates an application view to ensure that keypad input is passed automatically to the current view. The key events can be inspected by overriding CCoeControl OfferKeyEventL . Note that only input from the numerical keypad and multi-way controller is passed into CCoeControl OfferKeyEventL . Input from...
Packaging a MIDlet
Following the above steps is sufficient to build simple MIDlets for running in the emulator. However, if you are developing a more sophisticated MIDlet that contains many classes, images, application parameters, and so on, you need to package your MIDlet into a MIDlet suite. Packaging creates a JAR file containing all your class and resource files such as images and sounds and the application descriptor JAD file, which notifies the AMS of the contents of the JAR file. The following attributes...
Playing
The Series 60 Platform includes three player classes for different purposes one for playing sinewave tones, one for playing WAV sound clips and other supported formats, and one for streaming audio. The support for additional audio formats is done by media server plugins. Currently, in Series 60 there is a plug-in for polyphonic MIDI songs. All playing requests have to have a priority. Through the priority value, Media Server chooses the client that has the highest priority to play and gives the...
Playing Tone Sequences
Playing a tone sequence is akin to playing an audio file see Section 5.3 but sequence files are inherently simpler. Not only is no controller required but the sequence is decoded in the adaptation layer. Although the use case is similar to that of playing audio files, the calling pattern is similar to that of playing DTMF or tones. There are several ways of playing a tone sequence provide the tone sequence in a descriptor provide a filename that contains the tone sequence data use RFile Open to...
Exe and shared library
- static resolution of call Exe and provider library Binary code when linked from various object code files into an executable has its function calls between modules resolved. When the code runs function calls are direct transfers of control. A static interface library shared library provides a fixed API that can be used by one or more programs and have the extension .dll. A polymorphic interface library provider library implements an abstract API. They usually have a single entry point that...
main body of the function
Some types of error are due to bad programs. When this type of error is discovered, the thread with the erroneous program should be terminated. In Symbian OS, this is a referred to as a panic. The only proper response to a panic is to fix the program with the error. Typically, a panic is not discovered by the program that made the error, but by some library code which operates on behalf of that program. If the library code is in a DLL running in the same thread as the program, it may use the...
Figure Analysis of one function with new IDS
But how to create those IDS files I had to create on my own using the idsutils for IDA and the following procedure with a little of automation . 1. Download the Symbian SDK from the Nokia site for example from 3 2. Download ActivePerl and install it, as requested to install the SDK see the readme inside 4. Go to the and copy all the .lib files A mirror is also available at 7.0 S60 LIB files.rar 5. Launch on any of it the lib files the program ar2idt.exe or use an automation tool like for...
Updating Events using the Eventful API
The Eventful Web API is used to retrieve events according to the user's preferences. Titles of the retrieved events are presented in a list, like the one that is shown in Figure 9.2 b . The list is constructed by the function update_list that is presented in Example 92. lprefs 'app_key' APP_KEY, 'page_size' '10' appuifw.app.title uUpdating s prefs.get 'Location', url SEARCH_URL urllib.urlencode lprefs events json.read res 'events' 'eventl listbox.set_list titles appuifw.app.title prefs...
Drive Mapping
The emulator maps features of the target machine onto features of the PC environment. For software development, it is particularly important to know how the emulator maps drives and directories onto your PC's file system. On a Symbian OS phone, there are two important drives see Figure 10.1 Z is the ROM, which contains a bootstrap loader and all the EXE, DLL and other files required to boot and run Symbian OS and its applications. All files on Z are read-only program files are executed directly...
The Document Class
The class definition for the Noughts and Crosses document class, listed below, provides the implementation of CreateAppUiL , which is always required. In addition, it implements persistent storage of the game's state in the StoreL and RestoreL functions, using the principles described in Chapter 7. class COandXDocument public CAknDocument static COandXDocument NewL CEikApplication amp aApp virtual COandXDocument From CEikDocument CEikAppUi CreateAppUiL void StoreL CStreamStore amp aStore,...
Linking in the Cards Class
We are now ready to link in the cards class. Copy the header file into the source directory and the include directory. We use a deck of cards in the AppUi class. Include the cards.h file into the header file of the Container and add a pointer to a deck of cards into the Container class as below The deck needs to be instantiated. We can add a new method, StartGame , to initialize the card game iPlayerWins iPhoneWins 0 iDeckOfCards CCards NewL 2 Here we see the addition of two new variables,...