Tài liệu Symbian OS C++ for Mobile Phones doc

Symbian OS C++ for Mobile Phones
Volume 3

Symbian OS C++
for Mobile Phones
Volume 3
Richard Harrison, Mark Shackman
With
Adi Rome, Alex Wilbur, Andrew Jordan, Douglas Feather,
Ernesto Guisado, Hassan Ali, Ioannis Douros, John Pagonis,
Lucian Piros, Mark Cawston, Martin Hardman, Mathew Inwood,
Rick Martin, Sanjeet Matharu, Tim Williams, Yang Zhang
Reviewed by
Graeme Duncan, Guanyun Zhang, Ian McDowall,
Jehad Al-Ansari, Jonathan Allin, Jo Stichbury,
Kostyantyn Lutsenko, Lane Roberts, Lars Kurth, Mark Jacobs,
Mark Welsh, Mathias Malmqvist, Matthew O’Donnell,
Rahul Singh, Ricky Junday, Robert Palmer,
Rosanna Ashworth-Jones, Sorin Basca, Tim Labeeuw,
Warren Day, Will Bamberg
Head of Symbian Press
Freddie Gjertsen
Managing Editor
Satu McNabb
Copyright ¤ 2007 Symbian Software Ltd
Published by John Wiley & Sons, Ltd The Atrium, Southern Gate, Chichester,
West Sussex PO19 8SQ, England
Telephone (+44) 1243 779777

Email (for orders and customer service enquiries):
Visit our Home Page on www.wileyeurope.com or www.wiley.com
All Rights Reserved. No part of this publication may be reproduced, stored in a retrieval system or
transmitted in any form or by any means, electronic, mechanical, photocopying, recording, scanning or
otherwise, except under the terms of the Copyright, Designs and Patents Act 1988 or under the terms of
a licence issued by the Copyright Licensing Agency Ltd, 90 Tottenham Court Road, London W1T 4LP,
UK, without the permission in writing of the Publisher. Requests to the Publisher should be addressed to
the Permissions Department, John Wiley & Sons Ltd, The Atrium, Southern Gate, Chichester, West
Sussex PO19 8SQ, England, or emailed to , or faxed to (+44) 1243 770620.
Designations used by companies to distinguish their products are often claimed as trademarks. All
brand names and product names used in this book are trade names, service marks, trademarks or
registered trademarks of their respective owners. The Publisher is not associated with any product or
vendor mentioned in this book.
This publication is designed to provide accurate and authoritative information in regard to the subject
matter covered. It is sold on the understanding that the Publisher is not engaged in rendering
professional services. If professional advice or other expert assistance is required, the services of a
competent professional should be sought.
Other Wiley Editorial Offices
John Wiley & Sons Inc., 111 River Street, Hoboken, NJ 07030, USA
Jossey-Bass, 989 Market Street, San Francisco, CA 94103-1741, USA
Wiley-VCH Verlag GmbH, Boschstr. 12, D-69469 Weinheim, Germany
John Wiley & Sons Australia Ltd, 42 McDougall Street, Milton, Queensland 4064, Australia
John Wiley & Sons (Asia) Pte Ltd, 2 Clementi Loop #02-01, Jin Xing Distripark, Singapore 129809
John Wiley & Sons Canada Ltd, 6045 Freemont Blvd, Mississauga, Ontario, L5R 4J3, Canada
Wiley also publishes its books in a variety of electronic formats. Some content that
appears in print may not be available in electronic books.
Library of Congress Cataloging-in-Publication Data
Harrison, Richard.
Symbian OS C++ for mobile phones / By Richard Harrison.
p. cm.

Includes bibliographical references and index.
ISBN 0-470-85611-4 (Paper : allk. paper)
1. Cellular telephone systems – Computer programs. 2. Operating
systems (Computers) I. Title.
TK6570.M6H295 2003
621.3845

