Inside Macintosh: Open Transport /

Chapter 3 - Endpoints / Endpoints Reference

Functions / Functions for Connection-Oriented Transaction-Based Endpoints

OTSndRequest

Sends a request to a connection-oriented transaction-based responder.

C INTERFACE

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

C++ INTERFACE

OSStatus TEndpoint::SndRequest(TRequest* req, OTFlags reqFlags);

PARAMETERS

ref

The endpoint reference of the endpoint making the request.

req

A pointer to a TRequest structure (page 3-66) that contains information about the request, options for this request, and the transaction ID of the request.

reqFlags

A bitmapped long specifying whether you are sending request data using additional calls to this function (T_MORE) and whether you plan to acknowledge replies (T_ACKNOWLEGED). Use the bitAND operator to set both bits.

DESCRIPTION

You use the OTSndRequest function to initiate a transaction. When the responding peer replies to your request, you use the OTRcvReply function to read the reply.

By default, delivery is guaranteed for you, but not for the responder. That is, you will always find out whether your request was received, but the responder only receives acknowledgment that you received the reply if you set the T_ACKNOWLEDGED bit in the reqFlags parameter when you send the request.

If the responder is an Open Transport endpoint, its provider generates a T_REPLYCOMPLETE event when you have read the reply. This happens whether or not the T_ACKNOWLEDGED bit is set; but if it is set, this guarantees that the reply was delivered. If you don't set this flag, the responder's call to the OTSndReply function returns right away, and the responding endpoint receives no additional information as to whether the reply was received and the data
was read.

Setting the T_MORE bit tells the endpoint provider that you are using several calls to the OTSndRequest function to send the request data. Note that even though you are using several calls, the request data, put all together, must still not exceed the value specified for the etsdu field in the endpoint's TEndpointInfo structure.

If the endpoint is in blocking mode and flow-control restrictions prevent the endpoint provider from accepting the OTSndRequest function, Open Transport retries the operation until flow-control restrictions are lifted.

If the endpoint is in nonblocking mode and flow-control restrictions prevent the endpoint provider from accepting the OTSndRequest function, Open Transport returns the kOTFlowErr result. When flow-control restrictions are lifted, the provider issues a T_GODATA event, which you can retrieve using your notifier function or by polling the endpoint using the OTLook function. When you get this event, you can try sending the request again.

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

	Blocking	Nonblocking
Synchronous	The function returns when the provider lifts flow- control restrictions and the request has been sent to the protocol.	The function returns if flow-control restrictions are in effect or the request data has been sent to the protocol.
	The kOTFlowErr result is never returned.	The kOTFlowErr result might be returned.
Asynchronous	The function returns immediately.	The function returns immediately.
	The kOTFlowErr result is never returned.	The kOTFlowErr result might be returned.

VALID STATES

T_DATAXFER, T_INREL

SEE ALSO

You use the OTRcvReply function (page 3-144) to read the reply to your request.

You use the TRequest structure (page 3-66) to specify information about the request, options for this request, and the transaction ID of the request.

The maximum size of a request is defined by the etsdu field of the TEndpointInfo structure (page 3-48).

You use the OTLook function (page 3-85) to retrieve pending asynchronous events.

You use the OTData structure (page 3-52) to describe noncontiguous data.