stream_receive_byte_array :: Quanser C Functions

navigation bar

stream_receive_byte_array

Receives an array of bytes over a client stream.

Description

This function receives an array of bytes over a client stream. It differs from the stream_receive_bytes function in that it treats the entire array as an atomic unit. It either receives all of the array or none of it. It also requires that the stream receive buffer be at least as large as the array of bytes.

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 the entire array 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 1.

If the connection has been closed gracefully then it returns 0 only if there are fewer bytes left to receive than the size of the entire array. Otherwise it returns 1. Once there are fewer bytes left to receive than the size of the entire array 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_byte_array(t_stream stream, t_byte * elements, t_uint num_elements);

Parameters

t_stream stream

A client stream established using stream_connect or stream_accept.

t_byte * elements

A pointer to a t_byte array in which the received data will be stored.

t_uint num_elements

The number of elements to receive, and available in the elements array.

Return value

Returns 1 on success. If not enough 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