Programming PC connectivity applications for Symbian OS

Programming

PC Connectivity

Applications

for Symbian OS

Smartphone Synchronization and Connectivity

for Enterprise and Application Developers

By

Ian McDowall

Reviewed by

Day Barr, Emlyn Howell, Helena Bryant, Paul Newby,

Rob Falla, Simon Didcote, Tony Naggs, Zoe Martin ¨

Symbian Press

Managing editor

Phil Northam

Project editor

Freddie Gjertsen

Programming

PC Connectivity

Applications

for Symbian OS

TITLES PUBLISHED BY SYMBIAN PRESS

• Programming PC Connectivity Applications for Symbian OS

Ian McDowall

0470 090537 477pp 2004 Paperback

• 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, Inc.

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

Programming

PC Connectivity

Applications

for Symbian OS

Smartphone Synchronization and Connectivity

for Enterprise and Application Developers

By

Ian McDowall

Reviewed by

Day Barr, Emlyn Howell, Helena Bryant, Paul Newby,

Rob Falla, Simon Didcote, Tony Naggs, Zoe Martin ¨

Symbian Press

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

McDowall, Ian.

Programming PC connectivity applications for Symbian OS : smartphone

synchronization and connectivity for enterprise and application developers

/ by lan McDowall.

p. cm.

Includes bibliographical references and index.

ISBN 0-470-09053-7 (pbk. : alk. paper)

1. Cellular telephone systems – Computer programs. 2. Operating systems

(Computers) 3. Computer input-output equipment. I. Title.

TK6570.M6M38 2004

005.26

8 – dc22

2004017257

British Library Cataloguing in Publication Data

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

ISBN 0-470-09053-7

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

Author Biography ix

Author’s Acknowledgments xi

Symbian Press Acknowledgments xiii

1 Introduction 1

1.1 What is PC Connectivity and Why is This Book Different

from Other Symbian OS Books ? 2

1.2 What This Book Will Tell You (and What It Will Not) 3

1.3 How This Book is Structured 4

1.4 Conventions Used in This Book 5

1.5 Developer Resources 5

2 A History of Symbian OS and PC Connectivity 7

2.1 A History of Symbian OS 7

2.2 PC Connectivity Using PLP 8

2.3 PC Connectivity Using TCP/IP 8

2.4 PC Connectivity Using OBEX 10

3 An Architectural Overview of PC Connectivity 11

3.1 The Bearers, TCP/IP and PPP 11

3.2 A Client-Server Model of PC Connectivity 12

4 The Symbian Connect Object Model 15

4.1 Overview 15

4.2 Functionality in SCOM and in PC Suites 15

4.3 SCOM and BAL 16

4.4 COM Programming and Language Choice 17

4.5 Error Handling 18

vi CONTENTS

4.6 SCOM Class Reference 18

4.7 BAL Class Reference 33

4.8 Using SCOM in C++ and Visual Basic 37

5 An Example PC Connect Application – a File

Browser 39

5.1 Overview 39

5.2 Connecting to a Phone or Emulator 39

5.3 Accessing SCOM and Connecting to a Device 48

5.4 Handling Differences Between Devices 52

5.5 Copying Files – Asynchronous Actions 53

5.6 Navigating the Filing System 58

5.7 A File Browser Application 60

5.8 Simple Actions on Files and Directories 66

5.9 Error Handling and Disconnection 77

5.10 Visual C++ Code for Application and Device

Management 78

5.11 Visual C++ Code for Drive and Directory Navigation 86

5.12 Visual C++ Code for Synchronous and Asynchronous

Operations 87

6 Programming for Symbian OS 89

6.1 Building a Project 90

6.2 Using the Emulator 96

6.3 Types and Naming Conventions 100

6.4 Error Handling 102

6.5 Descriptors 106

6.6 Arrays 108

6.7 Processes and Threads 109

6.8 Active Objects 110

6.9 Backwards Compatibility and Programming for Multiple

Phone Types 113

7 Developing Custom Servers 117

7.1 Overview of Custom Servers 117

7.2 Limitations of Custom Servers 118

7.3 Custom Servers API 119

7.4 Protocol Conventions 123

7.5 Creating Your First Custom Server 124

7.6 Installing a Custom Server 129

7.7 Starting a Custom Server from SCOM 130

7.8 Communicating with a Custom Server 132

7.9 Asynchronous Communication 133

7.10 Debugging a Custom Server 136

CONTENTS vii

8 Developing Socket Servers 137

8.1 Overview of Connectivity Socket Servers 137

8.2 An Introduction to the Server Socket Classes 138

8.3 Using the Service Broker API 141

