quanser.communications.stream.receive_uint8s

navigation bar

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

Syntax

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

Description

This function receives data over a client stream. It attempts to receive num_uint8s 8-bit unsigned integers from the communication channel.

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 all the data in the stream buffer is exhausted it will return an empty array to indicate the connection has been closed. 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 no data is available at all then it returns 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 semantics of this function differ from the BSD recv() socket function because it receives num_uint8s in blocking mode rather than the number of 8-bit integers 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 quanser.communications.stream.send operation, the number of send() calls made at the peer may not correspond to the number expected.

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, would_block must also be false to indicate closure. The array may have fewer than num_uint8s elements if the stream is non-blocking or the connection was closed and these were the remaining 8-bit integers.

would_block

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

Examples

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