stream_scan_utf8_charsV :: Quanser C Functions

navigation bar

stream_scan_utf8_charsV

Reads a formatted string of UTF-8 characters from the stream.

Description

This function reads a formatted string of UTF-8 characters from the stream. 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_char_arrayV function, this function does not require that the stream receive buffer be at least as large as the formatted text in length. Hence, it allows smaller stream buffers to be used.

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 advanced to the end of the last character or field successfully scanned. This behaviour differs from the stream_scan_utf8_char_arrayV function, which does not advance the stream unless the entire format string is matched by the input. The stream may be rescanned. However, scanning will begin at the first character after the last character or field successfuly scanned previously.

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 advanced to the end of the last character or field successfully scanned without blocking. This behaviour differs from the stream_scan_utf8_char_arrayV function, which does not advance the stream unless the entire format string is matched by the input without blocking. The stream may be rescanned. However, scanning will begin at the first character after the last character or field successfuly scanned previously.

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_charsV(t_stream stream, t_int max_units, t_int * fields_scanned, const t_utf8_char * format, va_list arguments);

t_int
stream_scan_utf8_charsP(t_stream stream, t_int max_units, t_int * fields_scanned, const t_utf8_char * format, pa_list arguments);

t_int
string_scan_utf8_charsV(const t_utf8_char * string, t_int max_units, t_int * fields, const t_utf8_char * format, va_list arguments);

t_int
string_scan_utf8_charsP(const t_utf8_char * string, t_int max_units, t_int * fields, const t_utf8_char * format, pa_list arguments);

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.

va_list arguments

A va_list of 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