6 – dc21
2003006223
British Library Cataloguing in Publication Data
A catalogue record for this book is available from the British Library
ISBN: 978-0-470-06641-6
Typeset in 10/12pt Optima by Laserwords Private Limited, Chennai, India
Printed and bound in Great Britain by Bell & Bain, Glasgow
This book is printed on acid-free paper responsibly manufactured from sustainable
forestry in which at least two trees are planted for each one used for paper production.
Contents
About the Authors xi
Acknowledgements xix
Symbian Press Acknowledgments xxi
About this book xxiii
Glossary xxvii
1 Getting Started 1
1.1 Using the Emulator 1
1.2 Hello World – Text Version 6
Summary 15
2 A System Introduction to Symbian OS 17
2.1 Symbian OS Basics 17
2.2 Framework Basics 30
2.3 APIs Covered in this Book 36

Summary 39
3 Symbian OS C++ 41
3.1 Fundamental Data Types 41
3.2 Naming Conventions 43
3.3 Functions 49
3.4 APIs 51
3.5 Templates 55
3.6 Casting 56
vi CONTENTS
3.7 Classes 57
3.8 Design Patterns 59
Summary 60
4 Objects – Memory Management, Cleanup
and Error Handling 61
4.1 Object Creation and Destruction 62
4.2 Class Categories in Symbian OS 66
4.3 Error Handling 70
4.4 The Cleanup Stack 76
4.5 Two-Phase Construction 81
Summary 85
5 Descriptors 87
5.1 Overview 87
5.2 Anatomy of Descriptors 91
5.3 Literals 93
5.4 Stack Descriptors 93
5.5 Pointer Descriptors 95
5.6 Heap Descriptors 99
5.7 Narrow, Wide and Neutral Descriptors 108
5.8 Descriptors and Binary Data 109
5.9 Using Descriptors with Methods 110

5.10 Some Descriptor Operations 121
5.11 Correct Use of Descriptors 128
5.12 Manipulating Descriptors 138
Summary 148
6 Active Objects 151
6.1 The Asynchronous Service 151
6.2 Multitasking and Pre-emption 156
6.3 A More In-depth Look at Active Objects 158
6.4 How It Works 167
6.5 Active Object Priorities 171
6.6 Active Object Cancellation 176
6.7 Starting and Stopping the Scheduler 181
6.8 Understanding a Stray Signal 182
6.9 Other Common Active Object Errors 187
6.10 Implementing State Machines 190
6.11 Long-Running Tasks and Active Objects 194
Summary 200
7 Files and the File System 203
7.1 File-Based Applications 203
7.2 Drives and File Types 204
CONTENTS vii
7.3 File System Services 205
7.4 Streams 216
7.5 Stores 224
Summary 239
8 Interprocess Communication Mechanisms 241
8.1 Overview 241
8.2 Client–server IPC 247
8.3 Publish and Subscribe IPC 253
8.4 Message Queue IPC 257

8.5 Which IPC Mechanism Should You Use? 259
Summary 261
9 Platform Security and Publishing Applications 263
9.1 Releasing an Application 263
9.2 How Does Platform Security Work? 264
9.3 How Do I Support Platform Security? 266
9.4 Preparing an Application for Distribution 268
9.5 Overview of Symbian Signed 272
9.5 Installing a SIS File 279
9.6 List of Capabilities 280
Summary 281
10 Debugging and the Emulator 283
10.1 Using the Emulator 283
10.2 Emulator Debugging 289
10.3 Debugging on a Phone 306
10.4 Miscellaneous Tools 308
Summary 309
11 The Application Framework 311
11.1 Symbian OS Application Framework 311
11.2 S60 and UIQ Platform Application Frameworks 313
11.3 A Graphical Hello World 315
Summary 330
12 A Simple Graphical Application 331
12.1 Implementing the Game on S60 333
12.2 Differences for UIQ 3 355
Summary 366
13 Resource Files 367
13.1 Why a Symbian-Specific Resource Compiler? 367
13.2 Source File Syntax 368
13.3 Bitmaps and Icons 372

