Inside Macintosh: Open Transport /

Chapter 3 - Endpoints / 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);

PPARAMETERS

ref

The endpoint reference of the endpoint reading the request.

req

A pointer to a TRequest structure (page 3-66) that contains information, on return, about the incoming request. See the description of the TRequest structure for how to set this parameter when doing a no-copy receive.

reqFlags

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

DESCRIPTION

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 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 field contains returns no information for these additional calls.

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

If flow-control restrictions prevent the provider from accepting the data when you call the OTRcvRequest function, the function returns the kOTFlowErr result. The provider issues the T_GODATA event when flow-control restrictions are lifted.

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.

VALID STATES

T_DATAXFER, T_OUTREL

SEE ALSO

You use the OTSndReply function (described next) to reply to a request that you have read using the OTRcvRequest function.

You can use the OTLook function to poll for T_REQUEST events (page 3-85).