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 /

OTRcvRequest

You use the OTRcvRequest function to read a request from a connection-oriented transaction-based requester.

C INTERFACE

OSStatus OTRcvRequest(EndpointRef ref, 
                     TRequest* req,
                                         OTFlags* reqFlags);

C++ INTERFACE

OSStatus TEndpoint::RcvRequest(TRequest* req,
                     OTFlags* flags);

PARAMETERS

ref

The endpoint reference of the endpoint reading the request.

req

A pointer to a TRequest structure that contains information, on return, about the incoming request. You must allocate buffers in which this information can be stored and specify the maximum size of each buffer.

The req->data.buf field is a pointer to a buffer in which the incoming request is stored. Set the req->data.maxlen field to the maximum size of the request.

The req->opt.buf field is a pointer to a buffer in which the options specified by the requester are stored. Set the req->opt.maxlen field to the maximum size of option data.

The value for the req->sequence field is generated by the endpoint provider. You need to save this value and use it for the sequence field when sending a reply.

reqFlags

A bitmapped 32-bit value specifying, on return, whether there is more request data coming (T_MORE) and whether the provider is going to acknowledge replies (T_ACKNOWLEDGED).

function result

An error code. See Appendix B, and Discussion.

DISCUSSION

You use the OTRcvRequest function to read an incoming request. After reading the request, you can use the OTSndReply function to reply to that request or the OTCancelRequest function to reject the request.

When the OTRcvRequest function returns, the req->data.buf field points to the request data and the req->sequence field specifies a transaction ID for this transaction. You must use this same sequence value when calling the OTSndReply function to reply to this request or the OTCancelRequest function to reject it.

If the endpoint is in synchronous mode and is blocking, the OTRcvRequest function returns only when a request arrives. The OTRcvRequest function returns either the next unread request or the kOTNoDataErr result if there are no pending requests.

When a request arrives, the provider generates a T_REQUEST event. You can poll for this event using the OTLook function or call the function for as long as the kOTNoDataErr result is returned. If you have a notifier installed for this endpoint, the event is sent to the notifier. For more information on notifier functions and event codes, see MyNotifierCallback function and "Event Codes".

If you have allocated a buffer that is too small to hold the request data, the provider sets the T_MORE bit in the reqFlags field to indicate that there is more request data to be read. You must call the OTRcvRequest function until the T_MORE flag is cleared in order to retrieve the rest of the request data. The req->opt.buf field contains no information for these additional calls.

The flags parameter can also have the T_PARTIALDATA bit set. In this case, the request data being received is only partial; there is more data coming, but it has not arrived. The difference between T_MORE and T_PARTIALDATA is that the first indicates that there is more data and the next call to OTRcvRequest will read that data, while the second does not gurantee that the next read will get the data. The T_PARTIALDATA bit is only set on the first call to the function. All subsequent calls to OTRcvRequest are guaranteed to continue reading the partial data in question until the function returns with the T_MORE flag clear.

SEE ALSO

"AppleTalk Reference".

Table 4-4.