viii CONTENTS
13.4 Updating the Resource Files 377
13.5 Application Registration Files 378
13.6 Localizable Strings 379
13.7 Multiple Resource Files 382
13.8 Compiling a Resource File 383
13.9 The Content of a Compiled Resource File 385
13.10 Reading Resource Files 388
Summary 389
14 Views and the View Architecture 391
14.1 The View Architecture 392
14.2 The MCoeView Interface 397
14.3 Introduction to the Example Application 398
14.4 Creating and Managing the Views 406
14.5 Implementing the MCoeView Interface 408
14.6 Command Menus 414
Summary 421
15 Controls 423
15.1 What Is a Control? 423
15.2 Control Types 424
15.3 Control Layout 429
15.4 Handling Key and Pointer Events 432
15.5 Observing a Control 442
15.6 Drawing a Control 444
15.7 Backed-up Windows 451
15.8 Backed-up-Behind Windows 452
15.9 Dimmed and Invisible Controls 454
Summary 455
16 Dialogs 457
16.1 What Is a Dialog? 457

16.2 Simple Dialogs 459
16.3 Complex Dialogs 462
16.4 Single-Page Dialogs 464
16.5 Multi-Page Dialogs 466
16.6 Dialog APIs 472
16.7 Stock Controls for Dialogs 475
16.8 Custom Controls in Dialogs 477
Summary 480
17 Graphics for Display 481
17.1 Drawing Basics 482
17.2 The CGraphicsContext API 486
CONTENTS ix
17.3 Drawing and Redrawing 492
17.4 Drawing Controls 499
17.5 Sharing the Screen 502
17.6 Support for Drawing in CCoeControl 514
17.7 Special Effects 521
17.8 Window Server Features 526
17.9 Device- and Size-Independent Graphics 529
Summary 556
18 Graphics for Interaction 557
18.1 Key, Pointer and Command Basics 558
18.2 User Requirements for Interaction 559
18.3 Some Basic Abstractions 561
18.4 Processing Key Events 567
18.5 Processing Pointer Events 571
18.6 Window Server and Control Environment APIs 576
Summary 582
19 Plug-ins and Extensibility 583
19.1 System Services 583

19.2 What Is a Plug-in? 587
19.3 The ECOM Library 593
19.4 Plug-ins in Symbian OS 603
Summary 604
20 Communications and Messaging Services 605
20.1 Communications in Noughts and Crosses 605
20.2 Communication Between Controller and Transport 606
20.3 Serial Communications 609
20.4 Socket-based Communications 615
20.5 Messaging 632
20.6 Security 646
Summary 649
21 Multimedia 651
21.1 The Multimedia Framework 651
21.2 The Image Conversion Library 682
21.3 Camera API 699
21.4 Tuner API 706
Summary 712
22 Introduction to SQL RDBMS 715
22.1 Overview of RDBMS 715
22.2 SQL Basics 716
xCONTENTS
22.3 Symbian SQL Server Component Architecture 729
22.4 Symbian SQL Error Codes 751
Summary 753
Appendix: Developer Resources 755
References 761
Index 763
About the Authors
Richard Harrison, Lead Author

Richard spent the first years of his working life teaching mathematics,
physics and computer science. During that time he wrote a Forth language
implementation for Acorn Computers, and wrote accompanying user
manuals for the Acorn Atom and BBC Micro.
He joined Psion in 1983, and worked on a range of documentation
and software projects. Amongst other roles, he was the principal designer
and author of the Psion Series 3 word processor, and lead author for the
Psion SIBO SDK.
Richard transferred to Symbian at its inception in 1998, when his initial
responsibility was to build up and lead the System Integration team. More
recently he has acted as adviser and author in the Symbian Press team.
Educated at Balliol College, Oxford with an MA in Natural Science
(Physics), Richard also gained an MSc in Astronomy from Sussex Uni-
versity, and spent a further two years of postgraduate research in the
Astronomy Group at Imperial College.
Outside work, Richard’s interests include a fascination with lights in the
sky – stemming from life-long loves for both Astronomy and Fireworks.
These days, his interest in Astronomy tends to be of the armchair variety,
but he still acts as an occasional firer on a range of public and private
firework displays.
Mark Shackman, Lead Author
Mark graduated with a first-class honors degree in Computing Studies,
followed by a Masters in Digital Systems and finally a Postgraduate
xii ABOUT THE AUTHORS
Certificate of Education. After six years of teaching mathematics, physics
and computing and a spell at Morgan Stanley, he joined Psion Software
in 1997 as a Technical Author working on SDK content and installation
technologies.
After the formation of Symbian, Mark joined the Connectivity Engineer-
ing group, with sole responsibility for authoring, producing, delivering and

