stream_print_utf8_chars :: Quanser C Functions

navigation bar

stream_print_utf8_chars

Prints a formatted string of UTF-8 characters to the stream buffer.

Description

This function prints a formatted string of UTF-8 characters to the stream buffer. The characters are converted according to the stream's character format prior to writing the character to the stream buffer. If no character format has been set, or the character format is STREAM_FORMAT_AUTO then the character format is set to UTF-8. This function attempts to store the converted characters in the stream buffer. If there is enough room available in the stream buffer then it stores the data in the buffer and returns immediately. The data is not written to the actual communication channel until the stream is flushed using stream_flush or there is no more room available in the stream buffer. If an error occurs, then it returns a negative error code. If the connection is closed it is considered an error condition.

Unlike the stream_print_utf8_char_array function, this function does not require that the stream send buffer be at least as large as the resulting formatted text in length. Hence, it allows smaller stream buffers to be used.

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

Refer to the comments under the heading "Print 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 converted character 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 flush the stream buffer. All the data will be consumed and the total number of code units read from the caller's buffer is returned. Some of the data may remain in the stream buffer and not be sent until the next time stream_flush is called or there is no more room available in the stream buffer. If an error occurs then the error code is returned and the stream should be closed.

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 the number of code units written to the caller's buffer and sent successfully after conversion. If the character could not be sent without blocking, then -QERR_WOULD_BLOCK is returned. If an error occurs 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_print_utf8_chars(t_stream stream, t_int max_units, t_int * fields_printed, const t_utf8_char * format, ...);

t_int
string_print_utf8_chars(t_utf8_char * string, t_int max_units, t_int * fields_printed, const t_utf8_char * format, ...);

t_int
string_print_utf8_charsP(t_utf8_char * string, t_int max_units, t_int * fields_printed, const t_utf8_char * format, pa_list arguments);

t_int
string_print_utf8_charsV(t_utf8_char * string, t_int max_units, t_int * fields_printed, const t_utf8_char * format, va_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 write to the stream.

t_int * fields_printed

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

const t_utf8_char * format

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

...

Subsequent arguments for substituting in the format string.

Return value

The number of code units written to the caller's buffer and sent successfully after conversion. 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