Legacy Document

Inside Macintosh: Networking With Open Transport / Part 2 - Open Transport Reference

Chapter 22 - Endpoints Reference / Functions

Functions for Connection-Oriented Transaction-Based Endpoints /

OTRcvReply

Reads a transaction reply sent by a connection-oriented responder.

C INTERFACE

OSStatus OTRcvReply(EndpointRef ref,
                     TReply* reply, 
                                         OTFlags* replyFlags);

C++ INTERFACE

OSStatus TEndpoint::RcvReply(TReply* reply, 
                     OTFlags* replyFlags);

PARAMETERS

ref

The endpoint reference of the endpoint reading the reply.

reply

A pointer to a TReply structure that specifies where to store the reply information. You must allocate buffers to contain the reply data, option values, and the transaction ID of the request to which the reply is being sent, and you must specify the maximum size of this data.

The reply->data.buf field points to a buffer in which the reply data is to be stored. Set the reply->data.maxlen field to the maximum size of the reply data.

The reply->opt.buf field points to a buffer in which option values are stored. Set the reply->opt.maxlen field to the maximum size of this data.

The reply->sequence field specifies the transaction ID of the transaction to which the reply is sent. If you have sent out multiple requests, you can examine this field to match replies to requests.

replyFlags

A bitmapped 32-bit value specifying T_MORE or T_PARTIALDATA. A value of T_MORE indicates that the buffer pointed to by reply->data.buf is too small to contain the reply. A value of T_PARTIALDATA indicates that the data unit being read does not contain the complete reply and that the next data unit might belong to a different transaction.

function result

An error code. See Appendix B, and Discussion.

DISCUSSION

You use the OTRcvReply function to read the reply to a request that you sent using the OTSndRequest function.

If the endpoint is in asynchronous mode, the endpoint provider issues the T_REPLY event to let you know that incoming reply data is available. After you retrieve this event, using the OTLook function or your notifier function, you must call the OTRcvReply function repeatedly to read the reply data until it returns kOTNoDataErr. The endpoint provider does not generate additional T_REPLY events until you have read the complete reply.

If a transaction has timed out awaiting reply data, the OTRcvReply function returns a kETIMEDOUTErr result; the sequence field of the reply parameter specifies which request has timed out.

If you have issued multiple requests, it is not possible to know ahead of time how incoming replies match your requests. You must be prepared to receive a reply to any outstanding request. One way to manage this situation is to call the OTRcvReply function with the reply->udata.maxlen field set to 0. The rest of the information returned by the function on this first call lets you know the sequence number of the reply as well as the replyFlags setting. Once you determine the matching request and the appropriate reply buffer, you can call the OTRcvReply function a second time to read the actual reply data. On the second and subsequent reads, Open Transport sets the reply->opt.len field to 0. It is guaranteed that once a reply has been partially read, subsequent calls to OTRcvReply read from that same reply until all the available data has been read. The T_PARTIALDATA event might be returned if the entire reply is not available.

If the T_MORE bit is set in the replyFlags parameter, this means your buffer is not large enough to hold the entire reply. You must call the OTRcvRequest function again to retrieve more request data. Open Transport ignores the addr and opt fields of the reply parameter for subsequent calls to the function. The T_MORE flag is not set for the last reply packet to let you know that this is the last packet.

If the T_PARTIALDATA bit is set in the replyFlags parameter, this means that the data you are about to read with the OTRcvReply function does not constitute the entire reply and that more data is coming, but it has not yet arrived. You must call the function again to read more, or the rest, of the reply.

If the T_MORE and the T_PARTIALDATA bits are both set, this means that the data you are about to read constitutes only part of the reply and that your buffer is too small to contain even this chunk. In this case, you must call the function again until the T_MORE flag is clear. The T_PARTIALDATA bit is set only on the first call to the function.

If you are communicating with multiple responders and if the OTRcvUReply function returns with the T_PARTIALDATA flag set, it is possible that your next call to the function might not read the rest of the reply because the next data unit coming in belongs to a different reply. One way to handle this situation is to use the next call to the OTRcvReply function to determine the sequence number of the incoming reply (by setting req->udata.maxlen to 0) and then, having determined which reply data is coming in, read the data into the appropriate buffer.

SEE ALSO

The OTSndRequest function.

Table 4-4.