Symbian OS explained

Symbian OS Explained

Effective C++ Programming for Smartphones

Jo Stichbury

Reviewed by

David Batchelor, Andy Cloke, Reem EI Ghazzawi, Martin

Hardman, Morgan Henry, John Pagonis, William Roberts,

Keith Robertson, Phil Spencer, Colin Turfus

Managing editor

Phil Northam

Project editor

Freddie Gjertsen

Symbian OS Explained

TITLES PUBLISHED BY SYMBIAN PRESS

• Symbian OS Explained

Jo Stichbury

0470 021306 416pp 2004 Paperback

• Symbian OS C++ for Mobile Phones, Volume 2

Richard Harrison

0470 871083 448pp 2004 Paperback

• Programming Java 2 Micro Edition on Symbian OS

Martin de Jode

0470 092238 498pp 2004 Paperback

• Symbian OS C++ for Mobile Phones, Volume 1

Richard Harrison

0470 856114 826pp 2003 Paperback

• Programming for the Series 60 Platform and Symbian OS

Digia

0470 849487 550pp 2002 Paperback

• Symbian OS Communications Programming

Michael J Jipping

0470 844302 418pp 2002 Paperback

• Wireless Java for Symbian Devices

Jonathan Allin

0471 486841 512pp 2001 Paperback

Symbian OS Explained

Effective C++ Programming for Smartphones

Jo Stichbury

Reviewed by

David Batchelor, Andy Cloke, Reem EI Ghazzawi, Martin

Hardman, Morgan Henry, John Pagonis, William Roberts,

Keith Robertson, Phil Spencer, Colin Turfus

Managing editor

Phil Northam

Project editor

Freddie Gjertsen

Copyright  2005 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): [email protected]

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, with the exception of any material supplied

specifically for the purpose of being entered and executed on a computer system for exclusive use by

the purchaser of the publication. 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 [email protected], 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, 33 Park Road, 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, 22 Worcester Road, Etobicoke, Ontario,

Canada M9W 1L1

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

Stichbury, Jo.

Symbian OS explained effective C++ programming for smartphones / By Jo Stichbury.

p. cm.

Includes bibliographical references and index.

ISBN 0-470-02130-6 (pbk. alk. paper)

1. Mobile communication systems–Computer programs. 2. Operating systems

(Computers) 3. C++ (Computer program language) I. Title.

TK6570.M6S745 2004

005.265–dc22 2004015414

British Library Cataloguing in Publication Data

A catalogue record for this book is available from the British Library

ISBN 0-470-02130-6

Typeset in 10/12pt Optima by Laserwords Private Limited, Chennai, India

Printed and bound in Great Britain by Biddles Ltd, King’s Lynn

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

Foreword xi

About This Book xiii

Who Is It For? xiv

How to Use This Book xiv

Notation and Code Conventions Used in This Book xv

Introduction to Symbian OS xvii

Author Biography xxi

Author’s Acknowledgments xxiii

Symbian Press Acknowledgments xxv

1 Class Name Conventions on Symbian OS 1

1.1 Fundamental Types 1

1.2 T Classes 3

1.3 C Classes 4

1.4 R Classes 6

1.5 M Classes 7

1.6 Static Classes 11

1.7 Buyer Beware 11

1.8 Summary 12

2 Leaves: Symbian OS Exceptions 13

2.1 Leaving Functions 13

2.2 Heap Allocation Using new (ELeave) 16

2.3 Constructors and Destructors 17

vi CONTENTS

2.4 Working with Leaving Functions 18

2.5 Trapping a Leave Using TRAP and TRAPD 20

2.6 LeaveScan 26

2.7 Summary 27

3 The Cleanup Stack 29

3.1 Using the Cleanup Stack 31

3.2 How Does the Cleanup Stack Work? 35

3.3 Using the Cleanup Stack with Non-CBase Classes 38

3.4 Using TCleanupItem for Customized Cleanup 44

3.5 Portability 46

3.6 An Incidental Note on the Use of Casts 46

3.7 Summary 47

4 Two-Phase Construction 49

5 Descriptors: Symbian OS Strings 55

5.1 Non-Modifiable Descriptors 56

5.2 Modifiable Descriptors 58

5.3 Pointer Descriptors 60