8.4 Server Socket Classes 142

8.5 Developing an Echo Socket Server 151

8.6 Installing and Registering a Server Socket Service 161

8.7 Starting a Socket Service from SCOM 163

8.8 Communicating with a Socket Service 164

8.9 Asynchronous Communication 165

8.10 Debugging a Socket Service 165

9 Introducing SMS and Messaging Classes 167

9.1 The Message Server and MTMs 167

9.2 The Structure of Messages 170

9.3 Message Server Events and Sessions 173

9.4 SMS Specific Variations 174

9.5 Common Messaging Classes 175

9.6 SMS Specific Classes 187

10 Developing an SMS Management Connectivity

Service 191

10.1 SMS Management Protocol 191

10.2 Packing and Unpacking Data 200

10.3 Obtaining Access to the Message Server

and the SMS MTM 204

10.4 Listing SMS Messages and Returning Their Contents 206

10.5 Deleting and Creating SMS Messages 209

10.6 Handling Message Server Events 213

10.7 Putting the Messaging Code in a Connectivity Plug-in 215

10.8 A Command-line SMS Application 219

11 Using the Contacts Model 227

11.1 Databases and Models 227

11.2 The Contacts Model 228

11.3 Views 230

11.4 Contacts Observers 230

11.5 Synchronization and Performance Issues 231

11.6 Contacts Model API 231

11.7 A Contacts Connectivity Service 256

12 Using the Agenda Model 283

12.1 The Various Agenda Models 283

viii CONTENTS

12.2 Types of Agenda Entries 284

12.3 Repeating Entries 285

12.4 Alarms 285

12.5 List and Filter Classes 286

12.6 Agenda Model API 286

12.7 An Agenda Connectivity Service 325

13 Developing a Specialized Connectivity GUI

Application 347

13.1 What is Special About a GUI Application? 347

13.2 Managing Connections to Phones 347

13.3 Starting a PC Connectivity Service 351

13.4 Communicating and Managing Delays 351

13.5 A GUI SMS Application 358

13.6 A Contacts GUI Application 367

13.7 An Agenda GUI Application 384

13.8 Conclusion and Ideas for Further Development 396

14 Starting General Socket Servers 397

14.1 Communicating with a Socket Server 398

14.2 Starting a Server 400

15 Connectivity Dos and Don’ts 403

15.1 Protocol Design 403

15.2 Robustness and Defensive Design 406

15.3 Device and Service Management 407

15.4 General Development and Debugging Skills 410

Appendix 1 Developer Resources 413

Appendix 2 Specifications of Symbian OS Phones 421

Index 441

Author Biography

Ian joined Symbian in 2000 and is currently a technology architect

responsible for connectivity. He has previously filled roles ranging from

developer through project manager to technical manager by way of

quality manager and process consultant (including presentation at inter￾national conferences).

He has an MA in Computer Sciences from Cambridge University and

an MBA from Warwick University. As a software engineer for over twenty

years he has been with a number of software companies and has worked

on more than fifteen operating systems, developing software ranging from

enterprise systems to embedded software. He is married to Lorraine and

they have two children, Ross and Kelly, and a number of pets.

Author’s Acknowledgments

I would like to thank the members of the PC Connectivity team and others

in Symbian’s Software Engineering Department who have made this book

possible. In the PC Connectivity team Day Barr, Simon Didcote and Paul

Newby have provided essential information and suggestions, and in other

teams Emlyn Howell, Tony Naggs and David Cunardo have provided

invaluable advice on the best use of Symbian’s Messaging, Contacts and

Agenda APIs.

I would like to thank Zo¨e Martin, Colin Turfus and Ian Weston for their

support in promoting the wider use of PC Connectivity software.

The other reviewers have also been both diligent and construc￾tive – Helena Bryant and Rob Falla (who also suggested the original

idea for this book).

I must thank Freddie Gjertsen and Phil Northam of Symbian Press for

promoting the concept of this book inside and outside Symbian and for

their patient checking and support.

I would also like to thank all the engineers in Symbian and elsewhere

who have made Symbian’s PC Connectivity software what it is today.

Finally, I would like to thank my family who have put up with my

work on this book for more than a year.

Symbian Press Acknowledgments

Symbian Press would like to thank Ian for his perseverance in adversity.

And all those who reviewed the book, mentioned or otherwise. And those

who worked ‘behind the scenes’ to allow this book to be realized. And,

of course, the BA cabin-crew for always looking after the Symbian Press

‘frequent flyer’ so splendidly. And the wonderful Loza, Symbian Press

Officer extraordinaire.

Cover concept by Jonathan Tastard.