Technical Q&A DV39

Serial API Choice

Q: Given that the Carbon specification says that classic serial won't be supported in Carbon but the Open Transport API will be, should I convert my serial code to use Open Transport serial endpoints?

A: No. There is no point converting your code to use the Open Transport API because the Open Transport compatibility layer on Mac OS X will not support serial endpoints. If you read the Carbon specification carefully, it says that Carbon only guarantees TCP/IP protocol endpoint support (TCP, UDP, RawIP). Other endpoint types may work (for example, on traditional Mac OS, serial endpoints work just fine from within Carbon), but this won't always be the case.

The following table summarizes the support for the two APIs in the various environments.

For more details on what will and won't be supported by Carbon, read the Carbon Specification.

Q: What serial API should I use for new development?

A: There are a number of considerations here:

• Open Transport serial will continue to be supported on traditional Mac OS, both for Carbon and non-Carbon applications.
• Open Transport serial will not be supported under Carbon on Mac OS X.
• Classic serial will not be supported under Carbon on traditional Mac OS or Mac OS X.
• To talk to serial ports on Mac OS X you should use a combination of the IOKit API (to enumerate the ports) and the BSD "termios" API (to actually talk to a port). The DTS sample code SerialPortSample shows how to do this.
• On traditional Mac OS, Open Transport serial is layered on top of classic serial by a compatibility shim inside Open Transport.
• When deciding which serial API to use, you should take into account the following points.
  • Classic serial offers the best flexibility, performance and responsiveness.
  • Open Transport serial is easier to use if you are already working within the Open Transport world (for example, you are turning telnet code into terminal code, or building a STREAMS plug-in that needs serial).
  • If you have working code, there is no future compatibility benefit to be gained by moving it from classic serial to Open Transport serial, or vice versa.
• When writing a serial driver for traditional Mac OS, you should write a Device Manager (either 'ndrv' or 'DRVR') driver and register it with Communications Resource Manager. Open Transport's serial shim will then work with your driver automatically, and both Open Transport and classic serial clients will be able to use it. If you write an Open Transport (TPI) driver, only Open Transport serial clients will be able to use your driver.

Regardless of the serial API you choose, you should be familiar with the information in Technote 1119, Serial Port Apocrypha.