1 Description
This document describes the salient features and their differences among symbian 8 and symbian 9 application development.
· Assumptions
· Project file
· Resource files
· Application startup
· Exe, dll,
· Active object
· Client-Server.
2 Assumptions
All estimations are done with an assumption that the developer has enough experience (3-4 years) in working with symbian applications and understand the application development cycle thoroughly.
Wherever symbian 8 is mentioned it should also be assumed about versions bellow 8.
3 Introduction
Symbian 8 and symbian 9 differs because of and after the introduction of platform security. Platform security brings in changes in mmp file, resource files and the way applications are installed and with what capabilities. Capability is an access token that corresponds to permission to access critical system components. In symbian 8 there is no platform security available.
The difference between sym8 and 9 in the application development are categorized in this document as mmp file changes, resource file changes, application startup changes, changes in app, exe, and dlls, active objects and server components.
3.1 Project file
3.1.1 Mmp file in Symbian 8
The project files used in application development are bld.inf and
The bld.inf file lists the mmp files in the project under PRJ_MMPFILES key word. It can also contain the targeted platforms under PRJ_PLATFORMS.
There is no difference in the bld.inf file for both symbian 8 and symbian 9.
The mmp file syntax in symbian 8 is different from what is available in symbian 9.
The following list the main components/keywords in a symbian 8 mmp file. Lets see each keyword in the mmp files for both sym8 in detail.
TARGET news-qui.app
TARGET specifies the file name of the application that will be built after the build process.
TARGETTYPE app
Target type indicates the type of file generated by the project. Most common types are app, dll, exe, mdl etc.
UID 0x100039CE 0x101F81D9
UID key word specifies two applications UIDs, which is used to identify the type of application/project and the application unique id. This id should be obtained from symbian. The first value identifies the type (here as application) and the second is the unique id obtained from symbian. For symbian 8 UIDs are allocated in the range 0x10000000 - 0x1FFFFFFF.
TARGETPATH \system\apps\news-qui
This is an optional key word that specifies the target path of the build output. This path is different for each the target type. For exe it is system\programs, for recognizers it is system/recogs etc.
SOURCEPATH src
Source path specifies the path of the source file listed against SOURCE. And SOURCE lists the specific files. Similar explanation holds true for INCLUDEPATH and USERINCLUDE. SYSTEMINCLUDE specifies the system include path to be used for the compilation.
RESOURCE news-qui.rss
RESOURCE specifies the resource file to be used by the resource compiler. This is required especially for UI applications. An application can have more than one with each one containing 4K of resources.
LIBRARY
LIBRARY lists the import libraries for the application. The build will generate link errors if you don't specify all the libraries you need.
AIF news-qui.aif src news-qui-aif.rss c8,1 news-qui.bmp news-qui-mask.bmp
This line specifies the name of the aif (short for application information) file to build (news-qui.aif), its location (src), the resource file associated with the aif file (news-qui-aif.rss), the bitmap and mask which are used for the application's icon, and their colour depth (8 bits per pixel, colour for the bitmap, 1 bpp for the mask). Aif files specify the application's caption, icon, capabilities and the MIME types associated with it. There will be a default one created if nothing is specified.
The UID value will be 0 for an exe.
3.1.2 Mmp file in Symbian 9
In symbian 9 there is no major difference in the bld.inf file form what is available in symbian 8.
Let’s now list out the key work which has a different meaning/not available/newly introduced in symbian 9.
TARGETTYPE exe
This indicates the type of file generated by the project, in this case an executable. The most common target types are dll, exe and plugin
UID
In symbian 9 the UIDs are separated in to two sections, protected range and unprotected range. Both these ids are to be obtained from www.symbiansigned.com. The unprotected ids need not be unique in a system and the developed application need not be signed. Any UID values less than or equal to 0x7FFFFFFF are classed as "protected" and are only intended for use with signed applications. The software installer will refuse to install an unsigned application if it uses a package UID in the protected range. New UID allocations (shown below) will start from 0x20000000 for the protected range, and from 0xA0000000 for the unprotected range. The old UID can also be used for non trusted and unsigned application. One just needs to replace the first digit with F for this. Please not that this application cannot be used for signing at a latter stage and required a trusted UID, if it is to be signed.
SECUREID
A Secure ID (SID) is a special use of a UID. In Symbian OS v9 each executable has a SID which, unless explicitly specified by the SECUREID keyword in the application's MMP file, will default to be the same value as the application's UID3. The SID value is not relevant for DLLs as a process's SID will always be that of its EXE. This is used to determine which private directory a process can access and identify it as a caller, for example, when making client-server requests. To avoid confusion, it is recommended that a SECUREID not be specified in the application's MMP file; instead UID3 always be specified.
VENDORID
A VID can be used as a runtime mechanism to check that a binary comes from a particular source. VIDs are allocated to Symbian licensees, partners, operators and Independent Software Vendors through sign-up programs, for instance Symbian Signed. If an application needs a VID its installation package must be signed as described in the Application signing section. Unsigned applications have no vendor ID since without a signature it cannot be verified.
CAPABILITY
A capability is a unit of protection, or privilege and, in Symbian OS 9.1, used to restrict use of the API to callers with at least that same level of privilege. The capabilities that an executable/application is assigned are listed following the capability keyword. If the CAPABILITY keyword is not present in the .mmp file, the default of CAPABILITY NONE is used.
For a process running without AllFiles capability, nothing in the \sys\ directory is visible, and the only directory under \private\ that can be seen is \private\
SOURCEPATH, SOURCE, SYSTEMINCLUDE and USERINCLUDE are the same as symbian 8.
START RESOURCE…END
The above keyword is used to specify a resource file containing text and specifications of user interface elements. These keywords replace the RESOURCE statement used in mmp files prior to Symbian OS v9.1. The START RESOURCE keyword indicates the beginning of a block which provides information about how an application resource file is to be compiled. At least one of these is needed if the application has a UI. The resource file itself should be the same location as the mmp file itself or in the directory specified by the last preceding SOURCEPATH declaration.
The end of the information block is indicated by the END keyword and an application may have several resource files, each of which is specified separately using the START RESOURCE…END block.
TARGETPATH
TARGETPATH is used to specify the build location for a compiled resource. The location of the first compiled resource file is specified as \resource\apps, which is a public, read-only directory and is the standard location for resource files. The registration file is built to \private\10003a3f\apps. There is no longer any need to specify a target path for the executable in the mmp file and it will be ignored except when used within a START RESOURCE…END block.
An application registration file defines information about an application that is required by the application launcher or system shell. This includes the application’s name, UID, and properties. Other information used by the shell, for instance the icons and captions, is defined separately; the location of the icon/caption definitions is provided in the registration file. Before Symbian OS v8.1, all of this information was provided by aif files. In Symbian OS v8.1, both aif files and registration files are supported, but from Symbian OS v9 (S60 3rd Edition) onwards, only registration files are supported.
HEADER
This is an optional keyword which, when used, causes a resource header file (.rsg) to be created in the system include directory, \epoc32\include\.
START BITMAP…END
This section contains the bitmaps for application icons and specifies how to compile bitmap (.bmp) files into a Symbian OS format multi-bitmap (.mbm) file. Different sizes of source bitmap should be supplied for different view sizes.
EPOCHEAPSIZE min max
Use the epocheapsize statement to specify the minimum and maximum sizes of the initial heap for a process. The default sizes are 4 KB minimum and 1 MB maximum. The minimum size specifies the RAM that is initially mapped for the heap's use. The process can then obtain more heap memory on demand until the maximum value is reached. The sizes can be specified in decimal or hexadecimal format. Memory is allocated in pages, so the minimum and maximum values are rounded up to a multiple of the page size (4 K).
EPOCSTACKSIZE min max
Use the epocstacksize statement to specify a stack size for your executable other than the default 8 KB. In Symbian 8 there are no min/max values for this. The size of the stack, in bytes, can be specified in decimal or hexadecimal format. Use of this statement will have no effect under the WINSCW/WINS platforms. EPOCSTACKSIZE allows you to specify a stack size for your executable file, therefore enabling you to override the default (8KB). EPOCSTACKSIZE should be included in the MMP file, e.g., EPOCSTACKSIZE 0x5000. Note: The overridden value can be specified in decimal or hexadecimal format.
3.2 Resource file
Many elements of a user interface, for instance dialogs, toolbars, menu bars and menu panes, are easiest to define not in C++, but through a Symbian OS-specific resource language. The resource files are compiled into a compressed binary form using the Symbian resource compiler.
3.2.1 Resource files in symbian 8
There three main files in the resource category, the
Dialogs, list boxes, menu items, query dialogs and also other string data (localizable) are stored in rss file.
An application can support multiple resource files. The resource compiler and the RResourceFile class provide two mechanisms to support these requirements. The NAME statement allows a four-letter short name to be defined for a source file; this name is converted into a 20-bit value, represented by five hex digits. This value is referred to as the offset. If the digits are 0xabcde, then resource ids are allocated in sequence 0xabcde001, 0xabcde002, 0xabcde003 ... 0xabcdefff, rather than the usual 0x00000001, 0x00000002, 0x00000003 ... 0x00000fff (decimal 4095). A resource file signature, which must be the first resource in the file, contains a reference to itself: this may be used by the RResourceFile class to identify the 20-bit offset for resource ids, because the first resource id will be 0xabcde001.
Localizable strings are usually put in .lxx files, where xx defines the language code. These files will be included in the rss file
Resource files come under the RESOURCE key work in the mmp file.
3.2.2 Resource files in symbian 9
There are no differences in the way resource files are used in symbian 8 and symbian 9. But in symbian 9 due to platform security, a set of new resource files are introduced and aif files are removed.
Resources are added to a project by including them within START RESOURCE...END blocks within the project's mmp file.
A new resource file
This file includes the name of the application binary, UID and properties, the MIME types it can handle, and the location of the localisable registration information (built from
The
3.3 Application startup
3.3.1 Application architecture in symbian 8
Application framework provides frameworks for launching an application and also a rich set of control classes which the application can use at runtime. A typical application will have 4 components,
The Application: derived from CEikApplication, instantiated by the framework, this class initializes the rest of the application. For series 60 the application class is CAknApplication.
The Document: derived from CEikDocument. All applications have a CEikDocument-derived class and by default CEikDocument will create a default document file the first time an application is run. However, not all applications are file based. That is, they may not need to offer the user the ability to create, open, or edit documents. In such non-file-based applications, such as the Telephone application, the instance of the document class is little more than a shell required by the framework to create an instance of the AppUi class and typically a model/engine instance. In file-based applications the document class also manages the saving and restoring of data from persistent storage. In s60, CAknDocument is used.
The UI: derived from CEikAppUi, this class provides major functionality to all applications such as event handling, control creation, access to many useful system calls, etc. The CEikAppUi-derived class is typically responsible for creating one or more application views. S60 UI class is CAknAppUi providing support for event handling, CBA, status plane and view architecture integration.
CAknViewAppUi: This class is used in s60, for view based application, this is derived from CAknAppUi.
Prior to symbian 9 all applications were polymorphic dlls and a typical start-up code will look as follows.
GLDEF_C TInt E32Dll(TDllReason){
return KErrNone;
}
EXPORT_C CApaApplication* NewApplication()
{
return (new CMyApplication);
}
3.3.2 Application architecture in symbian 9
The underlying classes and their relationships are valid for symbian 9 too, but there are important differences from symbian 8.
The application framework in previous releases supported many types of plug in, including GUI applications that were implemented as polymorphic DLLs. Under platform security, this simple use of polymorphic DLLs is avoided, as:
1) The polymorphic DLL would need security capabilities as least as great as its loading process (which would be high). This could unnecessarily restrict who could use the framework.
A solution is to change the DLL to be an EXE, which can run as a process with just those security capabilities it needs.
2) Frameworks used to search a directory (or directories) to find polymorphic DLLs. With platform security, all binaries are located in \sys\bin\, and only processes with the AllFiles capability are able to read from that location. This means that most processes are not able to scan for binaries themselves.
The solution is to change the DLL into an ECom plug in. ECom provides a means for plugins to register that they exist and that they support a particular interface, and a means for processes to discover and load appropriate plugins.
The API for starting the application framework is in eikcore.dll, so eikcore.lib needs to be listed in the LIBRARY section of the MMP file.
A typical application startup code will look like as follows.
#include
LOCAL_C CApaApplication* NewApplication()
{
return new CExampleApplication;
}
GLDEF_C TInt E32Main()
{
return EikStart::RunApplication(NewApplication);
}
Even embeddable applications are written as ECom plugins.
3.4 dlls and Ecoms
A static interface dll export functions that can be called by other code that builds against its header file and links against its import library. Abstraction and modularization can be achieved by designing the system as a collection of separate units, where the units are built as dlls.
A polymorphic interface DLL exports a single factory function only at a well known location, usually at ordinal #1. Calling this function creates an instance of the newly derived framework class.The api is defined as a single abstract class,, whose functions are pure virtual. The dll implements this abstract class by deriving from it. RLibrray class can be used to load a dll. The entry function of the RLibrray gives the return from the ordinal 1 of the dll.
For a polymorphic DLL, the first UID component always has the value KDynamicLibraryUidValue. The second UID component is used to verify that the DLL satisfies the protocol defined by the programming interface. Indeed, this UID identifies that protocol. The third UID component is used to identify a specific implementation; the use of the third component UID depends on the protocol. The use of UIDs in DLLs provides a guarantee that the loaded DLL is the correct type. This prevents files which just happen to have the right name from being loaded inadvertently.
Symbian supports polymorphic dll loading by ordinal only. Module definition file lists the exported function of the dll, is used to insert the ordinal info to the dll export table.
ECom is considered as an alternative to polymorphic dll, and is available from symbian 7.0 onwards.
Polymorphic DLLs required each framework that uses them to provide its own mechanisms for clients to discover and instantiate the available implementations. ECom removes this duplication of functionality by introducing a generic framework that provides single mechanisms to:
· register and discover interface implementations
· select an appropriate implementation to use
· provide version control for plug-ins
The ECom framework provides facilities to resolve and load the appropriate implementations at run-time, on behalf of the interface definition. This is a client –server mechanism, with only one client per thread. The client side RECommSession is used to create, list and destroy implementations and server controls access to the registry of implementations, used to resolve and load the correct implementation.
In polymorphic dlls, for an interface a there can be only one implementation. I there are multiple implementations, the clients should load all the polymorphic dlls and resolve the one they want to use based on non standard methods.
Ecom provides this resolving of interfaces dynamically by the framework itself. Ecom does this by allowing the implementations (concrete classes) to export an array of factory functions by which the implementation can be created, publish a compiled resource file which lists the implementations and their properties.
For example:
Interface definition a, can be made in to a dll, by deriving a class from a and generating a polymorphic dll of the derived class. A client can take the include file for the interface. The polymorphic dll should be loaded with RLibrary class and a name/uid of the dll. The exported function @ ordinal 1 will return an object of the interface class and the client can use it. If there are multiple implementations of the dll, the client should find the appropriate dll and load it.
In case of Ecom, The interface uses Ecom to load an appropriate implementation based on the parameters passed on to the interface definition. The Ecom framework identifies the implementations with the implementation resource structure. If there resolving of the correct implementation is to be changed from the default way, the interface should provide a custom resolver. The implementation proxy structure contains the implementations creation functions (NewL).
There are no architectural difference in which the ECom functions in sym8 and sym9. Due to the introduction of platform security, the installation directories and UIDs are different as explained elsewhere in the document.
3.5 Client-Server
Using client server framework, a program can provide services to multiple other programs and also handle resources on behalf of multiple clients. Many important Symbian OS system APIs use the client/server framework to provide services to client programs. The api has 4 key concepts, server, session, sub session and message.
Client/server is usually chosen, rather than a conventional shared library, to provide services when one or more of the following is required: management of shared system resources; asynchronous services; protection offered by running in a separate process from clients.
A client/server implementation supplies a server program executable, and a .DLL containing the client-side interface. Client-server communication requires context switching.
3.5.1 Client-Server in symbian 8
Server is responsible to establish connection, manage connections, create session’s etc. All servers have a name which is passed to the server when it is started. A client finds a server through its name.
A session is a channel of communication between client and server. To make a server request, the client sends a message to the server over the session. The message includes a 32-bit request type code, and up to four 32-bit parameters. All client-server communication is mediated by the Kernel.
The client session interface is RSessionBase and at the server side CSession and CSharableSession. The sub-session presents a efficient refinement of a session when a client wants multiple simultaneous uses of a server.
The base client-side sub-session interface is provided by RSubSessionBase. An implementation derives from this to define the functions that it wants to expose to clients. Each sub session is created using CObject class, held in CObjectCon created and help by CObjectConIx class. All the above classes are owned by CServer.
A server implements a corresponding sub-session class based on CObject from the Reference Counting Objects API.
The message is the data structure passed between client and server. It contains the code specifying the type of client request, and four 32-bit data parameters. Clients do not use messages directly as they are encapsulated in client-side session and sub-session interfaces. Server-side sessions and sub-sessions read client data from messages, and write data back to them to be returned to the client. RMessage class is used for this.
3.5.2 Client-Server in symbian 9
Even though the underlying principles are same, new APIs have been introduced as part of the effort to provide a more securable interface for client/server communications, and form an essential component of Platform Security in Symbian OS. Both versions of apis are available and the old version can be disabled by macro __HIDE_IPC_V1__
In Version 1, the two different share modes existed for historical reasons. All sessions created with new Version 2 servers behave like the Version 1 auto attach sessions; there is no explicit attach sharing mode. The new ShareAuto() function should be used to replace all occurrences of Share().There is no explicit attach mode in the Version 2 API.
Version 1 send and receive was done through a c style array of 4 of type TAny, but version 2 introduced TIpcArgs packaging for sending data.
Server connection now takes RMessage2 argument to check security aspects.
In Version 2, a server's interaction with its clients is channelled through RMessagePtr2, from which RMessage2 is derived. An RMessagePtr2 object acts as a handle to the message that the client has sent, the same class provides functions to panic, reading descriptors etc, which were part of RThread in version 1.
No comments:
Post a Comment