stream_receive :: Quanser C Functions

navigation bar

stream_receive

Receives data over a client stream.

Description

This function receives data over a client stream. It attempts to receive buffer_size bytes from the communication channel.

If stream_listen or stream_connect was called with the non-blocking flag set to false (0),then this function blocks until all the data is read. If the connection has been closed gracefully then it returns 0 only once there is no more data to receive. Otherwise it returns the number of bytes read before the connection closed. Once all the data in the stream buffer is exhausted it will return 0 to indicate the connection has been closed. If an error occurs, then it returns a negative error code.

If stream_listen or stream_connect was called with the non-blocking flag set to true (1), then this function does not block. If no data is available at all then it returns -QERR_WOULD_BLOCK. In this case, the stream_poll function may be used with the STREAM_POLL_RECEIVE flag to determine when data becomes available. Otherwise it returns the number of bytes received.

Unlike the stream_receive_byte_array function, this function does not require that the stream receive buffer be at least buffer_size bytes in length. Hence, it allow smaller stream buffers to be used.

This function does not support two threads calling stream_receive at the same time. However, stream_send or stream_flush may be called by another thread at the same time as stream_receive.

The semantics of this function differ from the BSD recv() socket function because it receives buffer_size bytes in blocking mode rather than the number of bytes that were sent in a single send() call at the peer. The semantics differ because this function attempts to "read ahead" by keeping the stream buffer full, thereby minimizing the number of receive operations performed on the internal connection. Also, due to buffering of the stream_send operation, the number of send() calls made at the peer may not correspond to the number expected.

Prototype

t_int
stream_receive(t_stream stream, void * buffer, t_int buffer_size);

Parameters

t_stream stream

A client stream established using stream_connect or stream_accept.

void * buffer

A buffer of at least buffer_size bytes in which the received data will be stored.

t_int buffer_size

The number of bytes available in the buffer.

Return value

The number of bytes received, which may be less than buffer_size bytes for non-blocking streams. If no more data is available and the connection has been closed gracefully then 0 is returned. If an error occurs then a negative error code is returned.

Error codes

This function does not return any error code.

Requirements

Include Files	Libraries
quanser_stream.h	quanser_communications.lib;quanser_runtime.lib;quanser_common.lib