stream_scan_utf8_char_array :: Quanser C Functions

navigation bar

stream_scan_utf8_char_array

Reads a formatted string of UTF-8 characters from the stream as an atomic unit.

Description

This function reads a formatted string of UTF-8 characters from the stream as an atomic unit. The characters are converted according to the stream's character format prior to parsing the text according to the format string. If no character format has been set, or the character format is STREAM_FORMAT_AUTO then the character format is set to UTF-8. Parsed values are stored in the arguments, which must be pointers to the appropriate datatypes. If an error occurs, then it returns a negative error code.

If the connection is closed before any characters have been read from the stream, then this function returns 0. Otherwise it returns the number of code units read in the process of scanning the input stream.

Unlike the stream_scan_utf8_chars function, this function requires that the stream receive buffer be at least as large as the entire formatted text in length. However, it has the benefit that the entire text may be rescanned if a formatting mismatch occurs or the stream would block.

Note that this function only reads complete characters from the stream. It will not read some but not all of the code units comprising a multi-unit character.

Refer to the comments under the heading "Scan Functions' Format Specification" for details on the format string.

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 the characters read if the stream's character format is UTF-16 or UTF-32.

If stream_listen or stream_connect was called with the non-blocking flag set to false (0), then this function may block attempting to read from the stream. In particular, note that it may have to "read ahead" in order to parse the input stream. For example, if the format string is "%d" and the input stream is "2", this function will have to read another character after the '2' to see if it is another digit in the number or a delimiter.

If the input does not match the format string then -QERR_MISMATCHED_CHARACTER is returned. In this case, the stream is not advanced at all. This behaviour differs from the stream_scan_utf8_chars function, which advances the stream to the end of the last character or field successfully scanned. The stream may be rescanned. Scanning will begin at the same place in the stream as the previous call, so the entire formatted text may be rescanned, even if some fields were matched in the previous call.

If the input matches the entire format string then the stream is advanced. The next call will read subsequent characters from the stream.

If stream_listen or stream_connect was called with the non-blocking flag set to true (1), then this function does not block. It returns -QERR_WOULD_BLOCK if reading from the stream would block. In this case, the stream is not advanced at all. This behaviour differs from the stream_scan_utf8_chars function, which does advances the stream to the end of the last character or field successfully scanned. The stream may be rescanned. Scanning will begin at the same place in the stream as the previous call, so the entire formatted text may be rescanned, even if some fields were matched in the previous call.

If an error occurs reading from the stream then the error code is returned and the stream should be closed.

This function does not support two threads sending or flushing 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_scan_utf8_char_array(t_stream stream, t_int max_units, t_int * fields_scanned, const t_utf8_char * format, ...);

Parameters

t_stream stream

A client stream established using stream_connect or stream_accept.

t_int max_units

The maximum number of code units (bytes) to read from the stream.

t_int * fields_scanned

A pointer to a variable of type t_int in which the number of fields successfully scanned is stored.

const t_utf8_char * format

A UTF-8 string containing the format specification, like the format string in scanf.

...

Subsequent arguments to receive the values parsed from the input stream.

Return value

The number of code units read from the input stream. If the input stream does not match the format specification, then -QERR_MISMATCHED_CHARACTER is returned. If an error occurs reading from the stream 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