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