Legacy Document

Important: The information in this document is obsolete and should not be used for new development.

Inside Macintosh: Networking With Open Transport / Part 1 - Open Transport Essentials: Chapter 19 - Serial Endpoint Providers

Using Serial Endpoints
Serial endpoint providers use standard Open Transport functions for binding, requesting and accepting connections, sending and receiving data, and managing options. You can send and receive the desired data using the standard Open Transport OTSnd and OTRcv functions. You can call these functions either synchronously or asynchronously, as described in the chapter "Endpoints".
In addition, Open Transport provides specialized serial-specific commands and options that allow you to

set the flow-control handshaking
use an external timing signal for synchronous clocking
set or clear a break signal
get status information about a port and any associated transmission errors
define how characters with parity errors are handled
request burst mode operation
define receive timeout options
set the framing type

Opening and Closing Serial Endpoints
To open serial endpoints, you need to supply a configuration string to the OTOpenEndpoint function. The configuration string you supply depends on which serial port you want to open. The following constants are defined for the built-in ports; you can find other serial ports using the techniques descripted in "Ports".
Constant name String value Description
kSerialName "serial" Default serial port
kSerialPortAName "serialA" Serial port A
(printer port)
kSerialPortBName "serialB" Serial port B
(modem port)
kSerialPortABName "serialAB" Serial port AB
(combined printer/modem port)

For example, the following line of code opens a serial endpoint on serial port A:
OTOpenEndpoint(OTCreateConfiguration(kSerialPortAName));
There may be other serial ports available, such as those registered by the Communications Toolbox.
To close a serial endpoint provider, you use the standard Open Transport function OTCloseProvider, described in the chapter "Providers".

Sending and Receiving Data
As with all endpoints, you must call the OTBind function before you can use a serial endpoint provider to send or receive data. For serial endpoint providers that initiate outgoing data, you need to bind with a queue length (the qlen parameter) of 0. When you wish to start transferring data, you must call the OTConnect function to place the endpoint in the data transfer state and allow the OTSnd and OTRcv functions to be called. Calling the OTSndDisconnect function releases the connection.
For serial endpoint providers that listen for incoming data, you need to bind with a queue length of 1. You cannot bind with a queue length greater than 1. When an incoming character is detected on the serial port, you receive a connect indication. You can accept the indication on the current endpoint, or you can accept it on another serial endpoint, that has a queue length of 0 or is not yet bound. In either case, once the accepting endpoint returns to the T_IDLE state, the original endpoint once again listens for incoming data and gets a connect indication if another incoming character is detected. Calling the OTSndDisconnect function on the accepting endpoint releases the connection and allows your endpoint to continue listening on the port. Your endpoint can continue to listen until you call the OTUnbind function.
You can create a number of serial endpoints on a given serial port, but only one can have a connection at a time. The first serial endpoint to connect owns the hardware; other endpoints that subsequently attempt to connect receive a kOTAddressBusyErr result code.

Using Serial-Specific Commands
You can control several aspects of serial communication by using the Open Transport function OTIoctl with different serial-specific commands. The OTIoctl function, described in the chapter "Providers Reference", accesses the low-level serial driver control and status functions.
You can assert the DTR signal for the serial port by using a value of kOTSerialSetDTROn with the I_SetSerialDTR command and you can negate it with a value of kOTSerialSetDTROff. Likewise, you can use the I_SetSerialBreak command to set or negate the break signal with values of kOTSerialSetBreakOn and kOTSerialSetBreakOff or you can use a number greater than 1 to indicate the number in milliseconds to assert a break signal temporarily.
You can also use the OTIoctl function commands to set the XOFF state of the serial port and to indicate whether the port is to send an XOFF or XON character. Using a value of kOTSerialForceXOffTrue with the I_SetSerialXOffState command sets the XOFF state of the serial port, which is equivalent to receiving an XOFF character, and using a value of kOTSerialForceXOffFalse with this command clears the XOFF state, which is equivalent to receiving an XON character.
Using a value of 1 with the I_SetSerialXOn and I_SetSerialXOff commands causes the serial port to unconditionally send an XON or XOFF character, respectively. A value of 0 with these functions causes the character to be sent only if the last input flow-control character sent was the opposite kind--that is, the XOFF or XON character, respectively.

Using Options to Change Serial Communications Settings
Serial endpoints currently support eight options. These options are defined by the XTI-level constant COM_SERIAL, which has a value of 'SERL'.
When you open a serial endpoint, Open Transport configures the selected port with the default settings of 19200 baud, 8 data bits per character, no parity bit, 1 stop bit, and no handshaking. You can change these settings using various options, all of which use 4-byte unsigned integer values. There is also a serial status option that provides current information about the serial port. Four of the options are fairly straightforward and are described here; using the other options is more complicated, and their use is described in the two subsequent sections.