supporting the Connectivity SDK. He also wrote a chapter in Symbian’s
first book,
Professional Symbian Programming
. In 2001 Mark moved to
the Kits team, becoming Technical Architect shortly afterwards, with the
responsibility of introducing both the new Package Manager Kit format
and subsequently the Component-Based Releases.
In 2004, Mark transferred to the Symbian Developer Network, and
now provides technical support to developers in the form of presentations,
papers, books and tools. He specializes in platform security, has given
presentations in the USA, Brazil, Israel, India, the Philippines, Singapore,
at 3GSM & at the Smartphone Shows, and wrote for the
Symbian OS
Platform Security
book.
Mark spends some of his spare time shooting things – but only from
behind a Canon lens. He’s only ever had two pictures published and
firmly expects it to stay that way.
Adi Rome
Adi has a BA in Computer Science from Tel Aviv University. After a spell
in teaching, she worked in Quality Assurance, moving to analysis, design
and implementation of embedded systems, before joining Symbian in
2004. Having spent a while in the Multimedia team, becoming involved
in all aspects of the development and delivery software lifecycle, Adi
joined the Developer Services team as the multimedia guru. Within
this team, she also provided technical consultancy across all areas of
Symbian OS, with a special emphasis on hardware – she was responsible
for communicating the Symbian roadmap to silicon and multimedia
partners, and was Symbian’s lead on the partner component validation
program. Away from technical work, Adi has been involved in setting

up the Symbian China partner-consulting organization and is in much
demand for her presentation skills, having given sessions at a wide range
of partner and industry events, including 3GSM World Congress.
Andrew Jordan
Andrew joined Symbian in late 2000 where he worked in the Connectivity
team for a short time before moving to the Base Peripherals team. Here
he worked on device and media drivers, the file server and file systems.
Working mainly with Japanese customers for the Japanese market, Andrew
ABOUT THE AUTHORS xiii
currently lives in Japan where he has been for the last two years having
moved to a product development team.
Alex Wilbur
Alex graduated from the Royal Military College of Science in 1999 with
a first-class honors degree in software engineering. A keen third-party
software author for the Psion Series 5, Alex joined Symbian’s PIM team
in 1999.
2001 saw Alex joining Symbian’s Professional Services department as
a Senior Technical Consultant. Since then he has been living in Tampere,
Finland at the heart of Nokia’s S60 Research and Development site,
consulting on all the S60-based smartphones, from the 7650 onwards.
Alex enjoys all aspects of home cinema, the Finnish outdoors and also
spending time with his partner, Ina, and their daughter, Elli.
Douglas Feather
Douglas joined Symbian (then Psion) in 1994. He started by leading the
writing of the text formatting engine for the Psion S5. He has also work
in the Web Browser and Core Apps teams where he rewrote most of the
Versit parser to greatly improve its performance. For seven of the last nine
years, he has worked mainly on the Window Server, where he added
full color support, fading support, a framework to allow digital ink to
be drawn over the other applications, support for multiple screens and

