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 /

OTSndRequest

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

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 that contains information about the request, options for this request, and the transaction ID of the request. You must allocate buffers for this information and specify their size.

The req->data.buf field is apointer to a buffer that contains the request. Set the req->data.len field to the size of the request data. The size of the request cannot exceed the value specified for the etsdu field of the TEndpointInfo structure for the endpoint.

The req->opt.buf field is a pointer to a buffer that contains option values you want to negotiate for this request. Set the req->opt.len field to the size of the option data. Set the opt.len field to 0 if there are no options.

The req->sequence field specifies a unique non-zero number of your choice that identifies this request.

reqFlags

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

function result

An error code. See Appendix B, and Discussion.

DISCUSSION

You use the OTSndRequest function to initiate a transaction for a connection-oriented transaction-based endpoint. Call the OTRcvReply function to read the reply to your request.

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 synchronous 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 asynchronous or 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 might be returned.	The kOTFlowErr result might be returned.

SEE ALSO

"AppleTalk Reference".

Table 4-4.