K INSIDE MACINTOSH Open Transport K WWDC Release May 1996 © Apple Computer, Inc. 1994 - 1996 K Apple Computer, Inc. Helvetica and Palatino are authorized to make any modification, © 1994-1996 Apple Computer, Inc. registered trademarks of extension, or addition to this warranty. All rights reserved. Linotype-Hell AG and/or its Some states do not allow the exclusion subsidiaries. No part of this publication may be or limitation of implied warranties or reproduced, stored in a retrieval ITC Zapf Dingbats is a registered liability for incidental or consequential system, or transmitted, in any form trademark of International Typeface damages, so the above limitation or or by any means, mechanical, Corporation. exclusion may not apply to you. This electronic, photocopying, recording, QuickView™ is licensed from Altura warranty gives you specific legal rights, or otherwise, without prior written Software, Inc. and you may also have other rights permission of Apple Computer, Inc., CompuServe is a registered service which vary from state to state. except to make a backup copy of mark of CompuServe, Inc. any documentation provided on Docutek is a trademark of Xerox CD-ROM. Corporation. The Apple logo is a trademark of FrameMaker is a registered Apple Computer, Inc. trademark of Frame Technology Use of the “keyboard” Apple logo Corporation. (Option-Shift-K) for commercial purposes without the prior written NuBus is a trademark of Texas consent of Apple may constitute Instruments. trademark infringement and unfair UNIX is a trademark of UNIX competition in violation of federal System Laboratories, Inc. and state laws. Simultaneously published in the No licenses, express or implied, are United States and Canada. granted with respect to any of the technology described in this book. Apple retains all intellectual Even though Apple has reviewed this property rights associated with the manual, APPLE MAKES NO technology described in this book. WARRANTY OR REPRESENTATION, This book is intended to assist EITHER EXPRESS OR IMPLIED, WITH application developers to develop RESPECT TO THIS MANUAL, ITS applications only for Apple-labeled QUALITY, ACCURACY, or Apple-licensed computers. MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. AS A Every effort has been made to RESULT, THIS MANUAL IS SOLD “AS ensure that the information in this IS,” AND YOU, THE PURCHASER, manual is accurate. Apple is not ARE ASSUMING THE ENTIRE RISK responsible for typographical errors. AS TO ITS QUALITY AND Apple Computer, Inc. ACCURACY. 1 Infinite Loop Cupertino, CA 95014 IN NO EVENT WILL APPLE BE 408-996-1010 LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR Apple, the Apple logo, and CONSEQUENTIAL DAMAGES Macintosh are trademarks of Apple RESULTING FROM ANY DEFECT OR Computer, Inc., registered in the INACCURACY IN THIS MANUAL, United States and other countries. even if advised of the possibility of such Adobe, Acrobat, Adobe Illustrator, damages. Adobe Photoshop, and PostScript THE WARRANTY AND REMEDIES are trademarks of Adobe Systems SET FORTH ABOVE ARE EXCLUSIVE Incorporated or its subsidiaries and AND IN LIEU OF ALL OTHERS, ORAL may be registered in certain OR WRITTEN, EXPRESS OR IMPLIED. jurisdictions. No Apple dealer, agent, or employee is Draft. Confidential. Apple Computer, Inc. 4/25/96 Contents Figures, Tables, and Listings xvii Preface About This Book xxi Format of a Typical Chapter xxiii Conventions Used in This Book xxiv Special Fonts xxiv Types of Notes xxiv The Development Environment xxv Chapter 1 Introduction to Open Transport 1-1 Introduction to Open Transport 1-3 Basic Networking Concepts 1-4 Types of Protocols 1-6 Addressing and Data Delivery 1-8 Protocol Stacks and the OSI Model 1-9 About Networking With Open Transport 1-12 Open Transport Architecture 1-12 Open Transport API 1-14 Software Modules 1-15 Drivers and Hardware 1-15 Providers, Endpoints, and Mappers 1-16 Transport Independence 1-20 Endpoints and Protocol Layering 1-21 Deciding Which Protocol to Use 1-22 General Purpose or Special Purpose 1-23 Choice of Protocol Family 1-23 High-Level or Low-Level Protocol 1-23 Connection-Oriented or Connectionless 1-24 Transaction-Based or Transactionless 1-25 Miscellaneous Events 1-26 iii Draft. Confidential. Apple Computer, Inc. 4/30/96 Chapter 2 Providers 2-1 About Providers 2-3 Provider Functions 2-5 Modes of Operation 2-6 Provider Events 2-7 Using Providers 2-8 Controlling a Provider’s Modes of Operation 2-8 Specifying How Provider Functions Execute 2-9 Setting a Provider’s Blocking Status 2-10 Setting a Provider’s Send-Acknowledgment Status 2-10 Sending and Receiving Data 2-11 Using Notifier Functions to Handle Provider Events 2-13 Transferring a Provider’s Ownership 2-16 Closing a Provider 2-17 Providers Reference 2-17 Constants and Data Types 2-17 Event Codes 2-17 The TNetbuf Structure 2-23 Functions 2-24 Opening and Closing Providers 2-24 Controlling a Provider’s Mode of Operation 2-28 Installing and Removing a Notifier Function 2-40 Sending Module-Specific Commands 2-43 Application-Defined Functions 2-45 Chapter 3 Endpoints 3-1 About Endpoints 3-5 Endpoint Types and Mode of Service 3-7 Naming Conventions for Endpoint Functions 3-8 Endpoint Options 3-10 Modes of Operation 3-11 Blocking 3-12 Acknowledging Sends 3-13 Endpoint States 3-13 Transport Service Data Units 3-19 Using Endpoints 3-20 iv Draft. Confidential. Apple Computer, Inc. 4/30/96 Opening and Binding Endpoints 3-21 Obtaining Information About Endpoints 3-23 Handling Events for Endpoints 3-24 Establishing and Terminating Connections 3-27 Establishing a Connection 3-28 Terminating a Connection 3-35 Sending and Receiving Data 3-40 Sending Noncontiguous Data 3-40 Sending Data Using Multiple Sends 3-41 Receiving Data 3-42 No-Copy Receiving 3-42 Transferring Data Efficiently 3-43 Transferring Data Between Transactionless Endpoints 3-43 Using Connectionless Transactionless Service 3-43 Using Connection-Oriented Transactionless Service 3-44 Transferring Data Between Transaction-Based Endpoints 3-46 Using Connectionless Transaction-Based Service 3-48 Using Connection-Oriented Transaction-Based Service 3-50 Endpoints Reference 3-52 Constants and Data Types 3-52 OTData Constant 3-52 OTBuffer Constant 3-53 Buffer Types Enumeration 3-53 Endpoint Service Types 3-54 Open Transport Flags 3-54 Endpoint Flags 3-55 Endpoint States 3-56 Structure Types 3-57 The TEndpointInfo Structure 3-58 The TBind Structure 3-61 The OTData Structure 3-62 The No-Copy Receive Buffer Structure 3-63 Buffer Information Structure 3-65 The TUnitData Structure 3-65 The TUDErr Structure 3-67 The TUnitRequest Structure 3-68 The TUnitReply Structure 3-70 The TCall Structure 3-72 v Draft. Confidential. Apple Computer, Inc. 4/30/96 The TRequest Structure 3-76 The TReply Structure 3-77 The TDiscon Structure 3-79 Functions 3-80 Creating Endpoints 3-80 Binding and Unbinding Endpoints 3-86 Obtaining Information About an Endpoint 3-91 Allocating Structures 3-102 Checking a Buffer’s Size 3-106 Doing No-Copy Receives 3-107 Functions for Connectionless Transactionless Endpoints 3-110 Functions for Connectionless Transaction-Based Endpoints 3-117 Establishing A Connection 3-130 Functions for Connection-Oriented Transactionless Endpoints 3-140 Functions for Connection-Oriented Transaction-Based Endpoints 3-147 Tearing Down a Connection 3-159 Chapter 4 Mappers 4-1 About Mappers 4-4 Using Mappers 4-5 Setting Modes of Operation for Mappers 4-5 Specifying Name and Address Information 4-7 Searching for Names 4-7 Retrieving Multiple Entries From the Reply Buffer 4-9 Retrieving Entries in Asynchronous Mode 4-11 Mappers Reference 4-12 Constants and Data Types 4-12 The TRegisterRequest Structure 4-12 The TRegisterReply Structure 4-13 The TLookupRequest Structure 4-13 The TLookupReply Structure 4-15 The TLookupBuffer Structure 4-15 Functions 4-16 Creating Mappers 4-17 Registering and Deleting Names 4-21 Looking Up Names 4-26 vi Draft. Confidential. Apple Computer, Inc. 4/30/96 Chapter 5 Option Management 5-1 About Options and Option Negotiation 5-4 Explicit Use of Options and Portability of Code 5-4 Types of Options 5-5 The Format of Option Information 5-8 XTI-Level Options and General Options 5-10 Using Options 5-11 Determining Which Function to Use to Negotiate Options 5-12 Negotiating Options 5-13 Negotiating Multiple Options 5-13 Initiating an Option Negotiation 5-14 Privileged or Read-Only Options 5-15 Error Conditions 5-16 Obtaining the Maximum Size of an Options Buffer 5-18 Setting Option Values 5-18 Specifying Option Values 5-18 Setting Default Values 5-20 Allowing the Endpoint Provider to Select an Option Value 5-21 Retrieving Option Values 5-21 Obtaining Current and Default Values 5-21 Retrieving Values for Connection-Oriented Endpoints 5-22 Retrieving Values for Connectionless Transactionless Endpoints 5-23 Retrieving Values for Connectionless Transaction-Based Endpoints 5-23 Parsing an Options Buffer 5-24 Verifying Option Values 5-25 Option Management Reference 5-25 Constants and Data Types 5-25 XTI-Level Options 5-25 Generic Options 5-28 Status Codes 5-29 Action Flags 5-30 The Linger Structure 5-31 The Keepalive Structure 5-32 The TOption Structure 5-33 The Option Management Structure 5-33 Functions 5-34 Determining and Changing Function Values 5-35 vii Draft. Confidential. Apple Computer, Inc. 4/30/96 Manipulating the Format of Option Information 5-39 Finding Options 5-43 Chapter 6 Configuration Management 6-1 About Provider Configurations 6-3 About Port Information 6-5 Using the Configuration Functions 6-8 Determining Whether Open Transport