5.4 Stack-Based Buffer Descriptors 63

5.5 Heap-Based Buffer Descriptors 65

5.6 Literal Descriptors 69

5.7 Summary 72

6 Good Descriptor Style 75

6.1 Descriptors as Parameters and Return Types 75

6.2 Common Descriptor Methods 78

6.3 The Use of HBufC Heap Descriptors 82

6.4 Externalizing and Internalizing Descriptors 84

6.5 The Overuse of TFileName 86

6.6 Useful Classes for Descriptor Manipulation 87

6.7 Summary 88

7 Dynamic Arrays and Buffers 91

7.1 CArrayX Classes 92

7.2 RArray<class T> and RPointerArray<class T> 97

7.3 Why Use RArray Instead of CArrayX? 102

7.4 Dynamic Descriptor Arrays 103

7.5 Fixed-Length Arrays 104

7.6 Dynamic Buffers 106

7.7 Summary 109

8 Event-Driven Multitasking Using Active Objects 111

8.1 Multitasking Basics 111

CONTENTS vii

8.2 Event-Driven Multitasking 112

8.3 Working with Active Objects 115

8.4 Example Code 120

8.5 Threads Without an Active Scheduler 123

8.6 Application Code and Active Objects 123

8.7 Summary 124

9 Active Objects under the Hood 127

9.1 Active Object Basics 128

9.2 Responsibilities of an Active Object 131

9.3 Responsibilities of an Asynchronous Service Provider 133

9.4 Responsibilities of the Active Scheduler 134

9.5 Starting the Active Scheduler 135

9.6 Nesting the Active Scheduler 135

9.7 Extending the Active Scheduler 136

9.8 Cancellation 137

9.9 Request Completion 138

9.10 State Machines 138

9.11 Long-Running Tasks 143

9.12 Class CIdle 146

9.13 Class CPeriodic 148

9.14 Common Mistakes 149

9.15 Summary 150

10 Symbian OS Threads and Processes 151

10.1 Class RThread 152

10.2 Thread Priorities 155

10.3 Stopping a Running Thread 157

10.4 Inter-Thread Data Transfer 162

10.5 Exception Handling 163

10.6 Processes 164

10.7 Summary 166

11 The Client–Server Framework in Theory 167

11.1 Why Have a Client–Server Framework? 168

11.2 How Do the Client and Server Fit Together? 168

11.3 How Do the Client and Server Communicate? 170

11.4 What Classes Does the Client–Server Framework Use? 170

11.5 How Do Synchronous and Asynchronous Requests

Differ? 179

11.6 How Is a Server Started? 179

11.7 How Many Connections Can a Client Have? 180

11.8 What Happens When a Client Disconnects? 180

11.9 What Happens If a Client Dies? 181

11.10 What Happens If a Server Dies? 181

viii CONTENTS

11.11 How Does Client–Server Communication Use Threads? 181

11.12 What Are the Implications of Server-Side Active

Objects? 182

11.13 What Are the Advantages of a Local (Same-Process)

Server? 182

11.14 What Are the Overheads of Client–Server

Communication? 183

11.15 How Many Outstanding Requests Can a Client Make to

a Server? 186

11.16 Can Server Functionality Be Extended? 186

11.17 Example Code 186

11.18 Summary 187

12 The Client–Server Framework in Practice 189

12.1 Client–Server Request Codes 190

12.2 Client Boilerplate Code 191

12.3 Starting the Server and Connecting to It from the Client 198

12.4 Server Startup Code 203

12.5 Server Classes 205

12.6 Server Shutdown 213

12.7 Accessing the Server 214

12.8 Summary 214

13 Binary Types 217

13.1 Symbian OS EXEs 217

13.2 Symbian OS DLLs 218

13.3 Writable Static Data 220

13.4 Thread-Local Storage 223

13.5 The DLL Loader 226

13.6 UIDs 226

13.7 The targettype Specifier 228

13.8 Summary 230

14 ECOM 233

14.1 ECOM Architecture 233

14.2 Features of an ECOM Interface 236

14.3 Factory Methods 237

14.4 Implementing an ECOM Interface 240

14.5 Resource Files 242

14.6 Example Client Code 245

14.7 Summary 246