transparent windows.
Douglas has a BSc in mathematics from Southampton University and
a PhD in number theory from Nottingham University. He is a committed
Christian and can be regularly seen on a Sunday afternoon at Speaker’s
Corner (Hyde Park, London) engaging in theological debate to defend the
biblical truths about Jesus Christ.
Ernesto Guisado
Ernesto is a senior C++ developer. Between 2001 and 2006, he worked
at Symbian as developer, technology architect and technical lead for
Symbian OS v9.1. In the process, he learned more about Platform Security
and API compatibility than any sane person would want to. In his spare
time he publishes articles for computing magazines and contributes to
open source projects in C++, Perl and Ruby. He has a website and blog
at

.
xiv ABOUT THE AUTHORS
Hassan Ali
Hassan joined Symbian’s Crystal team 2000. He started work on the
9210 project mainly on defects triage, true testing and Java compliance
testing. He then moved onto Techview messaging and worked on the
SyncML application, SyncML Ui Notifiers, messaging MTMs and Auto-
mated Smoke tests. Hassan then joined the Multimedia test team where
he worked on automating the hardware testing and was a technical lead
for Multimedia’s EABI compiler migration. Currently he is working in
Product Delivery as OS technical lead of maintenance products, where
he automated the patch (ICD) delivery system. He is also involved in the
Java automated build system and providing defect analysis support to the
project office to help prioritize customer issues.
Ioannis Douros

Ioannis received his PhD in three-dimensional human body modeling
from University College London, where he has also worked for a number
of years as a research fellow in the areas of computer vision and intelligent
systems.
He joined the Symbian ecosystem in 2004 and is currently a software
engineer in the Converged Communications team. He is an Accredited
Symbian Developer, as well as an unrepentant caffeine addict. He lives
in rural Buckinghamshire with his partner, Sue.
John Pagonis
John joined Symbian in 1998, where he worked on the development
of the Ericsson R380 smartphone and later for the team that developed
the Symbian OS Bluetooth stack. Since then, John has worked on many
areas of Symbian OS with his experience ranging from communication
protocols, security, location-based services and operating system inter-
nals to software-engineering methodologies, developer consulting, team
coaching and organizational improvements.
Currently, John is working as a consultant to developers, trying to keep
them happy, among other ways, by writing articles and code and giving
seminars and presentations to whoever wants to learn about developing
for Symbian OS mobile phones. John is a visiting lecturer at City University
in London and is (still) a PhD candidate at the University of Essex, from
where he holds an MSc (Hons) in computer and information networks as
well as a BEng (Hons) in computers and networks. John also believes that
it is better when certain things are kept unread.
ABOUT THE AUTHORS xv
Lucian Piros
Since joining Symbian, in January 2006, Lucian has worked with the PIM
and Internet team on various releases of contact model architecture and
has been involved in the latest contact model architecture design. Before
joining Symbian, Lucian worked for two years as independent developer

on core Symbian OS applications for a number of UI platforms based on
Symbian OS. He has eight years industrial experience, most of them spent
as a C++ programmer writing telecommunications applications. Educated
at Babes-Boliay University, Cluj Napoca, with a BSc in mathematics and
computer science, he enjoys spending his free time reading, traveling and
cooking.
Mark Cawston
Mark joined Symbian after graduating from the Computer Science Depart-
ment of the University of York. Since then he has worked across the
operating system, from the kernel and device drivers, through file sys-
tems, databases, contacts and messaging engines, security, short-range
connectivity and communications, up to the user interface and appli-
cations. He has combined a career developing the core Symbian OS
functionality, with helping manufacturers to deliver phones powered by
Symbian OS.
Martin Hardman
Martin joined Psion in 1994, remaining with the company for 10 years
as it evolved into Symbian. During that time he worked in several areas
and had several roles including Senior Technology Architect and System
Architect. He was also Symbian’s representative on the SyncML and
OMA Data Synchronization and Device Management working groups.
He graduated from South Bank University in London with a first-class
degree in computing.
In 2004, he moved to Vancouver, where he now lives with his wife Hai
Wei, to spend more time snowboarding. He works for Intrinsyc Software
where he is still involved with Symbian development.
Mathew Inwood
Mathew joined Symbian’s technical consulting group as a graduate in
2003. Since then, he has been involved in the development of the
multimedia subsystem for the Symbian OS v9.1 range of Sony Ericsson

