stream_peek_utf8_char_array :: Quanser C Functions

navigation bar

stream_peek_utf8_char_array

Peeks ahead in the input stream to read an array of UTF-8 characters from a client stream.

Description

This function peeks ahead in the input stream to read an array of UTF-8 characters from a client stream. It returns exactly the number of code units requested. Since UTF-8 characters are variable-sized and may be up to four code units (bytes) long, this function may return an error if the characters received do not fit exactly within the number of code units requested, since it only extracts complete UTF-8 characters from the input stream. The return value is 1 if the entire array is peeked. It returns a negative error code if an error occurs. If the peer closes the stream gracefully then zero is returned.

If an illegal UTF-8 character is encountered then -QERR_ILLEGAL_UTF8_CHARACTER is returned.

If an illegal UTF-16 character is encountered then -QERR_ILLEGAL_UTF16_CHARACTER is returned.

If an illegal UTF-32 character is encountered then -QERR_ILLEGAL_UTF32_CHARACTER is returned.

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 element that it peeks before storing them in the given buffer.

The stream_peek_begin function must be called to initialize the peek state. No data peeked will be removed from the input stream until stream_peek_end is called. If stream_peek_end is not called before the next stream_peek_begin then the peeked data is read again.

See the stream_peek_begin function for more information and an example.

The size of the stream receive buffer must be at least max_code_units * sizeof(t_utf8_char) bytes in length.

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 peeked. Blocking may occur because data may be read from the underlying communication channel. However, 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.

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 code units 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 code units left to peek than the size of the entire array. Otherwise it returns 1. Once there are fewer code units left to peek than the size of the entire array then it will return 0 to indicate the connection has been closed. Use stream_peek to peek any remaining bytes if required. If an error occurs, then it returns a negative error code.

This function does not support two threads peeking 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 peeked.

The BSD socket API has no equivalent to this function.

Prototype

t_int
stream_peek_utf8_char_array(t_stream stream, t_stream_peek_state * state, t_utf8_char * buffer, t_int max_code_units);

Parameters

t_stream stream

A client stream established using stream_connect or stream_accept.

t_strean_peek_state * state

The "peek state" initialized using stream_peek_begin.

t_utf8_char * buffer

A pointer to an array of t_utf8_char's in which the received characters will be stored.

t_int max_code_units

The size of the buffer in code units (bytes).

Return value

Returns 1 upon success. If fewer code units than the size of the array 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