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...
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...
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...
RLibrary API Class
Symbian OS provides an API class called RLibrary to load and invoke DLL functions dynamically at runtime. The import library uses this API to access the DLL and so it's instructive to have a quick look at this class, even though the import library shields you from needing to use it. The key methods of RLibrary are Load and Lookup . The Load method is used to load a specific DLL and associate it with the class. The Lookup method will look up the DLL function with the ordinal value passed to it....
The MMP File
SimpleEx_reg.rss private 10 003a3f apps euser.lib apparc.lib cone.lib eikcore.lib This section describes some of the main MMP file statements. You should consult the Tools and Utilities guide in Symbian OS Library that comes with the SDK documentation for a complete list and description of MMP statements. TARGET program_name specifies your program's executable file name, for example TARGET myprocess.exe TARGET myfuncs.dll targettype type specifies the type of executable that is to be created....
Process Names
Each process has an ASCII name associated with it. The default name for a process is the name of the EXE file that contains it, minus the directory path and the .exe extension. You can open a handle to a process by its name using Open TDesC amp aName in RProcess. Note, however, that the system automatically appends a UID and instance number to the name of the process, and you must supply this full name to Open TDesC amp aName for it to succeed. This can make opening a process by name using Open...
Resource Classes R classes
Resource classes are used to control objects that are implemented and owned somewhere else. For example, client classes in a client-server structure are implemented as resource classes that just hold a handle to the actual resource, which is controlled by the server. Furthermore, the Symbian OS API provides numerous resource classes that allow user programs to control objects that are owned and implemented by the kernel threads, processes, mutexes, and memory chunks are examples of this ....
Resource File
Now, let's create the resource file to define the UI elements - in this case the menu softkey item used to display the alert dialog. The following shows the resource files for S60 and UIQ-enter the one corresponding to your platform into a file called SimpleEx.rss, and place it in the group directory. The resource file for S60 3rd Edition is as follows S60 SimpleEx Resource File NAME SIMP include lt eikon.rh gt include lt avkon.rh gt include lt avkon.rsg gt include SimpleEx.hrh RESOURCE TBUF...
Supporting Multiple Languages
While you can put text strings directly within the resource file as I have done in the examples, this is not recommended if you need your application to support different languages. Symbian recommends that you put all your strings into a RLS file, and then include this string file using include in your RSS file. There should be a separate RLS file for each language you support. Each string in the RLS file is defined using the rls_string keyword. For example rls_string STRING_r_example_start...
Dynamic Arrays
Symbian provides a set of classes for implementing dynamic arrays. Like descriptor arrays, dynamic arrays are based on dynamic buffers, and are thus expandable. However, unlike descriptor arrays, templates are used so that the array can contain items of any data type, as defined by the user. A wide assortment of dynamic array classes exists. Here is a sample of them CArrayFixFlat lt class T gt Holds fixed-length objects of type T and uses a flat dynamic buffer. CArrayFixSeg lt class T gt Holds...
Basic Data Types
To provide machine and compiler independence, Symbian OS provides a set of data types that should be used in place of the standard C types, such as int, long, and char. Tint, TUint An integer whose size is the natural machine word length at least 32 bits . These are mapped to int and unsigned int . Tlnt8, Tlnt16, Tlnt32 Signed integers of 8, 16, and 32 bits, respectively. TUint8, TUint16, TUint32 Unsigned integers of 8, 16, and 32 bits, respectively. Tlnt64, TUint64 A 64-bit integer, which is...
Introducing the GUI Framework
The main components of the GUI architecture and their relation to each other are shown in Figure 3.7. Near the bottom of the diagram, we see the window server, which provides centralized access to the screen and user input devices across all applications. As the name implies, the window server is a server process - applications act as calling clients to this server by linking to its client-side library ws32.dll. The window server handles the details of drawing window and control objects to the...
Naming Conventions
Symbian OS has a set of naming conventions that should be used when developing Symbian OS software. The operating system itself uses these for its APIs and data. Naming conventions make code easier to understand and aid correct usage of classes and variables. For example, code such as the following which appears to be pushing member data to the cleanup stack, since the 'i' prefix indicates a member variable should be regarded with suspicion This is because you should never push a class member...
Creating an Active Object Class
To create an active object, declare a class and derive it from CActive, as in the following example static CMyActive NewL CMyActive void InvokeAsyncFunc Some method to invoke the active object's associated asynchronous function. CMyActive void ConstructL Overriden from CActive virtual void RunL handles asynchronous function completion virtual void DoCancel Cancels an outstanding asynchronous function call virtual Tint RunError TInt aErr overridden to handle a leave that occurs in RunL Then,...
Build Some Examples
The SDKs include example projects with source code to help you get familiar with Symbian OS. It's a good idea to build and run some of these to test out, and get familiar with, the SDK. In the next few pages, I'll run through compiling and executing examples for the emulator, platform by platform from the command line. Although you likely will be using Carbide.c to build Symbian OS code, it's also a good idea to get familiar with building on the command line. I'll then provide some steps for...
Format of the PKG File
To create a SIS file you need to define a PKG file for your project, which is used to specify the contents of your SIS file. First I will discuss the basic statements in the package file using a simple illustrative example, then I will talk about some of the more advanced features. A minimum PKG file has two lines describing the application and the target smartphone device. These lines are followed by one or more lines that specify what files on the development PC go in the package file, and...
Header Files
This section describes the main header file for our example Sim-pleEx.h , defined for S60 and UIQ platforms and the header file it includes SimpleExUid.h . Put the header file for your particular platform in a file named SimpleEx.h and place it in the include directory e.g., SimpleEx S60 include for the S60 headers . The following is this header for S60 3rd Edition include lt eikenv.h gt include lt eikon.hrh gt include SimpleEx.hrh include lt akndoc.h gt include lt aknapp.h gt include lt...
Canceling Outstanding Requests
Each asynchronous function has a cancel function associated with it. This cancel function causes its corresponding asynchronous function to abort its operation and complete right away, with its TRequestStatus variable set to KErrCancel. For example, the API class RTimer provides the asynchronous function method RTimer After TRequestStatus amp aStatus, TTimeIn-tervalMicroseconds32 aWait .After the specified time has elapsed, this function will change aStatus to KErrNone and send the completion...
Simple Descriptor Example
Before describing the descriptor classes in detail, let's look at a simple string example - comparing its implementation both in C and in Symbian OS using descriptors. The example implements a function called MakeName , which concatenates the string passed as its argument to the string literal Name , and prints the results. Note that the goal of this example is just to introduce a few C string and descriptor differences and not to show the best way to implement the actual functionality of the...
Linked Lists
Class TDblQue lt class T gt can be used to create a double-linked list of objects of type T. The class that the array contains must have a member variable of type TDblQueLink contains the forward and backward linked list pointers . Then when you construct the TDblQue, you specify the offset of the TDblQueLink member variable in the constructor. construct list, supply offset of link member variable TbdlQue lt CMyObj gt linkList _FOFF CMyObj,iLink Objects are added to the linked list with...
Active Scheduler Error Handling
A leave can occur in your active object's RunL method as indicated by the L suffix to indicate an error. By default, a leave in RunL will generate a panic, but you can change this behavior for your active object by overriding CActive RunError . Additionally, you can override the default error handling of all active objects belonging to the active scheduler by customizing the active scheduler Error method - however, this is not often done. ACTIVE SCHEDULER ERROR HANDLING CActive RunError is...
ARM and THUMB instruction set
ARM supports both a 32-bit instruction set, known simply as ARM, and a 16-bit instruction set, known as THUMB. The ARM instruction set is for maximum performance, but with the sacrifice of some added code size, while the THUMB instruction set produces the most compact code, but at some sacrifice to performance. In Symbian SDKs before Symbian OS v9, there were separate build targets to specify the ARM and THUMB instruction sets. However, with Symbian OS v9, this is no longer the case. Now, the...
Code Layout
You'll notice that the curly bracket layout in Symbian OS code, used throughout this book, is to indent the bracket as well as the following statement void Only allow one request to be submitted at a time Caller must call Cancel before submitting another _LIT KAOExamplePanic, CNotifyChange User Panic KAOExamplePanic, KErrInUse iFs.NotifyChange ENotifyAll, iStatus, iPath SetActive Mark this object active
Application Registration Resource File
GUI applications are EXE files in the sys bin directory in Symbian OS v9 and in order for the device to recognize an executable as a GUI application, and to display them on the desktop for user selection, the application must be registered via a special resource file known as a registration resource file. The compiled registration resources are placed in the private 10003a3f import apps directory on the device. The source file names are typically lt application name gt _reg. rss. The user will...
Digital Signing Overview
Digital signing is a way of marking a file such that a receiver of the file can be assured of the file's source and integrity. Digital signing acts like a traditional written signature with the added feature of ensuring that the file was not modified after the file was signed. Digital signing is a part of the public key infrastructure PKI , which protects data by assigning a person or company a key pair consisting of a public key and a private key. The public key is widely distributed, while...
Active Object Example
To illustrate active objects, I'll present an example based on the SimpleEx program presented in section 2.3. The original SimpleEx displays 'Simple Example' in the middle of the screen. When you select a menu item called 'Start', it displays an alert dialog indicating that Start was selected. The example will be expanded here to include an active object. The Start menu item is changed so that, when selected, it starts a countdown of 10 seconds - displaying the progress of the countdown on the...
Setting and Retrieving Process Arguments
As mentioned in the previous section, you can pass a command line argument to your process via the second argument of RProcess Create . For example _LIT KMyExeFileCmd,arg1 arg2 RProcess proc proc.Resume start the process running This will pass the argument string argl arg2 to the process created. To retrieve the entire command string argument within the process itself, you can call User CommandLine as the following shows TBuf lt 200 gt cmdLine User CommandLine cmdLine Or you can use the class...
What Makes a Good Smartphone OS
Smartphone devices have certain characteristics that are different from traditional desktop computers, and that must be addressed by a smartphone operating system. Smartphones should be small, have long battery life, and cost as little as possible. To meet these requirements, smartphones, like other mobile devices, have limited memory and processing power compared with desktop PCs and laptops. The operating system must be frugal in using hardware resources - especially memory. Not only must the...
Templates in Symbian OS
Before I cover arrays, now is a good time to look at how templates are used in Symbian OS. Let's begin with a quick review of C templates in general. Normally in C , specifying a variable's data type is done at compile time and thus remains fixed while a program is running. This can be limiting in many cases. For example, if you want to create a list class where you do not care what type of objects are on the list, yet want to implement a common set of operations on them, then you would either...
Thread Priorities
A thread's priority can be set relative to the priority of its owning process or to an absolute priority, independent of the priority of its owning process. Thread priorities are set by the SetPriority method. Symbian OS defines the following process-relative priorities The default thread priority is EPriorityNormal, which means that the thread's priority is the same as that of the owning process. The other values indicate a thread's priority in relation to the priority of its owning process....
ontinueCancel
Figure 7.2 Warning with Untrusted Signature To prevent the display of this warning dialog, it is necessary to have a certificate issued by a Symbian Certificate Authority. This is achieved by applying to the Certificate Authority for a Publisher Id. Following a vetting process that confirms the identity of the applier the Publisher Id is issued. The Publisher Id contains the certificate and key file that is used to identify the source of the application. When an application issigned with...
Thread Synchronization
Being able to execute code in parallel, using threads, is a powerful feature, but it would not be very useful if there was no way to synchronize between them. After all, running in parallel is efficient-but without any coordination between the parallel strands of execution, chaos would result. Symbian OS provides several API classes for synchronization of threads. In this section I will briefly cover four basic thread-synchronization functions semaphores, mutexes, critical sections, and the...
Opening an Existing Thread
As in the case of a process, a handle to an existing thread can be opened by either name or ID using the RThread Open method. The following code will open the thread created in the previous example, and just to create interest , if it is still running, will suspend it. At this point the thread will be suspended until a Resume is performed. _LIT KMyThread, MyThread Tint rc thd.Open KMyThread if thd.ExitType EExitPending thd.Suspend thd.Resume continue thread execution Unlike processes, the...
Avoid StraySignal Panics
Any Symbian programmer who has developed active objects will probably have encountered a E32USER-CBase 46 panic. This is the stray-signal panic and it is invoked by the active scheduler's event loop when it receives a signal at the thread's request semaphore, but cannot find an active object that it belongs to i.e., no active objects with iActive ETrue AND iStatus KRequestPending . There are many situations that can cause this. Here are just a few Not adding your active object to the scheduler...
How is the DEF file used
With freezing enabled, each DLL project is associated with a DEF file see the note at the end of this section for how it is associated that defines where the abld freeze writes to. The build then uses this DEF file in the following situations When the DLL is built, the project's frozen DEF file is consulted. The linker will ensure that all functions specified in the DEF file will remain at the same specified ordinal position, ensuring backward compatibility with the import library produced...
Server Implementation
Following is the server's include file tbuffserver.h , which contains the server and session class definitions 1 Note also that system server names start with ' ', which are considered protected names. A server needs the ProtServ extended capability to have a name that starts with ' '. This protection is in place to prevent third-party servers from impersonating system servers. EInvalidCommand, EInvalidDescriptor, EServerlnitError const Tint KMaxTextBufferSize 4096 class CTextBuffServer public...
Process Priority
Each process is assigned a priority value. The kernel uses process priorities to decide which process to switch to when more than one process is ready for execution at a time. Use SetPriority in RProcess to set the priority for a process. The priority can be one of the following from the TProcessPriority enum As an example, the following line changes the priority of the current process to the highest priority By default, the RProcess class constructor opens a handle to the currently running...
Types of Control
This section gives a tour of some of the main control types. It is not exhaustive, but the SDK documentation contains a complete list of available controls. Edit controls allow the user to enter a piece of data of a specific type. A wide variety of edit controls exist, including text editors, number editors, calendar editors, date and time editors, duration editors, secret editors, PIN editors, color editors, IP address editors, and more. For example, we have seen the text editor, which uses...
Descriptors for Strings and Binary Data
Descriptors are classes that represent data buffers and allow you to safely access them. Symbian OS uses descriptors to store and manipulate strings as opposed to NULL-terminated C strings , as well as to manage binary data. Descriptor classes, although containing many features, are optimized for minimal overhead, since they are designed to run on memory-constrained devices. You'll need to thoroughly understand descriptors in order to develop Symbian OS code, since they are so widely used. In...
Requisite lines
You can use a requisite line to specify that a particular component must already be installed in order for the current installation to continue. It has the following format This means that the component with the specified UID and Product Name, with a version number not earlier than the one specified, must exist for the installation to continue. For example indicates that a component named MyDll, with UID 0x10000123 and a version number of at least 1.0.0, must exist already before installation...
Network Programming Using Sockets
The goal of a good networking API is to hide the underlying details of the network and allow you to connect to a remote host and transfer data easily. This section introduces the concepts of network sockets and how to program using them. The socket programming interface originated from BSD Unix as a generic API for Inter-Process Communications. Since then it has become the standard for network programming. Virtually all operating systems that support TCP IP have some sort of socket API,...
Symbian Signed Process Options
The outcome of the signing process is an application SIS file to which Symbian's 'root' digital signature has been appended in the form of a certificate, and which has in turn incorporated the digital signature of the developer, thus 'binding' the developer's identity to the application. Or, in the case of the freeware and Publisher Certifier routes to signing, binding the publisher's identity to the application. At install time, the application certificate is verified against the Symbian root...
Leaves and TRAP Harnesses
To solve the problems just mentioned, Symbian OS provides an exception-based error handling and recovery mechanism based on leaves and trap harnesses. When an error occurs, the software invokes a leave, which causes the function to exit immediately. Control returns to the calling function, which, if no trap harness exists, will also exit at that point. This process continues up the calling chain until a trap harness is encountered, at which time the error is handled. Figure 4.2 illustrates this...
The Use of Semaphores in Symbian OS
Symbian OS automatically creates a semaphore, known as a request semaphore, for each thread on creation. This request semaphore is the basis of the Symbian asynchronous request functionality used by the active object framework, described in the previous chapter, which is in turn used in the client-server framework. When an asynchronous function completes, the calling program's request semaphore is used to signal to the calling program that the function which is running in a separate process...
Descriptor Arrays
Descriptor array classes implement arrays of TDesC-based buffer descriptors. The purpose of these classes, in most cases, is to implement an array of strings. For example, a list box keeps its list of selection item strings in a descriptor array. Descriptor arrays use dynamic buffers to store their data. Therefore, the array size does not need to be preallocated, as it is for a fixed array. The array is expanded as needed when new data items are added to it. Descriptor arrays can be flat or...
The Communication Architecture
Communication is key to smartphones, and Symbian OS contains an extensive and flexible communication architecture to support it. This section looks at the Symbian OS communications architecture. Chapter 11 will discuss communications in more detail, as you learn to develop communication applications. This section and Chapter 11 assumes some basic knowledge of network communications. For more information, see Symbian OS Communications Programming, Second Edition. Figure 3.8 shows the main...
Network Programming Using Active Objects
As you've seen, I used User WaitForRequest to wait for the asynchronous socket functions to complete in the previous section. However, a better way to call these socket functions is within active objects, which were discussed in Chapter 8. The active object framework allows the system to handle events, such as those arising from user input, while the socket functions are active. When they complete, the associated active object's RunL method handles events as appropriate. So the Connect call,...
Basic Capabilities
Basic capabilities, also known as user grantable capabilities, represent device functions that are easy enough to comprehend so that a user can reasonably choose whether to accept or reject an application's access to them. These functions are not dangerous as far as causing damage to the system or its data, but they can cause unexpected operation and compromise user data if abused. Examples of functionality controlled by basic capabilities are accessing the phone network, sending an SMS, or...
Removing an Active Object
The base class destructor removes the active object from the active scheduler's list. However, the base destructor requires that no asynchronous event should still be pending-if there is, it generates an E32USER-CBase 40 panic. Therefore the destructor in your derived class should call the Cancel method as well as any other cleaning up it needs to do . If you want to remove an active object from the active scheduler, but not destroy it, call CActive Deque . This will call the active object's...
Test House Certification
The process to get your application signed via a test house is as follows 1. Get a Publisher ID from TC TrustCenter if you do not already have one . 2. Sign your application with the Publisher ID. 3. Submit your application through http www.symbiansigned.com, selecting a third-party test house. 4. Handle any problems found by the test house. 5. Upon passing of the tests, they send you the signed application. Let's look at the steps in more detail. Before you can submit your application to a...