xvi ABOUT THE AUTHORS
phones. He has a BA in computer science from Cambridge University,
during which he worked as a summer intern at Amadeus in France. He is
a keen paraglider pilot and tries to go flying as often as he can.
Rick Martin
Rick is a New Zealander who joined Symbian in 2005. One of Rick’s
hobbies is collecting qualifications. His first was in physics in the early
1980s. After that he graduated in software engineering, going on to qualify
in french studies and classical history. His latest project is working toward
an OU post-graduate degree in physical science, with a particular interest
in quantum computing. On one particularly sad occasion, he sat and
passed the Mensa exam.
Sanjeet Matharu
Sanjeet (Sanj) graduated from the University of Westminster in 1998 with
a BSc in computing. He eventually found himself joining Symbian in
2000 as a software engineer working on test tools. He developed much of
the core code for the Symbian Test Automation Tool (STAT) which is now
used in a majority of integration testing for Symbian OS. He also worked
on a number of other tools within the System Test team as a developer,
technical architect and project manager culminating in the creation of
the Symbian Test Network (involving many hours of reverse engineering
and assembling rack-mount servers). This network is now used as a test
harness for much of the Symbian OS testing.
In 2004, he moved into Marketing and had a direct involvement in
the Symbian Signed program and Developer Certificates. Since then he
has moved on to manage the Symbian Signed program and the Symbian
Developer Network with his core focus being on after-market application
developers and other developer programs such as Forum Nokia and Sony
Ericsson Developer World. Sanj would like to thank his team for putting
up with his continual demands to get things done and his wife, Jaskie, for

just generally putting up with him.
Tim Williams
Tim joined Symbian when it took over Origin’s Automation Technology
group with which he had worked mainly on manufacturing control
systems. An interest in user interfaces saw him work on the first S60
phone and Symbian’s smartphone reference user interface. Currently
a technical author he was previously a user-interface specialist in the
ABOUT THE AUTHORS xvii
Symbian Licensee Technical Consulting group. Away from the office,
he is normally riding his bike or coaching triathletes. He is married to
Heather.
Yang Zhang
Yang has a BEng in communication systems, an MSc in physics and a PhD
in engineering. He has contributed a number of works to IEEE journals,
international conferences and book chapters. He is now working for
Symbian after years of industrial experience in the telecommunications
domain. His current interests include mobile social networking, mobile
computing and mobile machine learning.

Acknowledgements
We would like to thank:
The authors, who toiled hard and long to give us their manuscripts,
and the technical reviewers who corrected and enhanced the text.
Freddie Gjertsen, who gave us the opportunity to polish our egos by
writing another book, and Laura Sykes.
Satu McNabb, for keeping our noses to the grindstone and making
sure that the work at each stage was completed – more or less – on time.
Our colleagues, who answered our queries and bore additional work-
load as this volume demanded ever-increasing amounts of time.
All those at Wiley who coaxed us into agreeing to a challenging

schedule for delivery of the text and then, following delivery, added their
inimitable professional touches.
Our families and friends who, throughout the long process of preparing
this book, saw much less of us than they had the right to expect

Symbian Press Acknowledgments
Symbian Press would like to thank Richard for not retiring too soon, and
Mark for more than helping him to bear the heavy burden of working
with us.
We’d also like to thank every member of the glittering crowd that
contributed: the authors who worked so hard to create this book and
the reviewers who shared their expertise by reviewing the content. A
special thank you to Adi for saving us as disaster loomed – very much
appreciated.
And last but not least, Satu, Freddie, Laura, Mark, Jo, Phil and everyone
at Developer Product Marketing would like to wish Richard a relaxing
retirement and every happiness in the future; it really has been a pleasure
working with you.