Legacy Document

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

Chapter 22 - 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,
                                         OTFlags reqFl

C++ INTERFACE

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

PARAMETERS

ref

The endpoint reference of the endpoint making the request.

req

A pointer to a TUnitRequest structure that specifies the address of the responder, the request data, and the ID of this transaction.

The req->addr field specifies the location and size of a buffer containing the address of the responder. You must allocate a buffer for the address and specify the address. You must set the req->addr.buf field to point to this buffer and set the req->addr.len field to the length of the address.

The req->opt field specifies the location and size of a buffer containing the options you want to negotiate. You must allocate a buffer that contains the option information and set the req->opt.buf field to point to it. You must set the req->opt.len field to the length of the option data or to 0 if you don't want to specify any options.

The req->udata field specifies the location and size of a buffer containing the request data. You must allocate a buffer for the request data, initialize the req->opudata.buf field to point to it, and set the req->opudata.len field to the size of the request. The request size must not exceed the value for the etsdu field of the TEndpointInfo structure for the endpoint.

You set the req->sequence field to a unique, non -zero value when you send the request. You only need to do this if the endpoint issues multiple requests.

reqFlags

A bitmapped 32-bit value 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 bitwise OR operator to set both values.

function result

An error code. See Discussion.

DISCUSSION

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. If the endpoint is issuing multiple requests, you should set the sequence field of the req parameter to a unique non-zero number so that each request is distinguished from all other outstanding requests issued by the endpoint.

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.

The responder's 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 synchronous 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 asynchronous or 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 by 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 accepted by the provider.
	The kOTFlowErr result is never returned.	The kOTFlowErr result might be returned.
Asynchronous	The function returns immediately	The function returns immediately.
	The kOTFlowErr result might be returned.	The kOTFlowErr result might be returned.

SEE ALSO

Table 4-4.

"AppleTalk Reference"