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. [. . . ] 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. The serial port is not actually opened until you do the OTConnect. You make a passive connection by calling OTBind with a qlen of 1. The serial port is opened as part of the binding process. 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. [. . . ] 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. If the ARA Serial Port Arbitrator went away, they would no longer receive an error when other application were using the serial port, with potentially disastrous consequences. So ARA 3. 0 includes a new serial port arbitrator, the OpenTpt Serial Arbitrator, which includes the serial port arbitration functionality of the original Serial Port Arbitrator. [. . . ]