Inside Macintosh: Open Transport /

Chapter 3 - Endpoints / Endpoints Reference

Functions / Functions for Connection-Oriented Transactionless Endpoints

OTRcv

Reads data sent using a connection-oriented transactionless protocol.

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 memory location where the incoming data is to be copied. You must allocate this buffer before you call the function. If you are doing a no-copy receive, this field is a pointer to an OTBuffer pointer.

nbytes

A long specifying the size of the buffer in bytes. If you are doing a no-copy receive, you must set this field to the kNetbufDataIsOTBufferStar constant.

flags

A long bitmapped variable specifying, on return, whether the data being sent is expedited (T_EXPEDITED) and whether more data remains to be received (T_MORE).

DESCRIPTION

You call the OTRcv function to read data sent by the peer to which you are connected. If the OTRcv function succeeds, it returns an integer (OTStatus) 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 T_MORE is set in the flags parameter when the function returns, this means that the buffer you allocated is too small to contain the data to be read 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. Of course, if you need it, you must copy the data in the buffer to another location before calling the function again. Each call to this function that returns with the T_MORE flag set means that you must call the function again to get more data. When you have read all the data, the OTRcv function returns with the T_MORE flag not set. 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. A value of T_INVALID means that the endpoint does not support it.

Some protocols allow you to send zero-length data to signal the end of a logical unit. In this case, if you request more than 0 bytes when calling the OTRcv function, the function returns 0 bytes only to signal the end of a TSDU.

If the OTRcv function returns and the T_EXPEDITED bit is set in the flags parameter, this means that you are about to read expedited data. If the number of bytes of expedited data 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 expedited data.

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. You can determine how much normal data you read by maintaining a running total of the number of bytes returned in the OTStatus result.

If the endpoint is in asynchronous mode or is not blocking, the function returns with the kOTNoDataErr result if no data is available. 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.

If the endpoint is in synchronous mode and is blocking, the endpoint waits for data if none is currently available. You should avoid calling the OTRcv function this way because it might cause processing to hang if no data is available. If you are doing other operations in synchronous mode, you should put the endpoint in nonblocking mode before calling the OTRcv function.

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 are 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 are cleared, Open Transport cannot send you another T_DATA event (or any other event other than a T_DISCONNECT, for that matter).

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. 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_OUTREL

SEE ALSO

You use the OTLook function (page 3-85) to poll for the T_DATA or T_EXDATA events.

You use the OTIsNonBlocking function, described in the reference section of the chapter "Providers" in this book, to determine the current operational mode of the endpoint. It is recommended that the endpoint be in nonblocking mode before you call the OTRcv function.

For information on how to use this function with a TCP/IP protocol, see page 8-19 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.

You use the OTOptionManagement function, described in the chapter "Option Management" in this book, to negotiate the XTI_RCVLOWAT option.