Inside Macintosh: Networking With Open Transport / Part 1 - Open Transport Essentials

Chapter 16 - AppleTalk Data Stream Protocol (ADSP)

Using ADSP

To use Open Transport ADSP, you first open an endpoint as an ADSP endpoint. This causes Open Transport to allocate the memory ADSP needs for data buffers and for storing the variables ADSP uses to maintain the connection between endpoints. After a connection is established, ADSP manages and controls the data flow between two endpoints throughout a session to ensure that data is delivered and received in the order in which it was sent and that duplicate data is not sent.

As with other connection-oriented protocols, Open Transport ADSP allows you to create a passive endpoint that listens for incoming connection requests rather than initiating such requests. In addition, the implementation of ADSP under Open Transport includes some ADSP-specific features that are specific to the two AppleTalk connection-oriented protocols:

• an option to enable end-of-message (EOM) indicators that let you break streams of data into logical units

• locally implemented orderly disconnects rather than over-the-wire remote disconnects

ADSP also implements a separate data channel for expedited data. This provides an attention-message facility that lets ADSP endpoints signal each other outside the normal exchange of data.

Binding ADSP Endpoints

You have two choices when you bind an ADSP endpoint: You can create an endpoint that can initiate and accept connections, or you can create an endpoint that can only receive connection requests.

If the endpoint can initiate connections, you can bind it as a normal Open Transport endpoint and use any of the three AppleTalk address formats for the socket address: DDP, NBP, or the combined DDP-NBP format. If the bind is successful, the endpoint is ready for use in establishing and using a connection.

The other choice when binding an ADSP endpoint is to establish it as a passive peer that listens for incoming connection requests. The passive endpoint can accept or deny a connection request based on criteria that you define. The use of a passive peer is typical of a server environment in which a server, such as a file server, is registered with a single NBP name. Endpoints throughout the network can contact the server's passive peer with connection requests. The server can accept or deny a request. It might deny a request, for example, when its resources are exhausted.

To create a passive peer that listens, you specify a qlen field value greater than 0 during the binding process. The number you use determines how many outstanding connection requests the endpoint can support. Once you bind a passive peer, it starts listening for incoming connection requests. When a request arrives, the endpoint retrieves certain information about the request and continues to process it by accepting or rejecting it.

You can bind multiple ADSP endpoints to the same DDP socket, and ADSP can support as many connections on a socket as you have memory for, but you can only have one passive peer that listens on a given socket.

Sending and Receiving ADSP Data

ADSP supports two separate data channels: one for normal data and one for expedited data. You can send a stream of normal data that has no logical boundaries that need to be preserved across the connection, or you can use transport service data units (TSDUs) to separate the data stream into discrete logical units when sending and receiving data across a connection. For expedited data, you can use expedited transport service data units, or ETSDUs.

By default, ADSP does not support TSDUs. Instead, ADSP sends and receives a continuous stream of data with no message delimiters. If you do not change this through the use of options, ADSP endpoints act much like other connection-oriented transactionless endpoints, and the bulk of your code would be reusable for other types of protocols (such as TCP).

Open Transport uses a flag in the send and receive functions to indicate multiple sends and receives. The use of this flag, the T_MORE flag, allows you to break up a large data stream without losing its logical boundaries at the other end of the connection. The flag, however, indicates nothing about how the data is packaged for transport on the lower-level protocols below the ADSP endpoint provider.

The End-of-Message Option

If transport independence is not crucial for your application, you can use the ADSP enable EOM (OPT_ENABLEEOM) option that allows infinite length TSDUs on the normal data channel.

If you enable the EOM option, you can send any length TSDU by setting the T_MORE flag on each send to indicate to the provider that another packet is coming that is part of this same message. When you send data without the T_MORE flag set, the provider knows this is the end of the message, and it sends an EOM packet to the remote peer. It is possible for the EOM packet to contain no data because ADSP supports the sending of zero-length packets. This is useful when you send a packet with the T_MORE flag set only to discover that you have no more data to send. In this case, ADSP still expects another packet, but you have no data to put into it. You can send a zero-length packet to set the T_MORE flag correctly.

You can enable the EOM option for an endpoint in several ways. One way
is to define the option as part of the configuration string you use to open
the endpoint. The following line of code enables the EOM option for an
ADSP endpoint:

          OTOpenEndpoint(OTCreateConfiguration("adsp(EnableEOM=1)"),0, NULL, &err);

Or you could call a function like that shown in Listing 7-5 as follows:

err=SetFourByteOption(ep, ATK_ADSP, OPT_ENABLEEOM, 1);

to enable the EOM option for an ADSP endpoint.

The Checksum Option

You can use the OPT_CHECKSUM option to force ADSP to send all outgoing packets with the checksum option enabled. By default, outgoing ADSP packets do not use this option, which directs DDP to compute a checksum and include it in each packet that it sends to the remote endpoint provider, since using checksums slows communications slightly. Normally, ADSP and DDP perform enough error checking to ensure safe delivery of all data, so set this option only if the network is highly unreliable.

