Inside Macintosh: Open Transport /

Chapter 3 - Endpoints / Endpoints Reference

Functions / Functions for Connectionless Transaction-Based Endpoints

OTSndURequest

Initiates a connectionless transaction by sending a request to the responder.

C INTERFACE

OSStatus OTSndURequest (EndpointRef ref, TUnitRequest* req,
                        int reqFlags);

C++ INTERFACE

OSStatus TEndpoint::SndURequest(TUnitRequest* req, int reqFlags);

PARAMETERS

ref

The endpoint reference of the endpoint making the request.

req

A pointer to a TUnitRequest structure (page 3-58) that specifies the address of the responder, the request data, and the ID of this transaction.

reqFlags

A bitmapped long specifying whether delivery is guaranteed for both the requester and the responder (T_ACKNOWLEDGED) and whether you are sending the request data using additional calls to the OTSndURequest function (T_MORE). Use the bitAND operator to set both values.

DESCRIPTION

You use the OTSndURequest function to initiate a transaction. When the responder replies to your request, you use the OTRcvUReply function to read the reply. By default, the endpoint provider guarantees delivery 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 have set the T_ACKNOWLEDGED flag in the reqFlags parameter when you send the request. Not all protocols honor this flag.

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 flag 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 OTSndUReply 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 flag tells the endpoint provider that you are using several calls to the OTSndURequest function to send the request data. Note that even though you are using several calls, the request data, all put 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 OTSndURequest function, the provider waits to send the request until flow-control restrictions are lifted.

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

The following table shows how the endpoint's mode of execution and blocking status affects the behavior of the OTSndURequest 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_IDLE

SEE ALSO

To determine the maximum size of the request data, you must call the OTGetEndpointInfo function (page 3-82) and examine the etsdu field of the TEndpointInfo structure that it returns.

You use the TUnitRequest structure (page 3-58) to specify the address of the responder, the request data, and the ID of this transaction.

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

To read the reply to an outgoing request, you must use the OTRcvUReply function (page 3-115).

For information on how to use this function with the AppleTalk ATP protocol, see page 14-9 in the ATP chapter.

You can poll for the T_GODATA event by calling the OTLook function (page 3-85).