15 Panics 247

15.1 Just-In-Time Debugging 248

15.2 Good Panic Style 249

CONTENTS ix

15.3 Symbian OS Panic Categories 250

15.4 Panicking Another Thread 251

15.5 Faults, Leaves and Panics 253

15.6 Summary 253

16 Bug Detection Using Assertions 255

16.1 __ASSERT_DEBUG 256

16.2 __ASSERT_ALWAYS 261

16.3 Summary 263

17 Debug Macros and Test Classes 265

17.1 Heap-Checking Macros 265

17.2 Object Invariance Macros 270

17.3 Console Tests Using RTest 273

17.4 Summary 276

18 Compatibility 277

18.1 Forward and Backward Compatibility 278

18.2 Source Compatibility 279

18.3 Binary Compatibility 280

18.4 Preventing Compatibility Breaks 281

18.5 What Can I Change Without Breaking Binary

Compatibility? 287

18.6 Best Practice: Planning for Future Changes 289

18.7 Compatibility and the Symbian OS Class Types 291

18.8 Summary 292

19 Thin Templates 293

20 Expose a Comprehensive and

Comprehensible API 299

20.1 Class Layout 300

20.2 IMPORT_C and EXPORT_C 301

20.3 Parameters and Return Values 303

20.4 Member Data and Functional Abstraction 309

20.5 Choosing Class, Method and Parameter Names 312

20.6 Compiler-Generated Functions 314

20.7 Summary 315

21 Good Code Style 317

21.1 Reduce the Size of Program Code 317

21.2 Use Heap Memory Carefully 320

21.3 Use Stack Memory Carefully 325

21.4 Eliminate Sub-Expressions to Maximize Code

Efficiency 328

x CONTENTS

21.5 Optimize Late 330

21.6 Summary 331

Appendix Code Checklist 333

Glossary 339

Bibliography and Online Resources 347

Index 351

Foreword

Charles Davies, Chief Technical Officer, Symbian

Software engineers live in interesting times: software is becoming perva￾sive. We all increasingly rely on our personal computers and use their

software as an essential tool in organizing our lives. But what we ”see” is

just the tip of the iceberg. Most software exists beneath the surface within

a variety of embedded systems such as electronic consumer devices,

motor cars, and aircraft. Symbian OS is targeted at mobile phones – a

class of embedded system that exists in massive volume and which is

used by the entire developed world.

The amount of software built into a mobile phone is expanding rapidly.

In recent times it has outpaced Moore’s law: in the past three years the

amount of embedded software in high-end phones has jumped from

xii FOREWORD

about 2 MB to 20 MB. This is partly required by the sophistication of

new 3G networks, but it is mainly due to mobile phones subsuming

the functionality of other portable consumer devices, such as digital

cameras and camcorders, digital audio players, video players, electronic

organizers, mobile gaming consoles, portable radios, portable TVs, email

terminals, cordless phones and even electronic payment cards. The

mobile phone is becoming the key portable lifestyle support system – an

electronic Swiss army knife.

Symbian OS is needed because this explosion in software-supported

functionality requires a capable operating system that is designed for

sophisticated, always-on, battery-powered mobile devices.

The object-oriented programming paradigm of Symbian OS helps

manage system complexity and permeates the architecture of Symbian

OS. This architecture uses many advanced, but classical, constructs

found in other multitasking operating systems. Examples include pre￾emptive multitasking threads, processes, asynchronous services and

internal servers for serializing access to shared resources. Symbian OS

has some particular features that also need to be understood if one is

to become an effective Symbian OS programmer. These distinct features

have been designed to cope with the rigorous discipline of mobile device

programming, for example, in the handling of asynchronous events and

errors, avoiding memory leakages and other dangling resources.

Software engineers moving from the embedded space will probably

have to make a transition from C to the object-oriented world of C++.

Software engineers moving from the PC space will probably be used to

C++, but will not be used to the tougher disciplines of programming for

mobile phones where robustness, code size, memory usage, performance

and battery life is important, where there are no regular reboots to mop

up memory leaks and where the radio increases and enriches the number

of events to which applications have to respond.

Whatever your background and level of experience, your effectiveness

will be much improved if you read this book and understand the essential

Symbian OS concepts.