Inside Macintosh: Open Transport /

Chapter 3 - Endpoints / Endpoints Reference

Functions / Functions for Connectionless Transactionless Endpoints

OTRcvUData

Reads data sent by a client using a connectionless transactionless protocol.

C INTERFACE

OSStatus OTRcvUData (EndpointRef ref, TUnitData* udata, 
                     OTFlags* flag);

C++ INTERFACE

OSStatus TEndpoint::RcvUData(TUnitData* udata, OTFlags* flag);

PARAMETERS

ref

The endpoint reference of the endpoint receiving the data.

udata

A pointer to a TUnitData structure (page 3-55) that, on return, contains information about the data that has been received. See the description of the TUnitData structure for how to set this parameter when doing a no-copy receive.

flags

A pointer to an unsigned long variable whose bit setting, on return, indicates whether you need to retrieve more data. A value of T_MORE specifies that there is more data; a value of 0 specifies that there is no more data.

DESCRIPTION

When the OTRcvUData function returns, it passes a pointer to a TUnitData structure containing information about the data read and a pointer to a flags variable that is set to indicate whether there is more data to be retrieved. If the buffer pointed to by the udata->udata.buf field is not large enough to hold the current data unit, the endpoint provider fills the buffer and sets the flags parameter to T_MORE to indicate that you must call the OTRcvUData function again to receive additional data. Subsequent calls to the OTRcvUData function return 0 for the length of the address and option buffers until you receive the full data unit. The last unit to be received does not have the T_MORE flag set.

If the endpoint is in asynchronous mode or is not blocking and data is not available, the OTRcvUData function fails with the kOTNoDataErr result. The endpoint provider uses the T_DATA event to notify the endpoint when data becomes available. You can use a notifier function or the OTLook function to retrieve the event. Once you get the T_DATA event, you should continue calling the OTRcvUData function until it returns the kOTNoDataErr result.

It is possible that the provider generates an erroneous T_DATA event. This is
the case when the provider calls your notifier, passing T_DATA for the code parameter; but when you execute the OTRcvUData function, it returns with a kOTNoDataErr result. If this happens, you should continue normal processing and assume that the next T_DATA event is genuine.

SPECIAL CONSIDERATIONS

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_IDLE

SEE ALSO

You can use the OTLook function (page 3-85) to retrieve pending asynchronous events for this endpoint.

For a description of the OTOptionManagement function, see the chapter "Option Management" in this book.

For information on how to use this function with the AppleTalk DDP protocol, see page 12-11 in the DDP chapter.

You use the TUnitData structure (page 3-55) to specify the size and location of buffers that contain information about the data that has been received.