Legacy Document

Important: The information in this document is obsolete and should not be used for new development.

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

Chapter 22 - Endpoints Reference / Functions

Functions for Connection-Oriented Transactionless Endpoints /

OTRcv
Reads data sent using a connection-oriented transactionless endpoint.

C INTERFACE
OTResult OTRcv(EndpointRef ref, 
                     void* buf, 
                     size_t nbytes, 
                                         OTFlags* flags);
C++ INTERFACE
OTResult TEndpoint::Rcv(void* buf, 
                     size_t nbytes, 
                     OTFlags* flags);
PARAMETERS

ref
The endpoint reference of the endpoint receiving data.
buf
A pointer to a buffer where the incoming data is to be copied. You must allocate this buffer before you call the function.
nbytes
A 32-bit value specifying the size of the buffer in bytes.
flags
A 32-bit bitmapped value specifying, on return, whether the data being sent is expedited (T_EXPEDITED) and whether more data remains to be received (T_MORE).
function result
A positive integer specifying the number of bytes received or a negative integer specifying an error code. See Appendix B, and Discussion.

DISCUSSION
You call the OTRcv function to read data sent by the peer to which you are connected. If the OTRcv function succeeds, it returns a positive integer (OTResult) specifying the number of bytes received. The function places the data read into the buffer referenced by the buf parameter. If the function fails, it returns a negative integer corresponding to a result code that indicates the reason for the failure. You can call this function to receive either normal or expedited data. If the data is expedited, the T_EXPEDITED flag is set in the flags parameter.
If the endpoint does not support the concept of a TSDU, the T_MORE flag is not meaningful and should be ignored. To determine whether the endpoint supports TSDUs, examine the tsdu field of the TEndpointInfo structure. If the endpoint supports TSDUs and the T_MORE bit is set in the flags parameter when the function returns, this means that the buffer you allocated is too small to contain the entire TSDU and that you must call the OTRcv function again. If you have read x bytes with the first call, the next call to the OTRcv function begins to read at the (x + 1) byte. Each call to this function that returns with the T_MORE flag set means that you must call the function again to get more of the TSDU. When you have read the entire TSDU, the OTRcv function returns with the T_MORE flag not set.
If the OTRcv function returns and the T_EXPEDITED bit is set in the flags parameter, this means that you have read expedited data. If the number of bytes in the ETSDU exceeds the number of bytes you specified in the reqCount parameter, both the T_EXPEDITED and the T_MORE bits are set. You must call the OTRcv function until the T_MORE flag is not set to retrieve the rest of the ETSDU.
If you are calling the OTRcv function repeatedly to read normal data and a call to the function returns T_EXPEDITED in the flags parameter, the next call to the OTRcv function that returns without the T_EXPEDITED flag set returns normal data at the place it was interrupted. It is your responsibility to remember where that was and to continue processing normal data.
If the endpoint is in synchronous blocking mode, the endpoint waits for data if none is currently available.If the endpoint is in asynchronous mode or is not blocking, the function returns with the kOTNoDataErr result if no data is available. For more information on notifier functions and event codes, see MyNofierCallback function and "Event Codes". If you have installed a notifier, the endpoint provider calls your notifier and passes T_DATA or T_EXDATA for the code parameter when there is data available. If you have not installed a notifier, you may poll for these events using the OTLook function. Once you receive a T_DATA or T_EXDATA event, you should continue in a loop, calling the OTRcv function until it returns with the kOTNoDataErr result.

SPECIAL CONSIDERATIONS
You should be prepared for a T_DATA event and then a kOTNoDataErr error when you call the OTRcv function. This seems unusual, but it can occur if you were in the process of calling OTRcv in the foreground when a T_DATA event comes in.
Whenever the OTRcv function returns a kOTLookErr error, it is very important that you call the OTLook function. If you are in a flow-control situation on the send side, and a T_GODATA or T_GOEXDATA event occurs that you do not clear in your notifier (by calling OTLook or by actually sending some data), then you will hang waiting. Until the T_GODATA or T_GOEXDATA events are cleared, Open Transport cannot send you another T_DATA event (or any other event other than a T_DISCONNECT event).
The XTI_RCVLOWAT option allows endpoints that support it to negotiate the minimum number of bytes that must have accumulated in the endpoint's internal receive buffer before the endpoint provider generates a T_DATA event. See "Option Management" for information on setting this option.