quanser.communications.stream.receive_uint8_array

navigation bar

Receives an array of 8-bit unsigned integer data as an atomic unit from a stream.

Syntax

[data, would_block] = stream.receive_uint8_array(num_uint8s)

Description

This function receives an array of 8-bit unsigned integers over a client stream. It differs from the receive_uint8s function in that it treats the entire array as an atomic unit. It either receives all of the array or none of it.

If quanser.communications.stream.listen or quanser.communications.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 an empty array only once there is no more data to receive. Otherwise it returns the array of 8-bit integers read before the connection closed. Once there is not enough data in the stream buffer to fill the requested array then it will return an empty array to indicate the connection has been closed. Use receive_uint8s to receive any remaining 8-bit integers if required. If an error occurs, then it issues an error message.

If quanser.communications.stream.listen or quanser.communications.stream.connect was called with the non-blocking flag set to true (1), then this function does not block. If fewer 8-bit integers are available than the size of the entire requested array then it sets would_block equal to true. In this case, the poll function may be used with the 'receive' flag to determine when data becomes available. Otherwise it returns the array of 8-bit integers received.

The BSD socket API has no equivalent to this function.

This operation is not valid on listening streams created using quanser.communications.stream.listen.

Parameters

stream

Stream handle returned by quanser.communications.stream.connect or accept.

num_uint8s

The number of uint8s to receive.

Outputs

data

An array of uint8's containing the 8-bit integers received. For blocking streams, if this array is empty then the connection has been closed gracefully. For non-blocking streams, the array is empty if not enough data was available in the stream buffer to satisfy the request. In this case, would_block is set to true if the connection is still open and false if the connection has been closed. The array is always empty or num_uint8s elements. Unlike the quanser.communications.stream.receive_uint8s function it will never contain between 0 and num_uint8s elements exclusive.

would_block

Whether the function would have blocked. Always false for blocking streams.

Examples

data = stream.receive_uint8_array(1000);    % Receive 1000 8-bit unsigned integers