K INSIDE MACINTOSH Networking With Open Transport K Revised for version 1.3 November 1997 © Apple Computer, Inc. 1994 - 1997 K Apple Computer, Inc. Helvetica and Palatino are damages, so the above limitation or © 1994-1997 Apple Computer, Inc. registered trademarks of exclusion may not apply to you. This All rights reserved. Linotype-Hell AG and/or its warranty gives you speciÞc legal rights, and you may also have other rights No part of this publication may be subsidiaries. which vary from state to state. reproduced, stored in a retrieval ITC Zapf Dingbats is a registered system, or transmitted, in any form trademark of International Typeface or by any means, mechanical, Corporation. electronic, photocopying, recording, NuBus is a trademark of Texas or otherwise, without prior written Instruments. permission of Apple Computer, Inc., PowerPC is a trademark of except to make a backup copy of International Busines Machines any documentation provided on Corporation, used under license CD-ROM. therefrom. The Apple logo is a trademark of UNIX is a regisered trademark in Apple Computer, Inc. the United States and other Use of the ÒkeyboardÓ Apple logo countries, licensed exclusively (Option-Shift-K) for commercial through X/Open Company, Ltd. purposes without the prior written Simultaneously published in the consent of Apple may constitute United States and Canada. trademark infringement and unfair competition in violation of federal and state laws. Even though Apple has reviewed this No licenses, express or implied, are manual, APPLE MAKES NO granted with respect to any of the WARRANTY OR REPRESENTATION, technology described in this book. EITHER EXPRESS OR IMPLIED, WITH Apple retains all intellectual RESPECT TO THIS MANUAL, ITS property rights associated with the QUALITY, ACCURACY, technology described in this book. MERCHANTABILITY, OR FITNESS This book is intended to assist FOR A PARTICULAR PURPOSE. AS A application developers to develop RESULT, THIS MANUAL IS SOLD ÒAS applications only for Apple-labeled IS,Ó AND YOU, THE PURCHASER, or Apple-licensed computers. ARE ASSUMING THE ENTIRE RISK Every effort has been made to AS TO ITS QUALITY AND ensure that the information in this ACCURACY. manual is accurate. Apple is not IN NO EVENT WILL APPLE BE responsible for typographical errors. LIABLE FOR DIRECT, INDIRECT, Apple Computer, Inc. SPECIAL, INCIDENTAL, OR 1 InÞnite Loop CONSEQUENTIAL DAMAGES Cupertino, CA 95014 RESULTING FROM ANY DEFECT OR 408-996-1010 INACCURACY IN THIS MANUAL, even if advised of the possibility of such Apple, the Apple logo, Macintosh, damages. AppleTalk, EtherTalk, ImageWriter,LaserWriter, LocalTalk, THE WARRANTY AND REMEDIES Mac, MPW, and TokenTalk are SET FORTH ABOVE ARE EXCLUSIVE trademarks of Apple Computer, Inc., AND IN LIEU OF ALL OTHERS, ORAL registered in the United States and OR WRITTEN, EXPRESS OR IMPLIED. other countries. No Apple dealer, agent, or employee is Adobe, Acrobat, and PostScript are authorized to make any modiÞcation, trademarks of Adobe Systems extension, or addition to this warranty. Incorporated or its subsidiaries and Some states do not allow the exclusion may be registered in certain or limitation of implied warranties or jurisdictions. liability for incidental or consequential Contents Figures, Tables, and Listings xxi Preface About This Book xxvii For More Information xxviii Format of a Typical Chapter xxix Conventions Used in This Book xxxi Special Fonts xxxi Types of Notes xxxi The Development Environment xxxii Part 1 Open Transport Essentials 1 Chapter 1 Introduction to Open Transport 3 Introduction to Open Transport 5 Basic Networking Concepts 6 Types of Protocols 8 Addressing 10 Protocol Stacks and the OSI Model 11 About Networking With Open Transport 14 Open Transport Architecture 14 Open Transport API 16 Software Modules 17 Drivers and Hardware 17 Open Transport and Interrupt-Time Processing 18 Providers: Endpoints, Mappers, and Services 18 Transport Independence 22 Endpoints and Protocol Layering 22 Deciding Which Protocol to Use 23 General Purpose or Special Purpose 23 Choice of Protocol Family 24 iii High-Level or Low-Level Protocol 24 Connection-Oriented or Connectionless 25 Transaction-Based or Transactionless 25 Summary 26 Chapter 2 Getting Started With Open Transport 29 Initializing Open Transport 31 Initializing From a Client Application 32 Initializing From a Stand-Alone Code Resource 33 Using ASLM and Open Transport 33 Using the Gestalt Function to Determine Whether Open Transport Is Available 34 ConÞguring and Opening a Provider 34 Creating a ConÞguration Structure 35 Opening a Provider 36 Reusing Provider ConÞgurations 37 Specifying an Address 37 Addressing in Open Transport 37 Using TNetBuf Structures 38 Storing an Address in a TNetBuf Structure 40 Using Helper Routines to Initialize an Address 40 Closing Open Transport 42 Closing From Applications 42 Closing From Stand-Alone Code 43 Open Transport Libraries 44 Downloading a URL With HTTP 45 Using Threads for Easy Synchronous Processing 50 Specifying the Host Names and HTTP Commands 51 Opening an Endpoint and Setting the Mode of Operation 52 Connecting to the Host and Sending Data 53 Receiving Data From the Remote Endpoint 54 Error Handling 55 Unbinding the Endpoint and Final Clean-Up 56 iv Chapter 3 Providers 59 About Providers 61 Provider Functions 63 Interrupt-Time Processing 64 Modes of Operation 65 Provider Events 67 Function Results 68 Using Providers 69 Controlling a ProviderÕs Modes of Operation 70 Which Mode To Use 70 Specifying How Provider Functions Execute 71 Setting a ProviderÕs Blocking Status 72 Setting a ProviderÕs Send-Acknowledgment Status 72 Using NotiÞer Functions to Handle Provider Events 73 Transferring a ProviderÕs Ownership 77 Closing a Provider 79 Chapter 4 Endpoints 81 About Endpoints 83 Endpoint Types and Type of Service 85 Naming Conventions for Endpoint Functions 85 Endpoint Options 87 Modes of Operation 88 Endpoint States 89 Transport Service Data Units 98 Using Endpoints 99 Opening and Binding Endpoints 100 Obtaining Information About E ndpoints 101 Handling Events for Endpoints 102 Clearing Events and Synchronization Problems 104 NotiÞer Reentrancy 104 Polling for Events 105 Establishing and Terminating Connections 105 Establishing a Connection 107 Terminating a Connection 112 Sending and Receiving Data 118 v Sending Data Using Multiple Sends 118 Receiving Data 119 Transferring Data Between Transactionless Endpoints 119 Using Connectionless Transactionless Service 119 Using Connection-Oriented Transactionless Service 120 Transferring Data Between Transaction-Based Endpoints 121 Using Connectionless Transaction-Based Service 123 Using Connection-Oriented Transaction-Based Service 125 Chapter 5 Programming With Open Transport 127 Open Transport Programming Models 129 Using Synchronous Processing With Threads 130 Polling for Events 132 Using Asynchronous Processing With a NotiÞer 134 Interrupt-Safe Functions 136 Memory Management From NotiÞers 136 Interrupt Levels and Open Transport Processing 136 Hardware Interrupt Level 136 Deferred Task Level 137 System Task Level 138 Using Timer Tasks 139 Using System and Deferred Tasks 139 Calling Open Transport Functions 140 Scheduling Tasks 140 Deallocating Resources 141 Handling Synchronization Problems 141 Handling Multiple Simultaneous Connections 142 Problems With Accepting Multiple Simultaneous Connections 142 Using "tilisten" to Accept Multiple Simultaneous Connections 143 Improving Performance 144 Streamlining Endpoint Creation 144 Handling Dead Clients 145 Shutting Down Servers 146 vi Chapter 6 Mappers 147 About Mappers 150 Using Mappers 150 Setting Modes of Operation for Mappers 151 Specifying Name and Address Information 152 Searching for Names 153 Retrieving Entries in Asynchronous Mode 154 Code Sample: Using OTLookupName 155 Chapter 7 Option Management 163 About Options and Option Negotiation 166 Explicit Use of Options and Portability of Code 166 Types of Options 167 The Format of Option Information 167 XTI-Level Options and General Options 169 Using Options 171 Determining Which Function to Use to Negotiate Options 171 Obtaining the Maximum Size of an Options Buffer 172 Setting Option Values 172 Specifying Option Values 173 Setting Default Values 174 Retrieving Option Values 174 Obtaining Current and Default Values 175 Parsing an Options Buffer 175 Verifying Option Values 176 Sample Code: Getting and Setting Options 177 Chapter 8 Ports 189 About Ports 191 Identifying Ports 192 Port Name 192 Port Reference 192 Multiport IdentiÞers 192 Pseudodevices 193 vii Port Structures 193 Using Ports 194 Obtaining Port Information 195 Requesting a Port to Yield Ownership 198 Registering as an Open Transport Client 198 Chapter 9 Utilities 201 About Utility Functions 203 Using List Management Functions 204 Chapter 10 Advanced Topics 213 Acknowledging Sends 215 Sending Noncontiguous Data 216 No-Copy Receiving 218 Using Raw Mode 225 Using Option Management to Set Raw Mode 225 Testing for Raw Mode Support 227 Sending and Receiving in Raw Mode at the Protocol Level 227 Chapter 11 TCP/IP Services 235 About the TCP/IP Protocol Family 237 About TCP/IP Services 240 About the Open Transport DNR 243 About Single Link Multi-Homing 243 ConÞguring Your System to Use Multiple IP Addresses 244 Checking for Availability 245 Getting Information About Secondary Addresses 245 Using TCP/IP Services 245 Setting Options When ConÞguring a TCP/IP Provider 245 Using RawIP 247 Receiving RawIP Datagrams 248 Sending RawIP Datagrams 248 Manually Setting the IP Header