You are previewing Porting to the Symbian Platform: Open Mobile Development in C/C++.
O'Reilly logo
Porting to the Symbian Platform: Open Mobile Development in C/C++

Book Description

If you want to write mobile applications without the idioms of Symbian C++, have existing software assets that you'd like to re-use on Symbian devices, or are an open source developer still waiting for an open Linux-based device to gain significant market penetration, this is the book for you!

Beginning with an introduction to the native programming environments available and descriptions of the various technologies and APIs available, you will first learn how to go about porting your code to the Symbian platform.

Next, you will discover how to port to Symbian from other common platforms including Linux and Windows.

Finally, you can examine sample porting projects as well as advanced information on topics such as platform security.

The author team consists of no less than six Forum Nokia Champions, together with technical experts from the Symbian community, either working on Symbian platform packages or third party application development. With this book, you will benefit from their combined knowledge and experience.

In this book, you will learn:

  • How to port and make use of existing open source code to speed up your development projects

  • How to port applications from other popular mobile platforms to the Symbian platform

  • How to write code that is portable across multiple platforms

  • The APIs in the Symbian platform for cross-platform development, such as support for standard C/C++ and Qt.

Table of Contents

  1. Copyright
  2. About this Book
    1. What Is Covered?
      1. Terminology and Version Numbering
      2. Core Material
      3. Platform-Specific Porting Guides
      4. Porting Examples
      5. Advanced Topics
    2. Who Is this Book For?
    3. The Future of the Symbian Platform
  3. Author Biographies
    1. Mark Wilcox
    2. Lauri Aalto
    3. Will Bamberg
    4. David Caabeiro
    5. Ivan Litovski
    6. Gábor Morvay
    7. Lucian Piros
    8. Jo Stichbury
    9. Paul Todd
    10. Gábor Torok
    11. Vinod Vijayarajan
  4. Author's Acknowledgements
  5. Symbian Acknowledgements
  6. 1. Introduction
    1. 1.1. What Is Porting?
    2. 1.2. What Is Portability?
    3. 1.3. Why Port to Mobile Platforms?
      1. 1.3.1. The Marketing Angle
      2. 1.3.2. The Hacker's Reason
      3. 1.3.3. The Geek's Reason
    4. 1.4. Why Get Interested Now?
      1. 1.4.1. A Brief History of Digital Convergence
      2. 1.4.2. Birth of the Mobile Convergence Device
      3. 1.4.3. Inevitable Fragmentation
      4. 1.4.4. Reunification
      5. 1.4.5. A Tipping Point
      6. 1.4.6. Mobile Devices of the Future
    5. 1.5. Why Port to the Symbian Platform?
      1. 1.5.1. Market Share
      2. 1.5.2. Open Source and Royalty-Free
      3. 1.5.3. Maturity
      4. 1.5.4. Range of Hardware
      5. 1.5.5. Cross-Platform APIs
  7. 2. The Porting Process
    1. 2.1. Choosing a Project
    2. 2.2. Analyzing the Code
    3. 2.3. Re-architecting
    4. 2.4. Setting Up the Development Environment
      1. 2.4.1. System Requirements
      2. 2.4.2. Integrated Development Environment
      3. 2.4.3. SDKs and Plug-ins
      4. 2.4.4. Compilers
    5. 2.5. Integrating with the Symbian Build System
      1. 2.5.1. Build Process
      2. 2.5.2. Build Files
      3. 2.5.3. Packaging for Device Installation
      4. 2.5.4. Incremental Integration
    6. 2.6. Compiling
    7. 2.7. Fixing Problems
      1. 2.7.1. RAM
      2. 2.7.2. Storage Space (Flash Memory)
      3. 2.7.3. Processing Power
      4. 2.7.4. Battery Life
      5. 2.7.5. Screen Resolution
    8. 2.8. Running and Testing
    9. 2.9. Debugging
    10. 2.10. Re-integrating
    11. 2.11. Summary
  8. 3. Symbian Platform Fundamentals
    1. 3.1. In the Beginning
    2. 3.2. Naming Guidelines and Code Conventions
      1. 3.2.1. Capitalization Guidelines
      2. 3.2.2. Naming Guidelines: Prefixes and Suffixes
      3. 3.2.3. Class Names
        1. 3.2.3.1. T Classes
        2. 3.2.3.2. C Classes
        3. 3.2.3.3. R Classes
        4. 3.2.3.4. M Classes
        5. 3.2.3.5. Static Classes
    3. 3.3. Data Handling
      1. 3.3.1. Simple Data Types
      2. 3.3.2. Collection Classes
      3. 3.3.3. Native Data Collection Classes
        1. 3.3.3.1. Linked Lists
        2. 3.3.3.2. Circular Buffers
        3. 3.3.3.3. Maps and Sets
    4. 3.4. String Handling: Descriptors
      1. 3.4.1. Memory Management
      2. 3.4.2. Character Size
      3. 3.4.3. Descriptor Data: Text or Binary?
      4. 3.4.4. Symbian C++ Descriptor Classes
        1. 3.4.4.1. Baes Classes: TDesC and TDes
        2. 3.4.4.2. Pointer Descriptors: TPtrC and TPtr
        3. 3.4.4.3. Stack-based Buffer Descriptors: TBufC and TBuf
        4. 3.4.4.4. Non-modifiable Dynamic Descriptors: HBufC
        5. 3.4.4.5. Modifiable Dynamic Descriptors: RBuf
        6. 3.4.4.6. Literal Descriptors
          1. 3.4.4.6.1. _LIT macro
          2. 3.4.4.6.2. _L macro
      5. 3.4.5. Descriptor Indigestion?
      6. 3.4.6. Descriptors as Function Parameters
      7. 3.4.7. Using the Descriptor APIs
        1. 3.4.7.1. Which Descriptor Class Should I Use?
        2. 3.4.7.2. The Difference Between Length() and Size()
        3. 3.4.7.3. MaxLength() and Length Modification Methods
        4. 3.4.7.4. Des() Method
      8. 3.4.8. Overview
    5. 3.5. Error Handling and Memory Management
      1. 3.5.1. Leaves and Exceptions
        1. 3.5.1.1. What Is a Leave?
        2. 3.5.1.2. How to Identify a Leaving Function
        3. 3.5.1.3. What Causes a Leave?
        4. 3.5.1.4. Symbian Leaves and C++ Exceptions
        5. 3.5.1.5. Legacy Implementation of User::Leave()
        6. 3.5.1.6. Heap Allocation Using new(ELeave)
        7. 3.5.1.7. Trapping a Leave Using TRAP and TRAPD
      2. 3.5.2. Cleanup Stack
        1. 3.5.2.1. Which Class Types Risk Becoming Orphaned?
        2. 3.5.2.2. Using the Cleanup Stack
        3. 3.5.2.3. Why Is PushL() a Leaving Function?
        4. 3.5.2.4. Popping Items off the Cleanup Stack
        5. 3.5.2.5. Member Variables and the Cleanup Stack
        6. 3.5.2.6. Using the Cleanup Stack with Non-CBase Classes
          1. 3.5.2.6.1. CleanupStack::PushL(TAny*)
          2. 3.5.2.6.2. CleanupStack::PushL(TCleanupItem)
      3. 3.5.3. Leaves and the Cleanup Stack
      4. 3.5.4. Two-Phase Construction
      5. 3.5.5. Panics
    6. 3.6. Event-Driven Programming
      1. 3.6.1. Threads and Active Objects
      2. 3.6.2. Working with Active Objects
        1. 3.6.2.1. Construction
        2. 3.6.2.2. Submitting Requests
        3. 3.6.2.3. Event Handling
        4. 3.6.2.4. Error Handling
        5. 3.6.2.5. Cancellation
        6. 3.6.2.6. Destruction
    7. 3.7. Writeable Static Data
      1. 3.7.1. Usage
      2. 3.7.2. Global Destructors
    8. 3.8. Multiple Inheritance
    9. 3.9. Summary
  9. 4. Standard APIs on the Symbian Platform
    1. 4.1. P.I.P.S. Is POSIX on Symbian OS
    2. 4.2. Open C
    3. 4.3. The STLport, uSTL and Open C++
    4. 4.4. Which Version of Symbian OS?
    5. 4.5. How to Use the APIs
      1. 4.5.1. Before Symbian OS v9.3
      2. 4.5.2. Symbian OS v9.3 and Later Versions
      3. 4.5.3. Stack Size for Standard C++ and OpenSSL
    6. 4.6. Examples: SoundTouch and SoundStretch
      1. 4.6.1. Selecting the Project
      2. 4.6.2. Analyzing the Code
      3. 4.6.3. Porting the Build Files
      4. 4.6.4. Building the Projects
      5. 4.6.5. Running and Testing
    7. 4.7. Known Limitations, Issues and Workarounds
      1. 4.7.1. Files and File Attributes
        1. 4.7.1.1. Timestamps
        2. 4.7.1.2. Users and Groups
        3. 4.7.1.3. Execute Permissions
        4. 4.7.1.4. Buffering
        5. 4.7.1.5. Link Files
        6. 4.7.1.6. Memory-Mapped Files
        7. 4.7.1.7. Sparse Files
        8. 4.7.1.8. Devices
      2. 4.7.2. Memory Handling
        1. 4.7.2.1. Heaps
        2. 4.7.2.2. Internal Allocation
        3. 4.7.2.3. Out-of-Memory Errors
        4. 4.7.2.4. Stack Size
        5. 4.7.2.5. Stack Overflows
      3. 4.7.3. Process Creation and Inter-Process Communication
        1. 4.7.3.1. File Descriptor Inheritance
        2. 4.7.3.2. IPC Mechanisms
        3. 4.7.3.3. Signals
        4. 4.7.3.4. Access Permissions for IPC Objects
        5. 4.7.3.5. RPipe
      4. 4.7.4. Communications and Networking
        1. 4.7.4.1. COM Ports
        2. 4.7.4.2. Socket Options
        3. 4.7.4.3. Future Bluetooth Sockets
        4. 4.7.4.4. Internet Access Point Name Restrictions
      5. 4.7.5. Miscellaneous
        1. 4.7.5.1. Timers
        2. 4.7.5.2. Error Handling
        3. 4.7.5.3. The atexit() Function
        4. 4.7.5.4. System Configuration
        5. 4.7.5.5. Build Support APIs
        6. 4.7.5.6. Hardware Floating-Point Support in libm
        7. 4.7.5.7. Symbol Lookup via libdl
        8. 4.7.5.8. Interleaving P.I.P.S. and Native APIs
      6. 4.7.6. How Platform Security Affects Compliance
    8. 4.8. Summary
  10. 5. Writing Hybrid Code
    1. 5.1. Popular APIs You Can't Use Directly
      1. 5.1.1. User Interface APIs
      2. 5.1.2. Multimedia APIs
      3. 5.1.3. Mobile-Oriented APIs
        1. 5.1.3.1. Bluetooth
        2. 5.1.3.2. PIM
        3. 5.1.3.3. Telephony and Device Status
        4. 5.1.3.4. Messaging
        5. 5.1.3.5. Other Hardware Access
    2. 5.2. How to Create a Hybrid Port
      1. 5.2.1. Active Scheduler vs Main Loop
      2. 5.2.2. Error Handling
      3. 5.2.3. Interleaving Standard C/C++ and Symbian C++
      4. 5.2.4. Hybrid Application Architectures
    3. 5.3. Example: Guitune
      1. 5.3.1. Project Selection
      2. 5.3.2. Code Analysis
      3. 5.3.3. Architecture Changes
      4. 5.3.4. Development Environment
      5. 5.3.5. Creating the Project
      6. 5.3.6. Getting It to Compile
      7. 5.3.7. Getting It to Work
    4. 5.4. Summary
  11. 6. Other Port Enablers
    1. 6.1. Real-time Graphics and Audio Libraries
      1. 6.1.1. Limitations of the RGA Libraries
      2. 6.1.2. Uses of the RGA Libraries
      3. 6.1.3. Features of the RGA Libraries
        1. 6.1.3.1. Graphics APIs
          1. 6.1.3.1.1. Back Buffer
          2. 6.1.3.1.2. Bitmaps
          3. 6.1.3.1.3. Display
          4. 6.1.3.1.4. Fonts
          5. 6.1.3.1.5. Images
        2. 6.1.3.2. Multimedia APIs
          1. 6.1.3.2.1. Audio (High-Level and Compressed)
          2. 6.1.3.2.2. Camera and Video Playback
          3. 6.1.3.2.3. Lights
        3. 6.1.3.3. Utility APIs
          1. 6.1.3.3.1. Alerts
          2. 6.1.3.3.2. Device Capabilities and Device Status
          3. 6.1.3.3.3. Input
          4. 6.1.3.3.4. Runtime and Application State
          5. 6.1.3.3.5. Themes
          6. 6.1.3.3.6. Timers
          7. 6.1.3.3.7. Vibra
          8. 6.1.3.3.8. Virtual Code
    2. 6.2. Simple DirectMedia Layer
    3. 6.3. OpenKODE
      1. 6.3.1. OpenKODE Core
      2. 6.3.2. OpenGL ES
      3. 6.3.3. OpenVG
      4. 6.3.4. OpenMAX
      5. 6.3.5. OpenSL ES
      6. 6.3.6. The Future of OpenKODE
    4. 6.4. Qt
      1. 6.4.1. QtCore
      2. 6.4.2. QtGui
      3. 6.4.3. QtNetwork
      4. 6.4.4. QtOpenGL
      5. 6.4.5. QtScript
      6. 6.4.6. QtSql
      7. 6.4.7. QtSvg
      8. 6.4.8. QtWebKit
      9. 6.4.9. QtXml and QtXmlPatterns
      10. 6.4.10. Phonon
      11. 6.4.11. Platform-Specific Extensions
      12. 6.4.12. Using Qt
    5. 6.5. Summary
  12. 7. Porting from Mobile Linux
    1. 7.1. Major Players in the Mobile Linux Space
      1. 7.1.1. Maemo
      2. 7.1.2. Openmoko
      3. 7.1.3. Moblin
      4. 7.1.4. LiMo
    2. 7.2. Porting from Linux to Symbian
      1. 7.2.1. Basic Support
        1. 7.2.1.1. Open C/C++ Libraries
        2. 7.2.1.2. Open C Incompatibilities
        3. 7.2.1.3. Threading and Processes
        4. 7.2.1.4. IPC and Porting from DBus
        5. 7.2.1.5. CreateGlobal()
        6. 7.2.1.6. CreateLocal()
        7. 7.2.1.7. OpenGlobal()
        8. 7.2.1.8. Send()
        9. 7.2.1.9. Receive()
        10. 7.2.1.10. Wait for Messages
      2. 7.2.2. User Interface
      3. 7.2.3. Other Features
        1. 7.2.3.1. System Functions
        2. 7.2.3.2. Multimedia
        3. 7.2.3.3. Networking
        4. 7.2.3.4. Security
        5. 7.2.3.5. Database
        6. 7.2.3.6. Other APIs
    3. 7.3. Summary
  13. 8. Porting from Microsoft Windows
    1. 8.1. Architecture Comparison
    2. 8.2. Application Compatibility
    3. 8.3. Development Languages and SDKs
      1. 8.3.1. Development Environments
      2. 8.3.2. Building Applications
      3. 8.3.3. Restricted APIs
      4. 8.3.4. Coding Style
      5. 8.3.5. Debugging
    4. 8.4. SDKs and APIs
      1. 8.4.1. Comparing the Win32 API with Symbian APIs
      2. 8.4.2. Comparing the MFC/ATL Libraries with Symbian APIs
    5. 8.5. Porting an Application
      1. 8.5.1. Layered Design
      2. 8.5.2. Modular Implementation and Unit Testing
      3. 8.5.3. Refactoring an Application
      4. 8.5.4. Cross-platform Libraries
      5. 8.5.5. Common Platform Code
    6. 8.6. Windows-specific Issues
      1. 8.6.1. Unsupported Features
      2. 8.6.2. Windows Registry
      3. 8.6.3. Databases
      4. 8.6.4. Inter-process and Inter-thread Communication
      5. 8.6.5. Binary Executables and DLLs
      6. 8.6.6. Compiler Differences
      7. 8.6.7. Functions Exported by Ordinal
      8. 8.6.8. Code Signing
      9. 8.6.9. Capabilities
      10. 8.6.10. UIDs
      11. 8.6.11. Installer
      12. 8.6.12. Localization
      13. 8.6.13. Component Object Model
    7. 8.7. Signing and Security
      1. 8.7.1. Types of Certificate
      2. 8.7.2. Enforcing Security in Code
      3. 8.7.3. Signing Programs
      4. 8.7.4. Symbian Signed Test Criteria
      5. 8.7.5. Signing Process
    8. 8.8. Porting from C# and .NET
      1. 8.8.1. .Net and the Common Language Runtime
      2. 8.8.2. Libraries
      3. 8.8.3. Build Process
      4. 8.8.4. User Interface
      5. 8.8.5. Porting a .NET Application to Symbian
    9. 8.9. Summary
  14. 9. Porting from Other Mobile Platforms
    1. 9.1. Android
      1. 9.1.1. Development Environments Compared
      2. 9.1.2. Android and Symbian Compared
        1. 9.1.2.1. Event Broadcasting
        2. 9.1.2.2. Content Providers
        3. 9.1.2.3. Services
      3. 9.1.3. Deployment Compared
      4. 9.1.4. API Mappings
    2. 9.2. BREW
    3. 9.3. iPhone OS
      1. 9.3.1. iPhone OS and Symbian Compared
      2. 9.3.2. Porting Scenarios
      3. 9.3.3. Cocoa Foundation Framework and Qt Compared
        1. 9.3.3.1. Base Class
        2. 9.3.3.2. String Handling
        3. 9.3.3.3. Containers
        4. 9.3.3.4. Basic I/O
        5. 9.3.3.5. Networking
        6. 9.3.3.6. Threading at a Glance
      4. 9.3.4. Porting the User Interface
        1. 9.3.4.1. Tools
        2. 9.3.4.2. Initializing the Application
        3. 9.3.4.3. UI Building Blocks
        4. 9.3.4.4. Routing Widget-specific Events to Handlers
        5. 9.3.4.5. Variants of the Model–View–Controller Design Pattern
      5. 9.3.5. Mobile-Specific APIs
    4. 9.4. Summary
  15. 10. Porting a Simple Application
    1. 10.1. Selecting a Project
    2. 10.2. Analyzing the Code
    3. 10.3. Setting Up the Development Environment
    4. 10.4. Integrating with the Symbian Build System
    5. 10.5. Getting It to Compile
    6. 10.6. Getting It to Work
    7. 10.7. Extensions Specific to Mobile Devices
    8. 10.8. Deploying and Testing on Target Hardware
    9. 10.9. Re-integrating
    10. 10.10. Summary
  16. 11. Porting Middleware
    1. 11.1. GDAL
      1. 11.1.1. Selecting a Project
      2. 11.1.2. Analyzing the Code
      3. 11.1.3. Setting Up the Development Environment
      4. 11.1.4. Integrating with the Symbian Build System
      5. 11.1.5. Getting It to Compile
      6. 11.1.6. Getting It to Work
      7. 11.1.7. Re-integrating
    2. 11.2. Qt
      1. 11.2.1. Technology Previews
      2. 11.2.2. Incremental Porting
      3. 11.2.3. Architecture of Qt on the Symbian Platform
      4. 11.2.4. Integration with the Symbian Build System: qmake
      5. 11.2.5. The Route to a Working Application Framework
    3. 11.3. Summary
  17. 12. Porting a Complex Application
    1. 12.1. Selecting a Project
    2. 12.2. Analyzing the Code
    3. 12.3. Re-architecting
    4. 12.4. Setting Up the Development Environment
    5. 12.5. Integrating with the Symbian Build System
      1. 12.5.1. Expat
      2. 12.5.2. JSON-C
      3. 12.5.3. Exiv2
      4. 12.5.4. The Main Executable
    6. 12.6. Getting It to Compile
      1. 12.6.1. Compiling Expat
      2. 12.6.2. Compiling JSON-C
      3. 12.6.3. Compiling Exiv2
      4. 12.6.4. Refactoring the Application Core
      5. 12.6.5. Separating Out the User Interface
    7. 12.7. Re-writing the User Interface
    8. 12.8. Testing and Debugging
    9. 12.9. Re-integrating
    10. 12.10. Summary
  18. 13. The P.I.P.S. Architecture
    1. 13.1. The Glue Code
    2. 13.2. The Core Libraries
      1. 13.2.1. The Locale Subsystem (libc)
      2. 13.2.2. The stdio Subsystem (libc)
      3. 13.2.3. The Math Library (libm)
      4. 13.2.4. The Dynamic Linking Interface Library (libdl)
    3. 13.3. The Backend
      1. 13.3.1. The Stdio Server
      2. 13.3.2. The IPC Server
      3. 13.3.3. C Wrappers
      4. 13.3.4. The CLSI
      5. 13.3.5. The Backend Heap
      6. 13.3.6. File Table
      7. 13.3.7. Signal Management Server
    4. 13.4. Emulator Writeable Static Data Support
      1. 13.4.1. Using Writeable Static Data in DLLs on the Emulator
      2. 13.4.2. The EWSD Library
    5. 13.5. Summary
  19. 14. Security Models
    1. 14.1. The Capability Model
      1. 14.1.1. Capability Word Structure and Definition
        1. 14.1.1.1. User Capabilities
        2. 14.1.1.2. System Capabilities
      2. 14.1.2. Use of EXE Capabilities
        1. 14.1.2.1. Assignment of Process Capabilities
        2. 14.1.2.2. Process Capability Checking at IPC Boundaries
      3. 14.1.3. Use of DLL Capabilities
      4. 14.1.4. Working Out which Capabilities You Need
    2. 14.2. Process Identity
      1. 14.2.1. Secure ID (SID)
      2. 14.2.2. Vendor ID (VID)
    3. 14.3. Data Caging
      1. 14.3.1. Data Caging and Removable Media
      2. 14.3.2. Sharing Data Securely
    4. 14.4. Code-Signing and Certification
      1. 14.4.1. Digital Signatures
      2. 14.4.2. Certificates and PKI
      3. 14.4.3. Digital Signatures for Software Authentication
    5. 14.5. Certification and Platform Security
      1. 14.5.1. Trusted Applications and Secure EXE Identity
      2. 14.5.2. Trusted Applications and Capability Assignment
      3. 14.5.3. Untrusted Applications
      4. 14.5.4. Certifying Trusted Applications
        1. 14.5.4.1. Publisher ID
        2. 14.5.4.2. Express Signed
        3. 14.5.4.3. Certified Signed
    6. 14.6. Development Code
      1. 14.6.1. Open Signed Online
      2. 14.6.2. Open Signed Offline
    7. 14.7. Tool Support
    8. 14.8. Symbian Platform Security Compared with Other Models
      1. 14.8.1. Android
        1. 14.8.1.1. Application Identity
        2. 14.8.1.2. Capability Assignment
      2. 14.8.2. Other Linux-based Platforms
      3. 14.8.3. iPhone OS
      4. 14.8.4. Windows Mobile
  20. 15. Writing Portable Code and Maintaining Ports
    1. 15.1. Recognizing Portable Code
      1. 15.1.1. Has Your Application Been Ported to Another Platform?
      2. 15.1.2. Are the Libraries Supported?
      3. 15.1.3. How Many New Compiler or Language Features Are Used?
      4. 15.1.4. Do I Have to Deal with Varying Feature Availability?
    2. 15.2. Design Strategies and Patterns
      1. 15.2.1. Writing Modular Code is a Good Way to Write Portable Code
      2. 15.2.2. Using Indirection Layers
      3. 15.2.3. Designing APIs
      4. 15.2.4. General Design Guidelines
      5. 15.2.5. Adopting Patterns
        1. 15.2.5.1. Adapter Pattern
        2. 15.2.5.2. Façade Pattern
        3. 15.2.5.3. Model–View–Controller Pattern
    3. 15.3. Strategies for Maximizing the Number of Portable Modules
      1. 15.3.1. Using User-Defined Data Types
      2. 15.3.2. Considering Platform Independence
      3. 15.3.3. Supporting Multiple Libraries
      4. 15.3.4. Building Your Own Bricks
    4. 15.4. Configuration Management
      1. 15.4.1. Revision-Control Systems
      2. 15.4.2. Common Problems
        1. 15.4.2.1. Badly Written Code
        2. 15.4.2.2. Developer Communication
        3. 15.4.2.3. Configuration File Management
        4. 15.4.2.4. Source Integration
    5. 15.5. Summary
  21. A. A Techniques for Out-of-Memory Testing
    1. A.1. Why Test for Out-of-Memory Errors?
    2. A.2. Out-of-Memory Loop
    3. A.3. Improved Heap Failure Tool
    4. A.4. Summary
  22. References