Palm OS Programmer's Companion, Vol II
Total Page:16
File Type:pdf, Size:1020Kb
Palm OS® Programmer’s Companion Volume II Communications Written by Greg Wilson, Jean Ostrem, Christopher Bey, Eric Shepherd, and Mark Dugger Technical assistance from Ludovic Ferrandis, Gilles Fabre, David Fedor, Roger Flores, Steve Lemke, Bob Ebert, Ken Krugler, Paul Plaquette, Bruce Thompson, Jesse Donaldson, Tim Wiegman, Gavin Peacock, Ryan Robertson, Andy Stewart, and Waddah Kudaimi Copyright © 1996-2004, PalmSource, Inc. and its affiliates. All rights reserved. This technical documentation contains confidential and proprietary information of PalmSource, Inc. (“PalmSource”), and is provided to the licensee (“you”) under the terms of a Nondisclosure Agreement, Product Development Kit license, Software Development Kit license or similar agreement between you and PalmSource. You must use commercially reasonable efforts to maintain the confidentiality of this technical documentation. You may print and copy this technical documentation solely for the permitted uses specified in your agreement with PalmSource. In addition, you may make up to two (2) copies of this technical documentation for archival and backup purposes. All copies of this technical documentation remain the property of PalmSource, and you agree to return or destroy them at PalmSource’s written request. Except for the foregoing or as authorized in your agreement with PalmSource, you may not copy or distribute any part of this technical documentation in any form or by any means without express written consent from PalmSource, Inc., and you may not modify this technical documentation or make any derivative work of it (such as a translation, localization, transformation or adaptation) without express written consent from PalmSource. PalmSource, Inc. reserves the right to revise this technical documentation from time to time, and is not obligated to notify you of any revisions. THIS TECHNICAL DOCUMENTATION IS PROVIDED ON AN “AS IS” BASIS. NEITHER PALMSOURCE NOR ITS SUPPLIERS MAKES, AND EACH OF THEM EXPRESSLY EXCLUDES AND DISCLAIMS TO THE FULL EXTENT ALLOWED BY APPLICABLE LAW, ANY REPRESENTATIONS OR WARRANTIES REGARDING THIS TECHNICAL DOCUMENTATION, WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING WITHOUT LIMITATION ANY WARRANTIES IMPLIED BY ANY COURSE OF DEALING OR COURSE OF PERFORMANCE AND ANY WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NONINFRINGEMENT, ACCURACY, AND SATISFACTORY QUALITY. PALMSOURCE AND ITS SUPPLIERS MAKE NO REPRESENTATIONS OR WARRANTIES THAT THIS TECHNICAL DOCUMENTATION IS FREE OF ERRORS OR IS SUITABLE FOR YOUR USE. TO THE FULL EXTENT ALLOWED BY APPLICABLE LAW, PALMSOURCE, INC. ALSO EXCLUDES FOR ITSELF AND ITS SUPPLIERS ANY LIABILITY, WHETHER BASED IN CONTRACT OR TORT (INCLUDING NEGLIGENCE), FOR DIRECT, INCIDENTAL, CONSEQUENTIAL, INDIRECT, SPECIAL, EXEMPLARY OR PUNITIVE DAMAGES OF ANY KIND ARISING OUT OF OR IN ANY WAY RELATED TO THIS TECHNICAL DOCUMENTATION, INCLUDING WITHOUT LIMITATION DAMAGES FOR LOST REVENUE OR PROFITS, LOST BUSINESS, LOST GOODWILL, LOST INFORMATION OR DATA, BUSINESS INTERRUPTION, SERVICES STOPPAGE, IMPAIRMENT OF OTHER GOODS, COSTS OF PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, OR OTHER FINANCIAL LOSS, EVEN IF PALMSOURCE, INC. OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES OR IF SUCH DAMAGES COULD HAVE BEEN REASONABLY FORESEEN. PalmSource, the PalmSource logo, BeOS, Graffiti, HandFAX, HandMAIL, HandPHONE, HandSTAMP, HandWEB, HotSync, the HotSync logo, iMessenger, MultiMail, MyPalm, Palm, the Palm logo, the Palm trade dress, Palm Computing, Palm OS, Palm Powered, PalmConnect, PalmGear, PalmGlove, PalmModem, Palm Pack, PalmPak, PalmPix, PalmPower, PalmPrint, Palm.Net, Palm Reader, Palm Talk, Simply Palm and ThinAir are trademarks of PalmSource, Inc. or its affiliates. All other product and brand names may be trademarks or registered trademarks of their respective owners. IF THIS TECHNICAL DOCUMENTATION IS PROVIDED ON A COMPACT DISC, THE SOFTWARE AND OTHER DOCUMENTATION ON THE COMPACT DISC ARE SUBJECT TO THE LICENSE AGREEMENTS ACCOMPANYING THE SOFTWARE AND OTHER DOCUMENTATION. Palm OS Programmer’s Companion, Volume II: Communications PalmSource, Inc. Document Number 3005-009 1240 Crossman Avenue November 9, 2004 Sunnyvale, CA 94089 For the latest version of this document, visit USA http://www.palmos.com/dev/support/docs/. www.palmsource.com Table of Contents About This Document ix Palm OS SDK Documentation . ix What This Volume Contains . ix Additional Resources . x Conventions Used in This Guide . xi 1 Object Exchange 1 About the Exchange Manager . 2 Exchange Libraries . 2 Typed Data Objects . 3 Initializing the Exchange Socket Structure . 4 Identifying the Exchange Library . 5 Identifying the Type of Data . 7 Registering for Data. 8 General Registration Guidelines . 9 Setting the Default Application. 10 Registering to Receive Unwrapped Data . 13 Sending Data. 15 Sending a Single Object . 15 Sending Multiple Objects . 16 Implementing the Send Command . 18 Receiving Data . 19 Controlling the Exchange Dialog . 19 Displaying a Preview . 21 Receiving the Data . 23 Sending and Receiving Databases. 26 Sending a Database. 26 Receiving a Database . 29 Requesting Data . 29 Sending a Get Request for a Single Object . 30 Responding to a Get Request . 30 Two-Way Communications . 30 Requesting a URL . 31 Sending and Receiving Locally . 32 Palm OS Programmer’s Companion, Volume II: Communications iii Interacting with the Launcher . 34 Summary of Exchange Manager . 35 2 Exchange Libraries 37 About Exchange Libraries . 37 Exchange Libraries, Exchange Manager, and Applications . 38 Palm OS Exchange Libraries . 39 Exchange Library Components . 40 The Exchange Library API. 40 Dispatch Table . 42 Implementing an Exchange Library . 46 Required Functions. 46 Registering with the Exchange Manager. 49 Summary of Exchange Library . 49 3 Personal Data Interchange 51 About Personal Data Interchange . 52 About vObjects . 52 Overview of vObject Structure . 53 About the PDI Library. 55 PDI Property and Parameter Types . 56 The PDI Library Properties Dictionary . 57 PDI Readers . 57 PDI Writers . 58 Format Compatibility . 59 International Considerations. 60 Features Not Yet Supported . 60 Using the PDI Library . 61 Accessing the PDI Library . 64 Unloading the PDI Library . 65 Creating a PDI Reader . 65 Reading Properties . 66 Reading Property Values . 67 Creating a PDI Writer . 71 Writing Properties . 72 Writing Property Values. 72 iv Palm OS Programmer’s Companion, Volume II: Communications Specifying PDI Versions. 73 Using UDA for Different Media. 73 About the UDA Library . 73 Using a PDI Reader - An Example . 74 Using a PDI Writer - An Example . 79 Summary of Personal Data Interchange . 83 Summary of Unified Data Access Manager . 84 4 Beaming (Infrared Communication) 85 IR Library . 85 IrDA Stack . 86 Accessing the IR Library . 87 Summary of Beaming . 87 5 Serial Communication 89 Serial Hardware . 90 Byte Ordering . 91 Serial Communications Architecture Hierarchy . 91 The Serial Manager . 92 Which Serial Manager Version To Use . 93 Steps for Using the Serial Manager . 97 Opening a Port. 98 Closing a Port . 101 Configuring the Port . 102 Sending Data . 105 Receiving Data. 106 Serial Manager Tips and Tricks . 112 Writing a Virtual Device Driver . 114 The Connection Manager . 116 The Serial Link Protocol . 120 SLP Packet Structures . 120 Transmitting an SLP Packet . 123 Receiving an SLP Packet . 123 The Serial Link Manager. 124 Using the Serial Link Manager . 124 Summary of Serial Communications . 127 Palm OS Programmer’s Companion, Volume II: Communications v 6 Bluetooth 131 Palm OS Bluetooth System . 131 Bluetooth System Components. 132 Implementation Overview. 135 Profiles . 135 Usage Scenarios . 138 Authentication and Encryption. 138 Device Discovery. 139 Piconet Support . 139 Radio Power Management . 140 Developing Bluetooth-Enabled Applications . 141 Overview of the Bluetooth Library . 142 Management . 142 Sockets . 146 Bluetooth Virtual Serial Driver . 149 Opening the Serial Port . 150 Palm-to-Palm Communication . 153 How Palm OS Uses the Bluetooth Virtual Serial Driver . 154 Bluetooth Exchange Library Support . 154 Detecting the Bluetooth Exchange Library . 154 Using the Exchange Manager With Bluetooth . 155 ExgGet and ExgRequest . 156 7 Network Communication 157 Net Library . 157 About the Net Library . 158 Net Library Usage Steps. 161 Obtaining the Net Library’s Reference Number . 162 Setting Up Berkeley Socket API . 163 Setup and Configuration Calls . 163 Opening the Net Library . 173 Closing the Net Library . 174 Version Checking. 175 Network I/O and Utility Calls . 176 Berkeley Sockets API Functions . 177 vi Palm OS Programmer’s Companion, Volume II: Communications Extending the Network Login Script Support . 184 Socket Notices . 188 Internet Library . 191 System Requirements . 192 Initialization and Setup . 193 Accessing Web Pages . 194 Asynchronous Operation . 194 Using the Low Level Calls . 196 Cache Overview . 197 Internet Library Network Configurations . 197 Summary of Network Communication . 199 8 Secure Sockets Layer (SSL) 203 SSL Library Architecture. 203 Attributes . 206 Always-Used Attributes. 207 Debugging and Informational Attributes . 213 Advanced Protocol Attributes . ..