Symbian OS C++ for Mobile Phones

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