Inside Macintosh: Open Transport /

Chapter 15 - Printer Access Protocol (PAP)

Using PAP

To use Open Transport PAP, you first open an endpoint as a PAP endpoint, which causes Open Transport to allocate the memory PAP needs for data buffers and for storing the variables PAP uses to maintain the connection between endpoints. After a connection is established, PAP manages and controls the data flow between the 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.

Communication between two client applications using PAP occurs over a connection between two endpoints that provides reliable data delivery. When you bind a PAP endpoint, the binding process associates a local protocol address with the endpoint. In PAP, this identifies the socket address, and PAP uses this as part of the address for sending and receiving packets of data. Each socket can maintain concurrent PAP connections with several other sockets, but there can be only one PAP connection between any two sockets at one time.

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

• an end-of-message option that lets you divide streams of data into
  logical units
• locally implemented orderly disconnects rather than over-the-wire remote disconnects

A feature unique to PAP is the ability to arbitrate connections requests and to retry attempts to open a connection. This allows PAP printer servers to accept requests from the workstations that have been waiting the longest to print, and it allows PAP workstations to keep trying to get their print request through to the printer.

Binding PAP Endpoints

You have two choices when binding a PAP endpoint: You can create an endpoint that can initiate connections and receive connection requests, or you can create a passive endpoint that can only receive connection requests. Typically, a passive PAP endpoint is a printer server.

If your 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 a PAP endpoint is to establish it as a passive peer that listens for incoming connection requests. The passive peer 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 printer server, is registered with a single name. Endpoints throughout the network can contact the printer server 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 queue length greater than 0 during the binding process. The number you use determines how many connection requests the endpoint can support. Once the endpoint is bound, it starts listening for incoming connection requests. When a request arrives, the endpoint retrieves certain information about the request and continues to process the connection request by accepting or rejecting it.

You can bind multiple PAP endpoints to the same socket, but you can have only one passive peer that listens for a given socket. When a server accepts a connection from a client workstation for processing its print request, it cannot accept another connection request from the same workstation endpoint. As with other connection-oriented protocols, you can only have one connection between the same pair of endpoints.

Specifying PAP Options

You can send a PAP data stream that has no logical boundaries within it 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 it across a connection.

By default, PAP does not support TSDUs. Instead, PAP sends and receives a continuous stream of data with no message delimiters, which means you can exchange data with an endpoint whose protocol does not support TSDUs. If you do not specify any PAP-specific options, your packets are not restricted to Open Transport PAP endpoints, and you can provide transport-independent data transmission.

The Enable End-of-Message Option

If transport independence is not crucial for your application, you can use a PAP-specific option that allows TSDUs. The OPT_ENABLEEOM option enables the PAP end-of-message feature, which permits dividing data streams into smaller logical units. 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 PAP endpoint provider.

To send a data stream that is broken up into TSDUs, you set the T_MORE flag on each send. This indicates to the remote connection end that there are more packets coming that are part of this same data stream. When a packet arrives without the T_MORE flag set, the remote end knows this is the last packet for this stream of data. It is possible for this last packet to contain no data because PAP supports the sending of zero-length packets. This could occur 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, PAP 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.

Because printers expect an EOM indicator on the last packet, if you do not choose to use the OPT_ENABLEEOM option, PAP takes care of that for you, guaranteeing that the EOM indicator is set on the last packet. If, however, you do choose to use the OPT_ENABLEEOM option, you are responsible for setting the EOM indicator, by using the T_MORE flag on every packet but the last.

When you use TSDUs with PAP, you cannot change the size of the TSDU after you have established the connection with another endpoint. This means that you don't need to double-check the TSDU size after the first packet because it will always be the same for all packets using this connection.

The Open Retry Option

When a PAP endpoint provider calls the OTConnect function, which creates a connection request, by default it does not try a second time to establish the connection. The PAP default for this option is a value of 1, which refers to the number of times that PAP tries to open a connection, which means that PAP permits only the initial OTConnect request. (Given the effect of its default value, you might find it easier to think of this option as the try open connection option, rather than as the retry open connection option.)

Note

The default value of 1 for this option differs from the default retry count of 5 specified in Inside AppleTalk, second edition. In other aspects of Open Transport AppleTalk, AppleTalk protocols adhere to the specifications detailed in that book.

To force PAP to try again to open the connection, you can use a value greater than 1 for the PAP_OPT_OPENRETRY option. Note that if you change the value of this option, you compromise the transport independence of your application. Thus, if you need to retry sending the open connection packets, you must deliberately choose to use the option and make your code transport dependent. Workstation client applications that want to print data, for example, will probably keep trying to get access to a printer server, retrying printer connections until the user presses the cancel button. Once the user requests a halt, of course, PAP stops trying to connect.

The Server Status Option

In a client-server interaction, a client may sometimes need to know the status of the server. In these cases, the client can request the server's status. This request can occur outside a connection. If the OPT_SERVERSTATUS option has been set, with a C string 255 bytes long, the server can return that string as the server status.

Disconnecting

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

An abortive disconnect directs the remote 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 to prevent losing data during the disconnect process.

PAP implements orderly disconnects locally, not over the wire. This means that immediately after you request the disconnect, PAP 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 PAP

This section describes any special considerations you must take into account for Open Transport functions when you use them with the Open Transport PAP implementation. These may mean using specific parameter values or using specific Open Transport functions. For example, PAP only works with two of the Open Transport sending and receiving functions, OTSnd and OTRcv, because only these work with protocols that are connection-oriented and transactionless. You must be familiar with the function descriptions in the chapter "Endpoints" in this book before reading this section.

OTBind

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

You can bind multiple PAP endpoints to a single protocol address, but you can bind only one passive endpoint that listens at that address.

With PAP, 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 the final value of qlen if it cannot handle the requested number of outstanding connection requests, but in PAP, the value of qlen cannot be negotiated to 0 from a requested value greater than 0.

OTConnect

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

PAP 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. PAP ignores the sndcall->udata.buf field.

OTRcvConnect

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

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

OTListen

The OTListen function listens for an incoming connection request.

PAP does not allow application-specific data to be included when you request a connection, so you need to set the call->udata.len field to 0. PAP ignores any data in the call->udata.buf field.

OTAccept

The OTAccept function accept a connection request either on the same endpoint that received the connection request or on a different endpoint.

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

OTSnd

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

PAP supports TSDUs through the OPT_ENABLEEOM option, although its use compromises the transport independence of your application. In PAP, TSDUs sent from the client endpoint can be of infinite length, but TSDUs sent from a server endpoint can only be up to 512 bytes long. Zero-length packets are supported by PAP.

OTRcv

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

PAP supports TSDUs through the OPT_ENABLEEOM option, although its use compromises the transport independence of your application. In PAP, TSDUs sent from the client endpoint can be of infinite length, but TSDUs sent from a server endpoint can only be up to 512 bytes long. Zero-length packets are supported by PAP.

OTSndDisconnect

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

In an abortive disconnect, the call parameter is ignored because PAP does not allow application-specific data to be associated with a disconnect. You need to set the call->udata.len field to 0. PAP 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 PAP does not allow application-specific data to be associated with a disconnect, you need to set the discon->udata.len field to 0. PAP ignores in the discon->udata.buf field.