stream_receive_units :: Quanser C Functions

navigation bar

stream_receive_units

Receives an array of "units" over a client stream, where the size of a "unit" is determined by the unit_size parameter.

Description

This function receives an array of "units" over a client stream, where the size of a "unit" is determined by the unit_size parameter. If the stream has been configured to swap bytes using stream_set_swap_bytes or stream_set_byte_order then this function will swap the order of the bytes within each unit that it receives before storing them in the given buffer.

Unlike the stream_receive_unit_array function, this function does not require that the stream receive buffer be at least num_units * unit_size bytes in length. Hence, it allows smaller stream buffers to be used.

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 stream_listen or stream_connect was called with the non-blocking flag set to true (1), then this function does not block. If fewer bytes are available then the size of a unit 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 units received.

If the connection has been closed gracefully then it returns 0 only if there are fewer bytes left to receive than the size of a unit. Otherwise it returns the number of units read before the connection closed. Once there are fewer bytes left to receive than the size of a unit then it will return 0 to indicate the connection has been closed. Use stream_receive to receive any remaining bytes if required. If an error occurs, then it returns a negative error code.

This function does not support two threads receiving data at the same time. However, data may be sent or the stream flushed by another thread at the same time as data is being received.

The BSD socket API has no equivalent to this function.

Prototype

t_int
stream_receive_units(t_stream stream, void * units, t_int unit_size, t_int num_units);

Parameters

t_stream stream

A client stream established using stream_connect or stream_accept.

void * units

A pointer to an array of units in which the received data will be stored. It must be at least num_units in length.

t_int unit_size

The size of a unit in bytes.

t_int num_units

The number of units to receive.

Return value

The number of units received, which may be less than the requested number for non-blocking streams. If fewer bytes than size of a unit are 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