Symbian OS C++ for Mobile Phones: Volume 1: Professional Development on Constrained Devices

Symbian OS C for Mobile Phones
CONTENTS
About this book
Who Is This Book For?
Conventions
Foreword
Simply better phones
Symbian OS phones
Mobile phones with a numeric keypad:
Mobile phones with touch screens:
Mobile phones with a full keyboard:
About the Authors
Acknowledgements
1 Getting Started
1.1 Using the Emulator
1.1.1 Launching the Emulator
1.1.2 GUI Style
1.2 Hello World – Text Version
1.2.1 The Program:
1.2.2 The Project Speci cation File
1.2.3 The Component De nition File
1.2.4 Building from the Command Line
1.2.5 Building in the Metrowerks IDE
1.2.6 Running on the Target Machine
1.3 Summary
2 System Structure
2.1 Hardware Resources
2.2 Software Basics
2.3 Processes, Threads and Context Switching
2.4 Executable Programs
2.4.1 The Place of Execution
2.4.2 Loading and Sharing
2.4.3 Cutting Down the Size
2.4.4 Launching Applications and Servers
2.5 Power Management
2.6 The Kernel and E32
2.7 Device Drivers
2.8 Timers
2.9 Memory
2.9.1 Process and Thread Memory
2.9.2 No Writable Static Data in DLLs
2.10 Files
2.11 Event Handling
2.12 Perspectives on Event Handling
2.13 Active Objects
2.14 Multitasking and Preemption
2.15 Servers
2.16 Where Threads Matter
2.17 APIs Covered in the Book
2.18 Summary
3 C++ and Object Orientation
3.1 Fundamental Types
3.2 Naming Conventions
3.2.1 Class Names
3.2.2 Data Names
3.2.3 Function Names
3.2.4 Macro Names
3.2.5 Layout
3.2.6 Summary
3.3 Functions
3.3.1 Function Parameters
3.4 APIs
3.4.1 Types of Function
3.4.2 DLLs and Other API Elements
3.4.3 Exported Functions
3.4.4 Virtual Functions and APIs
3.5 Templates
3.5.1 The Thin Template Pattern
3.5.2 Numbers in Templates
3.6 Casting
3.7 Classes
3.7.1 Interfaces
3.7.2 Bad Practices
3.8 Design Patterns
3.9 Class Diagrams and UML
3.9.1 Describing APIs
3.9.2 Describing Classes
3.9.3 Describing Relationships between Classes
3.9.4 Describing Derivation
3.9.5 Cardinality
3.10 Summary
4 A Simple Graphical Application
4.1 What’s in a Name?
4.2 Introduction to the Graphics Architecture
4.3 Application Structure
4.4 A Graphical Hello World
4.4.1 The Program
4.4.2 The Project Speci cation File
4.4.3 Getting a UID
4.4.4 Building the Application
4.4.5 Building in the CodeWarrior IDE
4.4.6 The Source Code
4.5 The Resource File
4.5.1 The Header
4.5.2 De ning the Shortcut Keys and the Menu
4.5.3 String Resources
4.6 Bringing it to Life
4.7 Launching the Application
4.8 Command and Event Handling
4.8.1 Pointer-generated Commands from the Menu Bar
4.8.2 Keyboard-generated Commands from the Menu Bar
4.8.3 Commands from Shortcut Keys
4.9 Terminating the Application
4.10 On-target Debugging
4.11 Setting Up MetroTRK
4.11.1 Con guration
4.12 Launching MetroTRK
4.13 Setting up the CodeWarrior IDE
4.14 Debugging Your Application
4.15 Summary
5 Strings and Descriptors
5.1 Strings and Memory
5.1.1 Strings in C
5.1.2 Strings in Symbian OS
5.2 Modifying Strings
5.2.1 Modifying C Strings
5.2.2 Modifying Symbian OS Strings
5.2.3 Modifying
5.2.4 Descriptor Type Summary
5.2.5 Using the Abstract Classes in Interfaces
5.2.6 Literals Again
5.3 Standard Descriptor Functions
5.3.1 Basics
5.3.2 Comparison
5.3.3 Searching
5.3.4 Extracting
5.3.5 Clearing and Setting
5.3.6 Manipulating Data
5.3.7 Letter Manipulation
5.3.8 Trimming and Justificatio
5.3.9 Formatting
5.4 More Text APIs
5.5 Unicode and Character Conversion
5.6 Binary Data
5.7 Summary
6 Error Handling and Cleanup
6.1 What Kinds of Error?
6.2 Handling Out-of-memory Errors
6.2.1 Uikon Debug Keys
6.2.2 The Memorymagic Application
6.2.3 Allocating, Destroying, and Heap Balance
6.2.4 Heap Failure
6.2.5 How Does Leave Work?
6.2.6 The Cleanup Stack
6.2.7 Two-phase Construction
6.3 Summary of Cleanup Rules
6.4
and
Classes
6.5
Classes
6.5.1
as Member Variables
6.5.2 Error Code Returns versus
Functions
6.5.3
Classes on the Cleanup Stack
6.6 User Errors
6.7 More on Panics
6.8 Testing Engines and Libraries
6.9 Summary
7 Resource Files
7.1 Why a Symbian-specific Resource Compiler?
7.1.1 Source-file Syntax
7.1.2 Localizable Strings
7.1.3 Multiple Resource Files
7.1.4 Compiling a Resource File
7.1.5 The Content of a Compiled Resource File
7.2 Summary
8 Basic APIs
8.1 A Few Good APIs
8.1.1 User Class
8.1.2 Dynamic Buffers
8.1.3 Collections
8.1.4 Locale
8.1.5 Math
8.1.6 Variable Argument Lists
8.1.7 String Formatting
8.1.8 RDebug Class
8.2 C Standard Library
8.2.1 Porting Issues
8.2.2 Porting Multithreaded Programs
8.2.3 Global Data
8.2.4 Conclusion
8.3 Summary
9 Stand-alone Applications
9.1 The Game of Battleships
9.2 Overview
9.2.1 Program Structure
9.2.2 The Engine
9.2.3 The Controller
9.3 Engine Classes
9.3.1 The Ship Class
9.3.2 The Fleet Class
9.3.3 The Game Engine Class
9.4 The View Class
9.4.1 View Construction
9.4.2 Drawing the View
9.4.3 Handling Events
9.5 Scaling and Zooming
9.6 The Controller
9.6.1 Accessing the GUI Environment
9.6.2 Zooming
9.7 The App UI
9.8 Persistence
9.8.1 Solo Ships as a File-based Application
9.8.2 Store and Restore
9.8.3 Creating a Default Document
9.8.4 App UI and the Document
9.9 Two Player Battleships
9.9.1 View Architecture
9.9.2 Views in Two Player Battleships
9.9.3 Fleet Views
9.9.4 Hider View
9.9.5 View Test Program
9.9.6 Sound Effects
9.10 Summary
10 Dialogs and Concrete Controls
10.1 Introducing Dialogs
10.1.1 A Query Dialog
10.1.2 A Single-page Dialog
10.1.3 A Multipage Dialog
10.1.4 Cue Text
10.1.5 Controls
10.1.6 Dialog Processing
10.1.7 Modality
10.1.8 Summary
10.2 Some Simple Dialogs
10.2.1 Resource File Definitio
10.2.2 Dialog Code
10.2.3 Read-only Dialogs
10.2.4 Simple Dialog Processing
10.3 Dialog APIs
10.3.1 Resource Specification
10.3.2 Adding Buttons
10.3.3 Basic Functions
10.4 Stock Controls for Dialogs
10.4.1 Buttons
10.4.2 Lists
10.4.3 Editors
10.4.4 Using Controls in Dialogs
10.4.5 Accessing Controls
10.4.6 Custom Controls in Dialogs
10.5 Standard Dialogs
10.5.1 Alerts
10.5.2 Queries
10.5.3 Other Standard Dialogs
10.6 Summary
11 Graphics for Display
11.1 Drawing Basics
11.1.1 Controls
11.1.2 Walking through
11.2 The CGraphicsContext API
11.2.1 Coordinate Classes
11.2.2 Setting up the Graphics Context
11.2.3 Drawing Functions
11.3 Drawing and Redrawing
11.3.1 The Model, View, and Controller Pattern
11.3.2 The
Contract
11.4 Flicker-free Redraw
11.4.1 Drawing Everything
11.4.2 Status View Update
11.4.3 Hit Reports
11.4.4 Cursor Movement
11.5 Sharing the Screen
11.5.1 CONE
11.5.2 Window-owning and Lodger Controls
11.5.3 Compound Controls
11.5.4 More on Drawing
11.5.5 Backed-up Windows
11.6 CCoeControl’s Support for Drawing
11.6.1 Control Environment
11.6.2 Window-owning and Lodging
11.6.3 Components
11.6.4 Position and Size
11.6.5 Drawing
11.7 Special Effects
11.7.1 Shadows
11.7.2 Backing Up Behind
11.7.3 Animation
11.7.4 Uikon Debug Keys
11.7.5 Control Context
11.7.6 Scrolling
11.8 Summary
12 Graphics for Interaction
12.1 Key, Pointer, and Command Basics
12.1.1 Handling Key Events
12.1.2 Handling Pointer Events
12.1.3 Turning Events into Commands
12.2 Interaction in Dialogs
12.2.1 User Requirements
12.2.2 Some Basic Abstractions
12.2.3 Programmer Requirements
12.2.4 Compound Controls
12.2.5 Key Distribution and Focus
12.2.6 Dimming and Visibility
12.2.7 Validation
12.2.8 Control Observers
12.2.9 Containers
12.3 Key Processing Revisited
12.3.1 Focus
12.3.2 The Text Cursor
12.4 Pointer Processing Revisited
12.4.1 Interaction Paradigms
12.4.2 Pick Correlation
12.4.3 Grabbing the Pointer-down Control
12.4.4 Capturing the Pointer
12.4.5 Getting High-resolution Pointer Events
12.4.6 Processing Pointer Events
12.4.7 Customizing Pointer and Key Sounds
12.5 More on Window Server and Control Environment APIs
12.5.1 Application to Window Server Communication
12.5.2 Window Types
12.5.3 Standard Window
12.5.4 Window Group
12.6 The Shell
12.7 Summary
13 Files, Streams, and Stores
13.1 File-based Applications
13.1.1 User and System Files
13.1.2 UIQ Application Data File Placement
13.1.3 Summary of File Naming and Location Conventions
13.2 Introducing the APIs
13.3 The File Server
13.3.1 File Server Sessions
13.3.2 The Current Directory
13.3.3 Drives, File Systems, and Media
13.3.4 Files
13.3.5 Directories
13.3.6 Cracking Filenames
13.4 The streams Program
13.4.1 Connecting to the File Server
13.4.2 Writing a File
13.4.3 Reading it Back
13.4.4 Parsing Filenames
13.4.5 Summary of the File APIs
13.5 Streams
13.5.1 External and Internal Formats
13.5.2 Ways to Externalize and Internalize Data
13.5.3 Types of Stream
13.6 Stores
13.6.1 Direct File Stores
13.6.2 Embedded Stores
13.6.3 Permanent File Stores
13.7 Types of Store
13.8 Dictionary Stores and .ini Files
13.9 The Application Architecture
13.10 Summary
14 Finishing Touches
14.1 Adding Buttons
14.1.1 Creating the Bitmaps
14.1.2 Converting the Bitmaps
14.1.3 Changing the Resource File
14.1.4 Building the Application
14.1.5 More on the bmconv Tool
14.2 Adding Application Icons
14.2.1 Creating the Icon
14.2.2 Adding Captions
14.2.3 Rebuilding Your Application
14.2.4 More on aiftool
14.3 Making Your Application Installable
14.3.1 Securing Your Installation File
14.3.2 Producing the package file
14.3.3 Generating the final SIS fle
14.3.4 Installing SIS Files
14.3.5 Checking and uninstalling SIS file
14.3.6 Delivering Applications to End Users
14.4 Designing Applications for UIQ – Some Guidelines
14.4.1 Planning the GUI
14.4.2 Designing List and Detail Views
14.4.3 Designing Menus and Folders
14.4.4 Standard Menu Items
14.4.5 Creating Dialogs
14.4.6 Considering Text Input
14.4.7 Providing Text and Messages
14.4.8 Using Scroll Arrows and Scroll Bars
14.4.9 Designing for Various Zoom Levels
14.4.10 Linking between Applications
14.5 Handling Data
14.6 Summary
15 Deviceand Size-independent Graphics
15.1 Sizeand Target-independent Drawing for Applications
15.1.1 Device-independent Drawing
15.1.2 Using the View
15.1.3 Managing the Zoom Factor
15.1.4 Views and Reuse
15.1.5 Summary of Device-independent Drawing
15.2 More on the GDI
15.2.1 Blitting and Bitmaps
15.2.2 More on Fonts
15.2.3 More on Printing
15.2.4 Color
15.2.5 Web Browsing
15.3 The Developer’s Quest for Device-independent Code
15.3.1 Real Devices Intrude
15.4 GUI Systems
15.4.1 The Evolution of the Symbian OS GUI System
15.4.2 Major GUI Components
15.5 Summary
16 A Multiuser Application
16.1 Communications in Symbian OS
16.2 Battleships without Communications
16.2.1 View and Menu Tricks
16.2.2 Object-oriented Plumbing
16.2.3 Communications is Different
16.3 TOGS
16.3.1 The Shape of TOGS
16.3.2 Starting Points – Datagram and Conversation
16.3.3 GSDP – Game Session Datagram Protocol
16.3.4 BSP – Battleships Protocol
16.3.5 Test Programs
16.3.6 Pattern Reuse
16.3.7 Building on TOGS
16.4 Using the Game
16.4.1 Playing for Real
16.4.2 Reliability from RGCP
16.4.3 SMS
16.5 From the Inside
16.5.1 The Status View
16.5.2 Handling Hit Requests
16.5.3 Checking Conditions
16.5.4 Hit Processing: the Full Story
16.6 Taking Battleships Further
16.6.1 Better Battleships
16.6.2 Other Games
16.6.3 Single-player Games
16.6.4 Infrastructure Improvements
16.7 Summary
17 Active Objects
17.1 A Simple Active Object
17.1.1 Construction and Destruction
17.1.2 Requesting and Handling Events
17.1.3 Canceling a Request
17.2 How it Works
17.2.1 More on Canceling Requests
17.2.2 Error Handling
17.2.3 Non-preemption and Priority
17.2.4 Starting and Stopping the Scheduler
17.2.5 Adding Functionality to the Active Scheduler
17.2.6 Framework Summary
17.3 Active Object Patterns
17.3.1 Maintaining an Outstanding Request
17.3.2 State Machines
17.3.3 Interfaces for Handling Completion
17.3.4 Long-running Tasks and Incremental Interfaces
17.3.5 Prioritizing and Maintaining Responsiveness
17.4 Summary
18 Client-server Framework
18.1 Introduction
18.1.1 Handling Routine Requests
18.1.2 Setting up Sessions
18.1.3 Starting Servers
18.1.4 Handling Asynchronous Requests
18.1.5 Ending a Session and Cleanup after Client Death
18.1.6 Cleanup after Server Death
18.1.7 Handling Multiple Objects from One Session
18.2 Performance
18.2.1 Client-side Buffering
18.2.2 High-level Transactions
18.2.3 Data Caching
18.2.4 Related Servers in the Same Process
18.2.5 Shared Memory
18.3 Servers and Threads
18.3.1 Sharing Client-side Objects between Threads
18.3.2 Multithreading in the Server
18.3.3 Time-critical Server Performance
18.3.4 Thread Priorities
18.4 The Client-server APIs
18.4.1 Thread Basics
18.4.2 Interthread Data Transfer and the Package Classes
18.4.3 Client-side Objects
18.4.4 Server-side Objects
18.5 Summary
19 The GSDP Server
19.1 Software Structure
19.2 The Client Interface
19.2.1 Message-passing Functions
19.2.2 Listening and Receiving
19.2.3 Connecting and Disconnecting
19.2.4 The Client API as a DLL
19.3 The Server Implementation
19.3.1 Message Handling
19.3.2 Sending Datagrams
19.3.3 Using the ECOM Framework
19.3.4 Using the Protocols
19.3.5 Receiving Datagrams
19.3.6 Startup and Shutdown
19.4 Summary
20 GDP Implementations
20.1 Tasks, States and State Machines
20.1.1 GDP State Machines
20.2 SMS Implementation
20.2.1 ESOCK and Symbian OS Support for SMS
20.2.2 The GDP-SMS Message Format
20.2.3 The GDP-SMS Implementation
20.3 Bluetooth Implementation
20.3.1 Symbian OS Support for Bluetooth
20.3.2 The GDP-BT Protocol Mapping
20.3.3 The GDP-BT Implementation
20.4 Summary
Appendix 1 Example Projects
The Independent Projects
The Battleships Projects
The TOGS Projects
Appendix 2 Developer resources
Symbian Developer Network
Symbian OS developer tools
Symbian OS SDKs
Other SDKs and SDK extensions
Developer support
Appendix 3 TOGS Guide and Reference
GDP
Symbian OS Implementation
GDP Loopback Implementation
GDP Chat
Taking GDP Forward
GSDP
Symbian OS Implementation – Client-side
Server-side Symbian OS Implementation
GSDP Chat
Taking GSDP Forward
RGCP
Protocol Overview
RGCP Symbian OS Implementation
RGCP Converse
Taking RGCP Forward
The Battleships Protocol
Protocol Overview
Game UI
Program Structure
Taking BSP Forward
Summary
Appendix 4 Emulator Reference
Inside the Emulator
Source Compatibility
Drive Mapping
The Directory Scheme
Emulator Startup
Emulator Startup Parameters
Emulator Command Line Syntax
Key Mapping
Communications
How Good is the Emulator?
Debug Keys
Index