The baud rate option sets the serial baud rate.The serial module chooses the closest baud rate supported that matches the requested rate. Possible values range from 300 to 230.4K baud transmission rates (depending on the hardware capability). The default value is 19200 baud.
The data bits option selects the number of data bits to be used. Legal values are 5, 6, 7, and 8. The default value is 8 data bits.
The stop bits option selects the number of stop bits to be used. This value corresponds to ten (10) times the actual number of stop bits. Legal values are 10, 15, and 20, which correspond to stop bits of 1, 1.5, and 2. The default value is 10, which is equivalent to 1 stop bit.
The parity option selects the parity to be used. Legal values are kOTNoParity 0), kOTOddParity(1), and kOTEvenParity(2). The default value is kOTNoParity.
The receive timeout option sets the number of milliseconds the receiver should wait to receive more data before timing out and delivering the data is already has. The default value is 10.
The error character option defines how characters with parity errors are handled--that is, if they are replaced and with which character. Open Transport provides macros (and C++ inline functions), OTSerialSetErrorCharacter and OTSerialSetErrorCharacterWithAlternate, to help place the character bits correctly.
The external clock option requests an external clock. This option may not be supported by all serial drivers.
The burst mode option requests that the serial driver continues looping, reading incoming characters, rather than waiting for an interrupt for each character. This option may not be supported by all serial drivers.

Controlling Serial Port I/O Handshaking
You can use the SRL_OPT_HANDSHAKE option to customize serial port handshaking in a variety of ways. For instance, you can request that an input handshake be controlled by the CTS line, or by the XON/XOFF sequence. To control the handshaking behavior, you pass in a 4-byte usigned integer value with the SRL_OPT_HANDSHAKE option.
A schematic diagram of this 4-byte option value is shown in Figure 19-2
Figure 19-2 Serial port I/O handshaking

The high word (16 bits) of the integer is a bitmap with one or more of the following bits set:
Handshake Value Description
kOTSerialXOnOffInputHandshake 1 XON/XOFF set for input.
kOTSerialXOnOffOutputHandshake 2 XON/XOFF set for output.
kOTSerialCTSInputHandshake 4 CTS set on input.
kOTSerialDTROutputHandshake 8 DTR set on output.

The third byte is the XON character value; the lowest byte is the XOFF character. If these values are 0 and XON/OFF handshaking is requested, the default values of control-S for XOFF and control-Q for XON are used. The default value of this option is no handshaking.
Open Transport provides a macro and a C++ inline function (OTSerialHandshakeData) that you can use to create the 4-byte option value.
For example, to enable XON/XOFF input handshaking, but to specify that the XON character be control-T rather than control-Q, you can create an option structure as follows:
opt.value = OTSerialHandshakeData( kOTSerialXOnOffInputHandshake | 
                        kOTSerialXOnOffOutputHandshake,
                              'T' - 64, 'S' - 64);
Obtaining Status Information About the Serial Port
The serial status option is a read-only option that returns status information on the serial port. It is a 4-byte unsigned integer containing a bitmap that can provide the following information about errors or changes in status that may have occurred:

A hardware overrun has occurred due to an overflow of the hardware input buffer.
A software overrun has occurred due to an overflow of the software input buffer.
A parity error has occurred due to the serial hardware detecting an incorrect parity bit.
A framing error has occurred due to the serial hardware detecting a stop bit error.
A break has occurred on the line.
The endpoint provider has sent an XOFF character, which initiates flow control.
The endpoint provider has negated the DTR signal, which initiates flow control.
The endpoint provider has negated the CTS signal, which initiates flow control.
The endpoint provider has received an XOFF character, and so all output is on hold.
The endpoint provider has initiated a break that is still in progress.

Data received from the serial port passes through a hardware buffer and then into a software buffer managed by the input driver for the port. Each input driver's buffer can initially hold up to 1024 characters, but you can specify a larger buffer with standard Open Transport functions. This is normally not necessary because Open Transport provides additional buffering as part of its processing.
Open Transport serial services are layered on top of the serial hardware driver. The capabilities of Open Transport endpoints depend on the driver. Consult the hardware documentation to determine the limitations of Open Transport for serial endpoints.
Because the serial hardware in some Macintosh computers relies on processor interrupts during I/O operations, overrun errors are possible if interrupts are disabled while data is being received on the serial port. To prevent such errors, the Disk Driver and other system software components are designed to store any data received by the modem port while they have interrupts disabled and then pass this data to the port's input driver. Because the system software only monitors the modem port, the printer port is not recommended for two-way communication at data rates above 300 baud.
Overrun, parity, and framing errors are usually handled by requesting that the sender retransmit the affected data. Break errors are typically initiated by the client application, which handles them as appropriate.

Using General Open Transport Functions With Serial Endpoints
This section describes any special considerations that you must take into account for Open Transport functions when you use them with serial endpoint providers. You should be familiar with the function descriptions in the chapter "Endpoints" before reading this section.

Obtaining Endpoint Data With Serial Endpoints
This section describes the possible values you can get for endpoint information when using a serial endpoint.

