Legacy Document

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

Chapter 22 - Endpoints Reference / Functions

Functions for Connectionless Transaction-Based Endpoints /

OTRcvUReply

Reads a reply to a request sent by a client using a connectionless transaction-based protocol.

C INTERFACE

OSStatus OTRcvUReply(EndpointRef ref, TUnitReply* reply, 
                                         OTFlags* replyFlags);

C++ INTERFACE

OSStatus TEndpoint::RcvUReply(TUnitReply* reply, 
                     OTFlags* replyFlags);

PARAMETERS

ref

The endpoint reference of the endpoint accepting the reply.

reply

A pointer to a TUnitReply structure that specifies the location to store the reply information.

The reply->addr field specifies the location and size of a buffer containing the address of the endpoint sending the reply. You must allocate a buffer into which the address is placed when the function returns, and you must set the reply->addr.buf field to point to this buffer. You must also set the reply->addr.maxlen field to the maximum size of the buffer.

The reply->opt field specifies the location and size of a buffer containing the association-related options that the responder has sent using the OTSndUReply function. You must allocate a buffer to hold option information and set the reply->opt field to point to it. When the OTRcvUReply function returns, it fills this buffer with option information. You must set the reply->opt.maxlen field to the maximum size necessary to hold option information.

The reply->udata field specifies the location and size of a buffer into which the function places the reply data on return. You must allocate a buffer to hold the data, set the reply->udata.buf field to point to it, and set the reply->udata.maxlen field to the maximum size of this buffer. The size must not exceed the value specified for the tsdu field of the TEndpointInfo structure for this endpoint.

If you have sent out multiple requests, you can use the reply->sequence field to match incoming replies to outgoing requests.

replyFlags

A pointer to a bitmapped long that is filled in by the endpoint provider to indicate whether there is more reply data to be read, in which case you must call the OTRcvUReply function again. A value of T_MORE indicates that the buffer pointed to by udata.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. It is possible that both flags are set.

function result

An error code. See Discussion.

DISCUSSION

You use the OTRcvUReply function to read the reply to a request that you have issued using the OTSndURequest function. The reply parameter points to buffers in which the function stores the reply, the address of the responder, any options connected with this transaction, and the transaction ID for this transaction.

If the endpoint is in asynchronous mode, the provider generates a T_REPLY event to let you know that reply data has arrived. If it should happen that the reply data is sent using multiple calls to the sending function, Open Transport does not generate additional T_REPLY events. To guard against this possibility, your notifier function should call the OTRcvUReply function until it returns the kOTNoDataErr result.

If a transaction has timed out awaiting reply data, the OTRcvUReply 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. If the OTRcvUReply function returns withthe T_PARTIALDATA flag set, you must be prepared to receive a reply to any outstanding request. One way to manage this situation is to call the OTRcvUReply 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 flagPtr setting. Once you determine the matching request and the appropriate reply buffer, you can call the OTRcvUReply 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 OTRcvUReply will read from that same reply until all the data has been read.

If the T_MORE bit is set in the flags parameter, this means your buffer is not large enough to hold the entire reply. You must call the OTRcvURequest 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 flags parameter, this means that the data you read with the OTRcvUReply function does not constitute the entire reply; more data is coming but it has not yet arrived. You must call the function again to read more of, or the rest of, the reply.

If the T_MORE and the T_PARTIALDATA bits are both set, this means that the data you 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.

The following table shows how the endpoint's mode of execution and blocking status affects the behavior of the OTRcvUReply function.

	Blocking	Nonblocking
Synchronous	The function returns when the provider lifts flow-control restrictions and the reply has arrived.	The function returns immediately.
	The kOTFlowErr result is never returned.	The kOTFlowErr result might be returned.
Asynchronous	The function returns immediately. The provider calls your notifier, passing T_REPLY for the code parameter.	The function returns immediately. The provider calls your notifier, passing T_REPLY for the code parameter.
	The kOTFlowErr result might be returned.	The kOTFlowErr result might be returned.

SEE ALSO

The OTSndURequest function.

"AppleTalk Reference".

Table 4-4.