Sending Expedited Data

In addition to the full-duplex data stream that an ADSP session maintains, ADSP allows either end of a connection to send an expedited attention message to the other end without interrupting the primary flow of data. Processing expedited data takes precedence over handling normal data, so when an expedited data packet arrives at an endpoint, the endpoint reads this packet before reading the next normal data packet. Both the send and receive functions have a flag, T_EXPEDITED, that indicates when a packet has expedited data.

Expedited transport service data units, ETSDUs, can be up to 572 bytes long, including a 2-byte attention code at the beginning of the user data portion. The minimum ETSDU for ADSP is 2 bytes, so if you send less than that, the data is padded to 2 bytes before being transmitted. If you use ETSDUs, you are responsible for ensuring that the code has a value from $0000 to $EFFF and is not in the reserved range of $F000 to $FFFF.

Note that not every connection-oriented transactionless protocol supports attention messages or expedited data. Therefore, using this option compromises the transport independence of your application.

Disconnecting

As with all connection-oriented Open Transport protocols, ADSP supports abortive disconnects. In addition, ADSP supports orderly disconnects, although it can only implement them locally.

An abortive disconnect directs the endpoint to abruptly tear down its connection without making any accomodation for the data that may be in the transmission pipeline at the time. You can define your own handshake, perhaps using the expedited data channel, to prevent losing data during the disconnection process.

ADSP implements orderly disconnects locally, not over the wire. This means that immediately after you request the disconnect, ADSP sends all data buffered at the local end and then tears down the connection, breaking communication with the remote end. As a result, no data can be sent from either the local or remote endpoint. The endpoints can continue to process data already in their receive queues, but no new data can go out.

Using General Open Transport Functions With ADSP

This section describes any special considerations you must take into account for Open Transport functions when you use them with the Open Transport ADSP implementation.

OTBind

The OTBind function associates a local protocol address with the endpoint provider specified by the ref parameter.

You can bind multiple ADSP endpoints to a single protocol address, but you can bind only one passive peer endpoint that listens on that socket.

With ADSP, as with other connection-oriented protocols, the req->qlen parameter specifies the number of outstanding connection requests that an endpoint can support. The endpoint can negotiate a lower final value of qlen if it cannot handle the requested number of outstanding connection requests.

OTConnect

The OTConnect function requests a connection to a specified remote endpoint.

ADSP does not allow application-specific data to be included when you establish a connection, so you need to set the sndcall->udata.len field to 0. ADSP ignores the sndcall->udata.buf field.

OTRcvConnect

The OTRcvConnect function reads the status of a previously issued connection request.

Because ADSP does not allow application-specific data to be associated with a connection request, you need to set the call->udata.maxlen field to 0. ADSP ignores the call->udata.buf field.

OTListen

The OTListen function listens for an incoming connection request.

ADSP does 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. ADSP ignores 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.

ADSP does 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. ADSP ignores the call->udata.buf field.

OTSnd

The OTSnd function sends normal and expedited data through a connection-
oriented transactionless endpoint.

ADSP supports TSDUs through the OPT_ENABLEEOM option. In ADSP, TSDUs can be of infinite length and ETSDUs can be up to 572 bytes long. Zero-length packets are supported in ADSP.

OTRcv

The OTRcv function receives normal and expedited data through a connection-
oriented transactionless endpoint.

ADSP supports TSDUs through the OPT_ENABLEEOM option.

OTSndDisconnect

The OTSndDisconnect function initiates an abortive disconnect or rejects a connection request.

When you call this function with ADSP, you receive a T_ORDREL asynchronous event rather than a T_DISCONNECT asynchronous event so that you can continue to read in the rest of the data in your receive queue. Otherwise, with a T_DISCONNECT event, any remaining unread data is discarded.

In an abortive disconnect, the call parameter is ignored because ADSP does not allow application-specific data to be associated with a disconnect. You need to set the call->udata.len field to 0. ADSP ignores the call->udata.buf field.

OTRcvDisconnect

The OTRcvDisconnect function returns information about why a connection attempt failed or an established connection was terminated.

Because ADSP does not allow application-specific data to be associated with a disconnect, you need to set the discon->udata.len field to 0. ADSP ignores the discon->udata.buf field. The discon->reason field contains a positive error code indicating why the connection was rejected.

---

Subtopics

Binding ADSP Endpoints

Sending and Receiving ADSP Data

The End-of-Message Option

The Checksum Option

Sending Expedited Data

Disconnecting

Using General Open Transport Functions With ADSP

OTBind

OTConnect

OTRcvConnect

OTListen

OTAccept

OTSnd

OTRcv

OTSndDisconnect

OTRcvDisconnect