stream_peek_begin :: Quanser C Functions

navigation bar

stream_peek_begin

Prepares the t_stream_peek_state to begin peeking for data.

Description

This function prepares the t_stream_peek_state to begin peeking for data. "Peeking" involves reading ahead without removing the data from the stream buffer. It is particularly useful for parsing the input from the stream because it allows the next bytes to be tested without preventing the user from receiving those bytes later. It may also be used to read a sequence of data types as a single atomic unit, much like the xxxx_array functions. The "peek state" is used to keep track of how far ahead the lookahead operations have reached so far.

The stream_peek_end function must be called to end the peek operation. Failure to do so may potentially cause deadlock the next time stream_peek_begin is called.

An example of using the peek capabilities to read a sequence of data types as a single atomic unit using non-blocking I/O is provided below. In the example, the code peeks ahead in the input stream for an integer and a double. If at any time the operation would block, then -QERR_WOULD_BLOCK is returned. The stream_peek_end call never advances the stream pointer because the result is less than 1 and the data is not removed from the input stream. Hence, the next time the code is called the same data is read again. The stream_peek_end also returns the same result so that the -QERR_WOULD_BLOCK error is returned.

However, if the stream_peek_int and stream_peek_double succeed then stream_peek_end advances the stream pointer and returns 1. Hence, the data is removed from the input stream and subsequent reads/peeks from the stream will return new data.

Thus, the integer and double are read as one atomic unit from the input stream, because if not all the data is available, then nothing is removed from the input stream. Only if both quantities are read successfully is the data actually removed from the input stream.

Note that the stream_peek_xxxx functions may read data from the underlying communication channel, but the contents of the stream buffer are never overwritten until stream_peek_end is called to indicate that the peeked data may be removed from the input stream.

This function assumes that the stream is valid. It does not block because it does not access the underlying communication channel.

Prototype

t_error
stream_peek_begin(t_stream stream, t_stream_peek_state * state);

Parameters

t_stream stream

A client stream established using stream_connect or stream_accept.

t_stream_peek_state * state

The "peek state" to initialize.

Return value

This function only returns an error if one of the parameters is invalid or the stream is shutdown or closed. It returns zero on success.

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

Examples

t_stream_peek_state state;
t_int int_value;
t_double double_value;

result = stream_peek_begin(stream, &state);
if (result == 0) {
    result = stream_peek_int(stream, &state, &int_value);
    if (result > 0) {
        result = stream_peek_double(stream, &state, &double_value);
    }

    result = stream_peek_end(stream, &state, result);
}