Inside Macintosh: Open Transport /

Chapter 3 - Endpoints / Endpoints Reference

Functions / Functions for Connection-Oriented Transactionless Endpoints

OTSnd

Sends data to a remote peer.

C INTERFACE

OTResult OTSnd (EndpointRef ref, void* buf, size_t nbytes, 
                OTFlags flags);

C++ INTERFACE

OTResult TEndpoint::Snd(void* buf, size_t nbytes, OTFlags flags);

PARAMETERS

ref

The endpoint reference of the endpoint sending data.

buf

A pointer to the data being sent. If you are sending data that is not stored contiguously, this is a pointer to an OTData structure that describes the first data fragment.

nbytes

A long specifying the number of bytes being sent. If you are sending data that is not stored contiguously, you must set this field to the kNetbufDataIsOTData constant.

flags

A long bitmapped variable specifying whether the data to be sent is expedited (T_EXPEDITED) and whether more data remains to be sent (T_MORE). To set both fields, use the bitAND operator.

DESCRIPTION

You use the OTSnd function to send data to a remote peer. Before you use this function, you must establish a connection with the peer.

If the OTSnd function succeeds, it returns an integer (OSStatus) specifying the number of bytes that were actually sent. If it fails, it returns a negative integer corresponding to a result code that indicates the reason for the failure.

You specify the data to be sent by passing a pointer to the data (buf) and by specifying the size of the data (nbytes). The maximum size of the data you can send is specified by the tsdu field of the TEndpointInfo structure for the endpoint.

Some protocols use expedited data for control or attention messages. To determine whether the endpoint supports this service, examine the etsdu field of the TEndpointInfo structure. A positive integer for the etsdu field indicates the maximum size in bytes of expedited data that you can send. To send expedited data, you must set the T_EXPEDITED bit of the flags parameter.

If you want to break up the data sent into smaller logical units, you can set the T_MORE bit of the flags parameter to indicate that you are using additional calls to the OTSnd function to send more data that belongs to the same logical unit.
To indicate that the last data unit is being sent, you must specify 0 for nbytes and turn off the T_MORE flag. This is the only circumstance under which it is permitted to send a zero-length data unit. If the endpoint does not support
the sending of zero-length data, the OTSnd function fails with the
kOTBadDataErr result.

If the endpoint is in blocking mode, the OTSnd function returns after it actually sends the data. If flow-control restrictions prevent its sending the data, it retries the operation until it is able to send it. If the endpoint is in nonblocking mode, the OTSnd function returns with the kOTFlowErr result if flow-control restrictions prevent the data from being sent. When the endpoint provider is able to send the data, it returns a T_GODATA event to let you know that it is possible to
send data.

If the endpoint is in non-blocking or asynchronous mode, it is possible that only part of the data is actually accepted by the transport provider. In this case, the OTSnd function returns a value that is less than the value of the nbytes parameter, or the error kOTFlowErr if no bytes at all were sent. After this error occurs, a T_GODATA event will be issued when the flow control restrictions are lifted. This error is not returned if the endpoint is in blocking mode.

If an asynchronous event, such as a disconnect, occurs and interrupts the OTSnd function, OTSnd returns with the kOTLookErr result.

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

	Blocking	Nonblocking
Synchronous	The function returns when the provider lifts flow-control restrictions.	The function returns immediately.
	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.

SPECIAL CONSIDERATIONS

The XTI_SNDLOWAT option allows endpoints that support it to negotiate the minimum number of bytes that must have accumulated in the endpoint's internal send buffer before they are sent. If the endpoint you are using supports this option, you can negotiate a value using the OTOptionManagement function. Because you use the OTOptionManagement function to set this option, it affects all subsequent sends.

VALID STATES

T_DATAXFER, T_INREL

SEE ALSO

For information about transferring data, see "Using Connection-Oriented Transactionless Service," beginning on page 3-36.

You can examine the TEndpointInfo structure (page 3-48) to find out what kind of data you can send and its maximum size.

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

For information on how to use this function with a TCP/IP protocol, see page 8-18 in the TCP/IP chapter.

For information on how to use this function with AppleTalk protocols, see page 13-11 in the ADSP chapter and page 15-10 in the PAP chapter.

For additional information about the OTOptionManagement function, see the chapter "Option Management" in this book.