stream_receive_utf8_chars :: Quanser C Functions

navigation bar

stream_receive_utf8_chars

Receives an array of UTF-8 characters over a client stream.

Description

This function receives an array of UTF-8 characters over a client 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 bytes are available then the size of a UTF-8 character then it returns -QERR_WOULD_BLOCK. In this regard, it differs from the stream_receive_utf8_char_array function which returns -QERR_WOULD_BLOCK if the entire array cannot be returned without blocking.

When -QERR_WOULD_BLOCK is returned, the stream_poll function may be used with the STREAM_POLL_RECEIVE flag to determine when data becomes available. Otherwise this functions returns the number of code units returned in the caller's buffer. This number may be smaller than the number requested even if all the requested bytes are available because this function never reads a partial character. UTF-8 characters are variable-sized and up to four code units (bytes) long. Hence, there may be 1-3 code units (bytes) that cannot be stored in the supplied buffer because the next character in the input stream is too large to fit in the remaining bytes.

If stream_listen or stream_connect was called with the non-blocking flag set to false (0), then this function attempts to return the number of code units requested unless the stream is closed by the peer before the full quantity is received.

The return value is the number of code units (bytes) stored in the supplied buffer.

If the buffer is too small for a UTF-8 character (only possible if max_code_units is less than four) then -QERR_BUFFER_TOO_SMALL is returned and nothing is read from the input stream. Hence, a subsequent call with a larger buffer can succeed in reading the UTF-8 character.

If an illegal UTF-8 character is encountered then -QERR_ILLEGAL_UTF8_CHARACTER is returned. If the lead byte was valid then the number of bytes indicated by the lead byte (1-4) are removed from the input stream. If the lead byte was not valid then only the invalid lead byte is removed from the input stream.

If an illegal UTF-16 character is encountered then -QERR_ILLEGAL_UTF16_CHARACTER is returned. If the lead code unit was valid then the number of words indicated by the lead code unit (1-2) are removed from the input stream. If the lead code unit was not valid then only the invalid lead code unit is removed from the input stream.

If an illegal UTF-32 character is encountered then -QERR_ILLEGAL_UTF32_CHARACTER is returned. The invalid character is removed from the input stream.

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

If the connection has been closed gracefully then it returns 0 only if there are fewer bytes left to receive than the size of a character. Otherwise it returns the number of code units read before the connection closed. Once there are fewer bytes left to receive than the size of a character 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_utf8_chars(t_stream stream, t_utf8_char * buffer, t_int max_code_units);

Parameters

t_stream stream

A client stream established using stream_connect or stream_accept.

t_utf8_char * buffer

A pointer to an array of t_utf8_char's in which the received characters will be stored. This buffer should contain at least 4 elements to ensure that a full UTF-8 character is received (UTF-8 characters may be up to 4 code units or bytes in length).

t_int max_code_units

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

Return value

The number of code units written to the caller's buffer. If fewer bytes than the size of a character 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