console.h File Reference

Console stream interface and utility functions. More...

#include "gate/gate_core_api.h"
#include "gate/streams.h"
#include "gate/inputs.h"

Macros
#define	GATE_CONSOLE_TIMEOUT_NEVER   ((gate_uint32_t)0xffffffff)
#define	gate_console_await_char(con, timeout_ms)
	Waits until a character is ready to be ready, or a timeout occurs.
#define	gate_console_read_char(con, ptr_char)
	Reads a single UTF32 character from the console (STDIN)

Functions
GATE_CORE_API gate_console_t *	gate_console ()
	Returns the global console stream connected to STDIN/OUT/ERR.
GATE_CORE_API gate_stream_t *	gate_console_stream ()
	Returns the global console stream as a generic stream object.
GATE_CORE_API gate_stream_t *	gate_console_error_stream ()
	Returns the global console error output as a generic stream object.
GATE_CORE_API gate_result_t	gate_console_write_err (gate_console_t *con, char const *buffer, gate_size_t bufferlen)
	Writes bytes to the ERR output stream of a console object.
GATE_CORE_API gate_result_t	gate_console_print_err (gate_console_t *con, char const *buffer)
	Writes bytes to the ERR output stream of a console object.
GATE_CORE_API gate_result_t	gate_console_print_err_num (gate_console_t *con, gate_int64_t num)
	Writes an integer as a decimal number to the console ERR stream.
GATE_CORE_API gate_result_t	gate_console_println_err (gate_console_t *con, char const *buffer)
	Writes a NULL-terminated text + platform newline characters to the console ERR stream.
GATE_CORE_API gate_result_t	gate_console_readln_raw (gate_console_t *con, gate_string_t *line, gate_uint32_t timeout_ms)
	Reads raw characters from console into a string until a newline (ENTER) character is entered.
GATE_CORE_API gate_result_t	gate_console_timed_read_char (gate_console_t *con, gate_uint32_t timeout_ms, gate_char32_t *ptr_char)
	Reads a single character type from the console's input stream or cancel on a given timeout.
GATE_CORE_API gate_result_t	gate_console_read_key (gate_console_t *con, gate_uint32_t timeout_ms, gate_input_keycode_t *out_ptr_keycode, gate_char32_t *out_ptr_chr, char *out_buffer, gate_size_t *out_buffer_len)
	Reads a key event from the console's input stream and if possible a mapped character and the native bytes.

Detailed Description

Console stream interface and utility functions.

Macro Definition Documentation

GATE_CONSOLE_TIMEOUT_NEVER

#define GATE_CONSOLE_TIMEOUT_NEVER   ((gate_uint32_t)0xffffffff)

Special timeout value to indicate: no-timeout

gate_console_await_char

#define gate_console_await_char	(		con,
			timeout_ms )

Value:

((gate_console_t*)con)->vtbl->await_char((con), (timeout_ms));

Waits until a character is ready to be ready, or a timeout occurs.

Parameters

[in]	con	pointer to console object
[in]	timeout_ms	timeout in milliseconds, when read attempt shall be canceled

Returns

GATE_RESULT_* result code (OK = char ready, TIMEOUT = no char ready)

gate_console_read_char

#define gate_console_read_char	(		con,
			ptr_char )

Value:

((gate_console_t*)con)->vtbl->read_char((con), (ptr_char));

Reads a single UTF32 character from the console (STDIN)

Parameters

[in]	con	pointer to console object
[out]	ptr_char	pointer to UTF32 character to be filled

Returns

GATE_RESULT_* result code

Function Documentation

gate_console()

GATE_CORE_API gate_console_t * gate_console

(

)

Returns the global console stream connected to STDIN/OUT/ERR.

Returns

pointer to console stream (no retain/release required)

gate_console_stream()

GATE_CORE_API gate_stream_t * gate_console_stream

(

)

Returns the global console stream as a generic stream object.

Returns

pointer to console stream (no retain/release required)

gate_console_error_stream()

GATE_CORE_API gate_stream_t * gate_console_error_stream

(

)

Returns the global console error output as a generic stream object.

Returns

pointer to console error stream (no retain/release required)

gate_console_write_err()

GATE_CORE_API gate_result_t gate_console_write_err	(	gate_console_t *	con,
		char const *	buffer,
		gate_size_t	bufferlen )

Writes bytes to the ERR output stream of a console object.

Parameters

[in]	con	pointer to console object
[in]	buffer	pointer to buffer with bytes to write to the console
[in]	bufferlen	amount of bytes in buffer to be written to console

Returns

GATE_RESULT_* result code

gate_console_print_err()

GATE_CORE_API gate_result_t gate_console_print_err	(	gate_console_t *	con,
		char const *	buffer )

Writes bytes to the ERR output stream of a console object.

Parameters

[in]	con	pointer to console object
[in]	buffer	pointer to NULL-terminated string

Returns

GATE_RESULT_* result code

gate_console_print_err_num()

GATE_CORE_API gate_result_t gate_console_print_err_num	(	gate_console_t *	con,
		gate_int64_t	num )

Writes an integer as a decimal number to the console ERR stream.

Parameters

[in]	con	pointer to console object
[in]	num	number to be printed on console ERR stream

Returns

GATE_RESULT_* result code

gate_console_println_err()

GATE_CORE_API gate_result_t gate_console_println_err	(	gate_console_t *	con,
		char const *	buffer )

Writes a NULL-terminated text + platform newline characters to the console ERR stream.

Parameters

[in]	con	pointer to console object
[in]	buffer	pointer text buffer to be written to console

Returns

GATE_RESULT_* result code

gate_console_readln_raw()

GATE_CORE_API gate_result_t gate_console_readln_raw	(	gate_console_t *	con,
		gate_string_t *	line,
		gate_uint32_t	timeout_ms )

Reads raw characters from console into a string until a newline (ENTER) character is entered.

Parameters

[in]	con	pointer to console object
[out]	line	pointer to string to be initialize with received console characters
[in]	timeout_ms	total input timeout, when function is canceled (or GATE_CONSOLE_TIMEOUT_NEVER)

Returns

GATE_RESULT_* result code

gate_console_timed_read_char()

GATE_CORE_API gate_result_t gate_console_timed_read_char	(	gate_console_t *	con,
		gate_uint32_t	timeout_ms,
		gate_char32_t *	ptr_char )

Reads a single character type from the console's input stream or cancel on a given timeout.

Parameters

[in]	con	pointer to console object
[in]	timeout_ms	amount of milliseconds to wait for a new character
[out]	ptr_char	pointer to UTF32 character to be filled

Returns

GATE_RESULT_* result code, (OK=key read, TIMEOUT=no key available)

gate_console_read_key()

GATE_CORE_API gate_result_t gate_console_read_key	(	gate_console_t *	con,
		gate_uint32_t	timeout_ms,
		gate_input_keycode_t *	out_ptr_keycode,
		gate_char32_t *	out_ptr_chr,
		char *	out_buffer,
		gate_size_t *	out_buffer_len )

Reads a key event from the console's input stream and if possible a mapped character and the native bytes.

Parameters

[in]	con	pointer to console object
[in]	timeout_ms	timeout in milliseconds waiting for a new key to read
[out]	out_ptr_keycode	pointer to output keycode field to be filled
[out]	out_ptr_chr	optional pointer to UTF32 character to be filled
[out]	out_buffer	optional pointer to buffer retrieving a copy of read bytes
[in,out]	out_buffer_len	optional pointer to out_buffer's length, will be updated with true amount of bytes retrieved

Returns

GATE_RESULT_* result code