Inside the Macintosh® Communications Toolbox i Linotronic is a registered APPLE COMPUTER, INC. trademark of Linotype Co. Copyright © 1991 by Apple MacPaint is a registered trademark Computer, Inc. of Claris Corp. All rights reserved. No part of this Microsoft is a registered publication may be reproduced, trademark of Microsoft Corp. stored in a retrieval system, or transmitted, in any form or by Teletype is a registered trademark of AT&T any means, mechanical, electronic, Teletype Corp. photocopying, recording, or Varityper is a registered trademark of Varityper, otherwise, without prior written Inc. permission of Apple Computer, Inc. Printed in the United States ISBN 0-201-57775-5 of America. 1 2 3 4 5 6 7 8 9-MU-9594939291 © Apple Computer, Inc., 1991 Publications staff for Inside the 20525 Mariani Avenue Macintosh Communications Cupertino, CA 95014-6299 Toolbox (408)996-1010 Writer: Rob Berkowitz Apple, the Apple logo, APDA, AppleLink, AppleShare, AppleTalk, Editors: Scott Smith, Becky Reece HyperCard, LaserWriter, Macintosh, Art Director: Tamara Whiteside MacTerminal, and MultiFinder are Production Editors: registered trademarks of Apple Charlotte Clark, Ron Morton Computer, Inc. Designer: Lisa Mirski Apple Desktop Bus, QuickDraw, and SuperDrive are trademarks of Manufacturing Supervisor: Apple Computer, Inc. Robin Kerns Adobe Illustrator and PostScript are registered trademarks of Adobe Systems, Inc. DEC, VAX, VT52, VT100, VT101, VT102, VT220, VT300, and VT320 are trademarks of Digital Equipment Corp. ITC Garamond and ITC Zapf Dingbats are registered trademarks of International Typeface Corp. ii Contents Contents Figures and Tables / ix Foreword / xi Preface / xiii 1 About the Macintosh Communications Toolbox / 1 Communications Toolbox contents / 3 Understanding routines and tools / 4 System requirements and installation / 5 2 Programming with the Macintosh Communications Toolbox / 7 Menu events / 10 Handling menu choices / 10 Initiating a connection /11 Terminating the connection / 11 Starting to send a file / 12 Starting to receive a file / 13 Configuring a connection / 14 Configuring a terminal emulation / 14 Configuring a file transfer / 15 Making a new session document / 16 Closing the session document / 19 Other events / 20 Activate events / 20 Resume events / 20 Update events / 21 Keyboard events / 22 Mouse events / 23 Main program loop / 24 iii 3 Connection Manager / 27 About the Connection Manager / 29 Connection channels: data, attention, and control / 30 The connection record / 31 Connection record data structure / 31 Connection Manager routines / 35 Preparing to open a connection / 36 Custom configuration of a connection tool / 43 Interfacing with a scripting language / 47 Opening, using, and closing the connection / 48 Reading and writing data / 56 Handling events / 61 Localizing configuration strings / 63 Miscellaneous routines / 64 Completion routines / 66 Quick reference / 67 4 Terminal Manager / 75 About the Terminal Manager / 77 The terminal emulation window / 78 The terminal emulation region / 79 The cache region / 79 The terminal record / 80 Terminal record data structure / 80 Terminal Manager routines / 87 Preparing for a terminal emulation / 88 Custom configuration of a terminal tool / 94 Interfacing with a scripting language / 98 Using terminal emulation routines / 99 Searching the terminal emulation buffer / 102 Manipulating selections / 104 Handling events / 105 Localizing configuration strings / 108 Miscellaneous routines / 109 Routines that must be in your application / 114 Sample routine for sending data / 115 Sample showing how to break a connection / 115 Sample showing how to cache lines / 116 Sample terminal-environment routine / 118 Quick reference / 119 iv Contents 5 File Transfer Manager / 127 About the File Transfer Manager / 129 The file transfer record / 130 File transfer record data structure / 131 File Transfer Manager routines / 137 Preparing for a file transfer / 138 Custom configuration of a file transfer tool / 144 Interfacing with a scripting language / 148 Transferring files / 149 Handling events / 151 Localizing configuration strings / 153 Miscellaneous routines / 154 Routines your application provides / 156 Sample send routine / 157 Sample receive routine / 158 Sample connection-environment routine / 160 Quick reference / 161 6 Communications Resource Manager / 167 About the Communications Resource Manager / 169 Device management / 170 Resource management / 170 The communications resource record / 171 Communications resource record data structure / 171 Communications Resource Manager routines / 173 Resource management routines / 177 Resource-mapping routines / 180 Registering a device / 182 Data structures / 182 Searching for serial port devices / 184 Quick reference / 185 7 Macintosh Communications Toolbox Utilities / 189 Communications Toolbox utilities / 191 Manipulating dialog item lists (DITLs) / 198 Special ways to append items / 200 Showing AppleTalk entities: NULookup and NuPLookup / 202 Hook and filter procedures / 206 Quick reference / 211 Contents v 8 Fundamentals of Writing Your Own Tools / 215 About writing a tool / 217 The six resources / 217 The bundle resource / 218 The validation code resource / 219 The setup definition code resource / 221 The scripting language interface code resource 226 The localization code resource / 229 Quick reference / 231 9 Writing Connection Tools / 233 Your connection tool’s main code resource / 235 Quick reference / 251 10 Writing Terminal Tools / 255 Your terminal tool’s main code resource / 257 Quick reference / 273 11 Writing File Transfer Tools / 277 Your file transfer tool’s main code resource / 279 Quick reference / 283 Appendix A Guidelines for Communications Tools / 285 Design goals / 286 Keeping your tool self-contained / 286 Keeping your tool task-specific / 286 User interface considerations / 287 Modeless tool operation / 288 The standard tool-settings dialog box / 288 Windows and status dialog boxes / 289 Error alerts / 290 Menus / 290 Handling errors / 290 Using the right words / 291 Compatibility requirements / 291 Keyboard considerations / 291 vi Contents Appendix B Communications Tools Scripting Interfaces / 293 Six rules for configuration strings / 294 ADSP Tool scripting interface / 295 Apple Modem Tool scripting interface / 299 LAT Tool scripting interface / 301 Serial Tool and Serial NB Tool scripting interface / 302 Text Tool scripting interface / 303 TTY Tool scripting interface / 304 VT102 Tool scripting interface / 305 VT320 Tool scripting interface / 309 XMODEM Tool scripting interface / 313 Appendix C Useful Code Samples / 315 Using FTExec and TMIdle effectively / 316 Determining events for Communications Toolbox managers / 319 The custom tool-settings dialog box / 323 Choose.p / 323 Choose.r / 330 Determining whether the managers are installed / 332 Using the scripting interface / 333 Glossary / 337 Index / 339 Contents vii viii Contents Figures and Tables CHAPTER 1 About the Macintosh Communications Toolbox Figure 1-1 Where the Macintosh Communications Toolbox fits in / 3 Figure 1-2 How Macintosh Communications Toolbox managers interact with applications and tools / 5 CHAPTER 3 Connection Manager Figure 3-1 Data flow into and out of the Connection Manager / 29 Figure 3-2 A sample tool-settings dialog box / 41 CHAPTER 4 Terminal Manager Figure 4-1 Data flow into and out of the Terminal Manager / 77 Figure 4-2 A terminal emulation window / 78 Figure 4-3 Bounds of viewRect and termRect / 84 Figure 4-4 The text selection mode selTextNormal / 86 Figure 4-5 The text selection mode selTextBoxed / 86 Figure 4-6 A sample tool-settings dialog box / 92 Figure 4-7 Additional space in the terminal emulation region / 113 Table 4-1 TmAddsearch search-area delimiters / 102 CHAPTER 5 File Transfer Manager Figure 5-1 Data flow into and out of the File Transfer Manager / 129 Figure 5-2 A sample tool-settings dialog box / 142 CHAPTER 6 Communications Resource Manager Figure 6-1 Data flow into and out of the Communications Resource Manager / 169 CHAPTER 7 Macintosh Communications Toolbox Utilities Figure 7-1 Pop-up menu in its inactive and active states / 193 Figure 7-2 Pop-up menu control when system justification is teJustRight / 196 Figure 7-3 Initial dialog box and to-be-appended items / 198 Figure 74 Dialog box after appended items are superimposed / 199 Figure 7-5 Dialog box after items are appended to the right / 199 Figure 7-6 Dialog box after items are appended to the bottom / 199 ix Figure 7-7 Dialog box after items are appended relative to item 2 / 200 Figure 7-8 Network look-up dialog box / 202 Table 7-1 TMAddSearch search-area delimiters / 205 CHAPTER 8 Fundamentals of Writing Your Own Tool Table 8-1 Connection Manager messages and parameters / 232 CHAPTER 9 Writing Connection Tools Table 9-1 Connection Manager messages and parameters / 253 CHAPTER 10 Writing Terminal Tools Table 10-1 Terminal Manager messages and parameters / 275 CHAPTER 11 Writing File Transfer Tools Table 11-1 File Transfer Manager messages and parameters / 284 APPENDIX A Guidelines for Communications Tools Figure A-1 A sample tool-settings dialog box for a connection tool / 288 Figure A-2 Example file transfer tool status dialog box / 289 x Figures and Tables Foreword One thing I like most about being at Apple is the gifted people who make innovation the norm. Also, it’s a rush to feel the energy people radiate when they believe that what they do can make a difference in the world. The creators of the Macintosh Communications Toolbox