User manual KEYSPAN TN1119 TECHNICAL NOTE

[. . . ] TN 1119: Serial Port Apocrypha Page: 1 NOTE: This Technical Note has been retired. Please see the Technical Notes page for current documentation. CONTENTS Notes for Both APIs Just The Facts: Classic Serial Just The Facts: OT Serial A Tale of Two Arbitrators Summary References Downloadables This Technote describes a number of problems often encountered by developers when dealing with serial ports under Mac OS. Most of this information is available from other sources, but those sources are obscure and commonly overlooked. Specifically, this Note describes the correct techniques for finding, opening, closing, and yielding serial ports under the classic serial API and the Open Transport serial API. [. . . ] Back to top Just The Facts: Open Transport Serial Open Transport provides a second API for serial on Mac OS, one that has much in common with the network APIs provided by OT. In the current implementation of OT (version 1. 3 at the time of writing), the OT serial API is implemented as a shim layered on top of the classic serial drivers. This fact is important because the way you use the OT serial API affects the availability of serial ports to the classic API, and vice versa. Inside Macintosh: Open Transport contains a lot of background material that you might find useful. See Technical Q&A NW 48 "68K Open Transport Code on Power Macintoshes" for details. Note: The routine OTGetUserPortNameFromPortRef is defined in the"OpenTptConfig. h" header file. This file is not in Universal Interfaces, but it is included in the full OT SDK. Look for it in the "Open Tpt Protocol Developer" folder. OT 1. 1. 1 (and later) will automatically register any CRM serial port as an OT serial port, so this technique will see built-in and third party serial ports. You can determine the currently installed version of OT using Gestalt, as described in Q&A NW 41 "Gestalt Selectors for Mac Networking. " Opening the Serial Port Once you know which serial port to use, you can call OTOpenEndpoint to create an endpoint to that serial port. However, OT does not actually open the underlying serial driver until you use that endpoint to make an active or passive connection. You make an active connection by first calling OTBind with a qlen of 0 and then calling OTConnect. Your notifier will receive a T_LISTEN event when the first characters arrive at the serial port. Your program should be sure to register itself as an OT client (using OTRegisterAsClient) so that it receives important notifications about the serial port it is using. Specifically, you should be prepared to handle the kOTYieldPortRequest notification, as described in the section on yielding. Also, your endpoint's notifier should be prepared to handle the kOTProviderIsDisconnected and kOTProviderIsReconnected notifications. Closing the Serial Port Once you're done with the serial port, you should be sure to close it. The exact point at which the underlying serial port is closed depends on how you opened it. If you made an active connection, you can close the serial port by disconnecting (taking the endpoint to state T_IDLE), typically using the OTSndDisconnect routine. If you made a passive connection, you can close the serial port by using OTUnbind to unbind the endpoint. Of course, if you close the endpoint (using OTCloseProvider), the serial port will always be closed. Unlike classic serial, Open Transport does keep track of which applications are using which serial ports. If your application unexpectedly quits, OT will automatically close all of its endpoints and thereby close any serial ports it had open. [. . . ] The serial driver returns portInUse when the serial hardware is being used by some other driver. The Link Tool Manager API, which ARA uses to open a serial port in passive mode, was never publicly documented. TN 1119: Serial Port Apocrypha Page: 10 The Newer Solution Unfortunately, in computers, stability is death, and this is as true for ARA as it is for any other part of Mac OS. Part of the plan for ARA 3. 0 was to get rid of the Link Tool Manager, and its associated Serial Port Arbitrator. However, by the time ARA 3. 0 became a reality, developers were used to the Serial Port Arbitrator and were happily calling OpenDriver to open the serial port. [. . . ]