OTOpenEndpoint, OTAsyncOpenEndpoint, and OTGetEndpointInfo
The following values can be returned by the info parameter to the OTOpenEndpoint, OTAsyncOpenEndpoint, and OTGetEndpointInfo functions when used with serial endpoint providers:
Parameter Serial Meaning
info->addr 0 Addresses are not used.
info->options Greater than 0 Maximum number of bytes needed to hold protocol-specific options.
info->tsdu T_INVALID TSDUs are not supported.
info->etsdu T_INVALID Transfer of expedited data is not supported.
info->connect T_INVALID Data cannot be sent with functions that establish connections.
info->discon T_INVALID Data cannot be sent with abortive disconnects.
info->servtype T_COTS Connection oriented transactionless service. Orderly disconnects are not supported.
info->flags - No flags are set.

IMPORTANT
The values shown in the preceding table are subject to change. Be sure to use the OTOpenEndpoint, OTAsyncOpenEndpoint, and OTGetEndpointInfo functions to obtain the current values for these parameters.
These fields and the significance of their values are described in more detail in the chapter "Endpoints Reference".

Using Endpoint Functions With Serial Endpoints
This section describes serial-specific information about functions described in the chapter "Endpoints".

OTBind
The OTBind function associates a serial port with the endpoint you specify. Because serial communication is point-to-point over a hardware connection, you cannot specify an address. Therefore, you must specify 0 as the length of the address in the reqaddr->TBind.addr.len parameter. You can bind multiple serial endpoints to listen at a single port.
With serial endpoints, the req->qlen parameter, which specifies the number of outstanding connection requests that an endpoint can support, can only have a value of 0 or 1. To listen, a serial endpoint provider must have a queue length value of 1; to make connections, the endpoint can have a value of 0 or 1. A value greater than 1 results in an error code.

OTConnect
The OTConnect function requests a connection to a specified remote endpoint.
Because serial endpoint providers do not allow you to send any application-specific data during the connection establishment phase, you must set the sndcall->udata.len field to 0. Serial endpoints ignore the sndcall->udata.buf field.

OTListen
The OTListen function listens for an incoming connection request.
Serial endpoints do not allow application-specific data to be included when you request a connection, so you need to set the call->udata.maxlen field to 0. Serial endpoints ignore the call->udata.buf field.

OTAccept
The OTAccept function accepts a connection request. You can accept a connection either on the same endpoint that received the connection request or on a different endpoint.
Serial endpoints do not allow application-specific data to be included when you accept a connection, so you need to set the call->udata.len field to 0. Serial endpoints ignore the call->udata.buf field.

OTSnd
The OTSnd function sends data through a connection-oriented transactionless endpoint. Serial endpoints do not support TSDUs.

OTRcv
The OTRcv function receives data through a connection-oriented transactionless endpoint. Serial endpoints do not support TSDUs.

OTSndDisconnect
The OTSndDisconnect function initiates an abortive disconnect or rejects a connection request.
In an abortive disconnect, the call parameter is ignored because serial endpoints do not allow application-specific data to be associated with a disconnect. You need to set the call->udata.len field to 0. Serial endpoints ignore the call->udata.buf field.

OTRcvDisconnect
The OTRcvDisconnect function returns information about why a connection attempt failed or an established connection was terminated.
Because serial endpoints do not allow application-specific data to be associated with a disconnect, you need to set the discon->udata.maxlen field to 0. Serial endpoints ignore the discon->udata.buf field.

Subtopics
Opening and Closing Serial Endpoints

Sending and Receiving Data

Using Serial-Specific Commands

Using Options to Change Serial Communications Settings

Controlling Serial Port I/O Handshaking

Obtaining Status Information About the Serial Port

Using General Open Transport Functions With Serial Endpoints

Obtaining Endpoint Data With Serial Endpoints

OTOpenEndpoint, OTAsyncOpenEndpoint, and OTGetEndpointInfo

Using Endpoint Functions With Serial Endpoints

OTBind

OTConnect

OTListen

OTAccept

OTSnd

OTRcv

OTSndDisconnect

OTRcvDisconnect

Constant name	String value	Description
`kSerialName`	`"serial"`	Default serial port
`kSerialPortAName`	`"serialA"`	Serial port A (printer port)
`kSerialPortBName`	`"serialB"`	Serial port B (modem port)
`kSerialPortABName`	`"serialAB"`	Serial port AB (combined printer/modem port)

Handshake	Value	Description
`kOTSerialXOnOffInputHandshake`	1	XON/XOFF set for input.
`kOTSerialXOnOffOutputHandshake`	2	XON/XOFF set for output.
`kOTSerialCTSInputHandshake`	4	CTS set on input.
`kOTSerialDTROutputHandshake`	8	DTR set on output.

Parameter	Serial	Meaning
`info->addr`	0	Addresses are not used.
`info->options`	Greater than 0	Maximum number of bytes needed to hold protocol-specific options.
`info->tsdu`	`T_INVALID`	TSDUs are not supported.
`info->etsdu`	`T_INVALID`	Transfer of expedited data is not supported.
`info->connect`	`T_INVALID`	Data cannot be sent with functions that establish connections.
`info->discon`	`T_INVALID`	Data cannot be sent with abortive disconnects.
`info->servtype`	`T_COTS`	Connection oriented transactionless service. Orderly disconnects are not supported.
`info->flags`	-	No flags are set.