Legacy Document

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

Chapter 22 - Endpoints Reference / Functions

Functions for Connectionless Transaction-Based Endpoints /

OTRcvURequest

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

C INTERFACE

OSStatus OTRcvURequest(EndpointRef ref,
                                         TUnitRequest* req, 
                                         OTFlags* reqFlags);

C++ INTERFACE

OSStatus TEndpoint::RcvURequest(TUnitRequest* req, 
                                         OTFlags* reqFlags);

PARAMETERS

ref

The endpoint reference of the endpoint accepting the request.

req

A pointer to a TUnitRequest structure that contains information about the request being received.

The req->addr field specifies the location and size of a buffer containing the address of the endpoint that made the request; the field is filled in by the OTRcvURequest function when it returns. You must allocate a buffer to hold address information and set the req->addr.buf field to point to it. You must also set the req->addr.maxlen field to the maximum size of the address.

The req->opt field specifies the location and size of a buffer containing the association-related options specified by the requester. Otherwise, this buffer is empty. When the OTRcvURequest function returns, it places option information in this buffer. You must allocate a buffer to contain the option information and set the req->opt.buf field to point to this buffer. You must set the req->opt.maxlen field to the maximum size necessary to hold option information for the endpoint.

The req->udata field specifies the location and size of a buffer containing the request. You must allocate a buffer into which the OTRcvURequest function can place the request and set the req->udata.buf field to point to it. You must set the req->udata.maxlen field to the maximum size of the request data.

The value of the req->sequence field is generated by the endpoint provider when you read the request. You need to save this value and use it for the req->sequence field when sending a reply or cancelling the transaction.

reqFlags

A bitmapped 32-bit value set by the endpoint provider that specifies whether the request is acknowledged (T_ACKNOWLEDGED) and whether there is more request data coming (T_MORE) or (T_PARTIALDATA). A value of T_MORE indicates that the buffer you have allocated is too small to contain the reply. A value of T_PARTIALDATA indicates that the data unit being read does not contain the complete request. It is possible that all flags are set.

function result

An error code. See Discussion.

DISCUSSION

You use the OTRcvURequest function to read an incoming request. When the function returns, it fills in the TUnitRequest structure (referenced by the req parameter) with the address of the sender, the request data, and any association-related options pertaining to this request. If the buffer you allocated for the address is not big enough, the function returns with the kOTBufferOverflowErr result and the incoming request is dropped.

If the endpoint is in synchronous mode and is blocking, the OTRcvURequest function waits for a request to arrive. If the endpoint is in asynchronous mode or is not blocking, the OTRcvURequest function retrieves the next pending unread request or returns the kOTNoDataErr result if there are no pending requests.

If the endpoint is in asynchronous mode, the endpoint provider generates a T_REQUEST event when a request arrives. You can poll the endpoint using the OTLook function or use a notifier function to retrieve this event. You should then call the funtion to retrieve request data until the function returns with the kOTNoDataErr result.

If the T_MORE bit is set in the flags parameter, this means your buffer is not large enough to hold the entire request. You must call the OTRcvURequest function again to retrieve more request data. Open Transport ignores the addr and opt fields of the req parameter for subsequent calls to the OTRcvURequest function. The T_MORE flag is not set for the last request 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 are about to read with the OTRcvURequest function does not constitute the entire request and that you must call the function again to read more of or the rest of the request.

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 request 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 requesters and the OTRcvURequest function returns with the T_PARTIALDATA flag set, it is possible that your next call to the OTRcvURequest function might not read the rest of the request because the next data unit coming in belongs to a different request. One way to handle this situation is to use the next call to the OTRcvURequest function to determine the sequence number of the incoming request (by setting req->udata.len to 0) and then, having determined which request data is coming in, read the data into the appropriate buffer.

The provider sets the T_ACKNOWLEDGED flag if the requester has set this flag when calling the OTSndURequest function. When this flag is set and you call the OTSndUReply function, Open Transport guarantees that your reply is acknowledged by the requester. This flag is set only on the first call to the OTRcvURequest function for any given transaction.

SEE ALSO

The OTSndUReply function.

"AppleTalk Reference".

Table 4-4.