applications.h File Reference

Functions to initialize, configure and manage application entrypoints. More...

#include "gate/gate_core_api.h"
#include "gate/gatetypes.h"
#include "gate/strings.h"
#include "gate/streams.h"

Data Structures
struct	gate_app_option_class
	Defines command line options. More...
struct	gate_app_class
	app class holding callbacks for different application execution states More...
struct	gate_appservice_class
	Service class that holds callbacks for different system service execution states. More...

Macros
#define	GATE_APP_OPTION_TYPE_SWITCH   0
#define	GATE_APP_OPTION_TYPE_BOOL   1
#define	GATE_APP_OPTION_TYPE_I32   2
#define	GATE_APP_OPTION_TYPE_I64   3
#define	GATE_APP_OPTION_TYPE_REAL   4
#define	GATE_APP_OPTION_TYPE_STRING   5
#define	GATE_APP_OPTION_TYPE_ARRAY   6
#define	GATE_APP_OPTION_INIT_STATIC(key, type, ptr_value, alias, name_value, description)
	Macro to initialize a static option definition with string tokens.
#define	GATE_APP_SIGNAL_TERMINATE   1
#define	GATE_APP_SIGNAL_CANCEL   2
#define	GATE_APP_SIGNAL_SHUTDOWN   3

Typedefs
typedef struct gate_app_option_class	gate_app_option_t
	Defines command line options.
typedef struct gate_app_class	gate_app_t
	app class holding callbacks for different application execution states
typedef struct gate_appservice_class	gate_appservice_t
	Service class that holds callbacks for different system service execution states.

Functions
GATE_CORE_API gate_size_t	gate_app_parse_args (gate_string_t const *argline, gate_string_t *dest_args, gate_size_t max_dest_args)
	Parses a full line of arguments into an array of argument tokens.
GATE_CORE_API gate_size_t	gate_app_parse_args_buffer (gate_string_t const *argline, char *buffer, size_t buffer_len, char const **dest_args, gate_size_t max_dest_args)
	Parses a full line of arguments into an array of argument tokens.
GATE_CORE_API gate_size_t	gate_app_options_parse (gate_string_t const *input_args, gate_size_t input_arg_count, gate_app_option_t *output_options, gate_size_t output_option_count)
	Parses an array of string arguments and fills option_value targets as defined by their option types.
GATE_CORE_API gate_size_t	gate_app_options_parse_strs (char const *const *input_args, gate_size_t input_arg_count, gate_app_option_t *output_options, gate_size_t output_option_count)
	Parses an array of c-string arguments and fills option_value targets as defined by their option types.
GATE_CORE_API gate_result_t	gate_app_options_print (gate_app_option_t const *options, gate_size_t options_count, gate_stream_t *out_stream)
	Prints a list of all defined options.
GATE_CORE_API void	gate_app_option_init (gate_app_option_t *opt, gate_string_t const *key, gate_enumint_t type, void *ptr_value, gate_string_t const *alias, gate_string_t const *name_value, gate_string_t const *description)
	Initializes an option definition with the given arguments.
GATE_CORE_API void	gate_app_option_copy (gate_app_option_t *opt_dest, gate_app_option_t const *opt_src)
	Initializes an option definition by copying values of another option definition.
GATE_CORE_API void	gate_app_option_release (gate_app_option_t *opt)
	Releases all acquired resources of an option definition.
GATE_CORE_API void	gate_app_init (gate_app_t *app, gate_result_t(*init)(gate_app_t *app, char const *program, char const *const *arguments, gate_size_t argcount, gate_uintptr_t apphandle), gate_result_t(*run)(gate_app_t *app), gate_result_t(*on_signal)(gate_app_t *app, int appsignal))
	Initializes an app object with state callback functions.
GATE_CORE_API int	gate_app_run (gate_app_t *app, char const *program, char const *const *arguments, gate_size_t argcount, gate_uintptr_t apphandle)
	perform default application execution on an initalized app object
GATE_CORE_API void	gate_appservice_init (gate_appservice_t *service, gate_result_t(*init_cb)(gate_appservice_t *, char const *, char const *const *, gate_size_t, gate_uintptr_t), gate_result_t(*run_cb)(gate_appservice_t *), gate_result_t(*on_signal_cb)(gate_appservice_t *, int), gate_size_t(*get_servicename_cb)(gate_appservice_t *, char *, gate_size_t), gate_result_t(*on_start_cb)(gate_appservice_t *), gate_result_t(*on_stop_cb)(gate_appservice_t *), gate_result_t(*on_pause_cb)(gate_appservice_t *), gate_result_t(*on_continue_cb)(gate_appservice_t *), gate_result_t(*on_error_cb)(gate_appservice_t *, gate_result_t, gate_int32_t, char const *))
	Initializes an app service object with state callback functions.
GATE_CORE_API int	gate_appservice_run (gate_appservice_t *appservice, char const *program, char const *const *arguments, gate_size_t argcount, gate_uintptr_t apphandle)
	perform default service execution on an initalized appservice object

Detailed Description

Functions to initialize, configure and manage application entrypoints.

Macro Definition Documentation

GATE_APP_OPTION_TYPE_SWITCH

#define GATE_APP_OPTION_TYPE_SWITCH   0

Option is a boolean switch, TRUE when present otherwise FALSE

GATE_APP_OPTION_TYPE_BOOL

#define GATE_APP_OPTION_TYPE_BOOL   1

Option is a boolean value => (gate_bool_t*)

GATE_APP_OPTION_TYPE_I32

#define GATE_APP_OPTION_TYPE_I32   2

Option is a 32 bit integer => (gate_int32_t*)

GATE_APP_OPTION_TYPE_I64

#define GATE_APP_OPTION_TYPE_I64   3

Option is a 64 bit integer => (gate_int64_t*)

GATE_APP_OPTION_TYPE_REAL

#define GATE_APP_OPTION_TYPE_REAL   4

Option is a floating point value => (gate_real64_t*)

GATE_APP_OPTION_TYPE_STRING

#define GATE_APP_OPTION_TYPE_STRING   5

Option is a string => (gate_string_t*)

GATE_APP_OPTION_TYPE_ARRAY

#define GATE_APP_OPTION_TYPE_ARRAY   6

Option is an array of strings => (gate_arraylist_t[gate_string_t])

GATE_APP_OPTION_INIT_STATIC

#define GATE_APP_OPTION_INIT_STATIC	(		key,
			type,
			ptr_value,
			alias,
			name_value,
			description )

Value:

{ \
GATE_STRING_INIT_STATIC(key),                                                           \
type,                                                                                   \
ptr_value,                                                                              \
GATE_STRING_INIT_STATIC(alias),                                                         \
GATE_STRING_INIT_STATIC(name_value),                                                    \
GATE_STRING_INIT_STATIC(description)}

Macro to initialize a static option definition with string tokens.

Parameters

[in]	key	C string containig option key.
[in]	type	target value type (see GATE_APP_OPTION_TYPE_*).
[in]	ptr_value	pointer to target variable that receives parsed argument
[in]	alias	pointer C string containing alternative option key
[in]	name_value	C string containing a name of the option value
[in]	description	C string containing description of option definition

Returns

C-struct initialization for gate_app_option_t variable

GATE_APP_SIGNAL_TERMINATE

#define GATE_APP_SIGNAL_TERMINATE   1

received process termination signal

GATE_APP_SIGNAL_CANCEL

#define GATE_APP_SIGNAL_CANCEL   2

received process cancelation signal

GATE_APP_SIGNAL_SHUTDOWN

#define GATE_APP_SIGNAL_SHUTDOWN   3

received system shutdown signal

Function Documentation

gate_app_parse_args()

GATE_CORE_API gate_size_t gate_app_parse_args	(	gate_string_t const *	argline,
		gate_string_t *	dest_args,
		gate_size_t	max_dest_args )

Parses a full line of arguments into an array of argument tokens.

Parameters

[in]	argline	command line of multiple arguments to be parsed
[in,out]	dest_args	output array of strings to be filled with parsed arguments
[in]	max_dest_args	amount of dest_args items that can be filled

Returns

amount of dest_args that where filled

gate_app_parse_args_buffer()

GATE_CORE_API gate_size_t gate_app_parse_args_buffer	(	gate_string_t const *	argline,
		char *	buffer,
		size_t	buffer_len,
		char const **	dest_args,
		gate_size_t	max_dest_args )

Parses a full line of arguments into an array of argument tokens.

Parameters

[in]	argline	command line of multiple arguments to be parsed
[in,out]	buffer	output text buffer retrieving a list of '\0' seperated arguments
[in]	buffer_len	maximum length of buffer in bytes
[in,out]	dest_args	output argument pointer-array, filled with
[in]	max_dest_args	amount of dest_args items that can be filled

Returns

amount of dest_args that where filled with pointers into buffer with arguments

gate_app_options_parse()

GATE_CORE_API gate_size_t gate_app_options_parse	(	gate_string_t const *	input_args,
		gate_size_t	input_arg_count,
		gate_app_option_t *	output_options,
		gate_size_t	output_option_count )

Parses an array of string arguments and fills option_value targets as defined by their option types.

Parameters

[in]	input_args	pointer to first argument string in array
[in]	input_arg_count	amount of argument strings to be parsed
[in,out]	output_options	pointer to first option definition in array
[in]	output_option_count	amount of option definitions to be matched

Returns

amount of arguments that where parsed into options

gate_app_options_parse_strs()

GATE_CORE_API gate_size_t gate_app_options_parse_strs	(	char const *const *	input_args,
		gate_size_t	input_arg_count,
		gate_app_option_t *	output_options,
		gate_size_t	output_option_count )

Parses an array of c-string arguments and fills option_value targets as defined by their option types.

Parameters

[in]	input_args	pointer to first argument c-string in array
[in]	input_arg_count	amount of argument strings to be parsed
[in,out]	output_options	pointer to first option definition in array
[in]	output_option_count	amount of option definitions to be matched

Returns

amount of arguments that where parsed into options

gate_app_options_print()

GATE_CORE_API gate_result_t gate_app_options_print	(	gate_app_option_t const *	options,
		gate_size_t	options_count,
		gate_stream_t *	out_stream )

Prints a list of all defined options.

Parameters

[in]	options	pointer to first option definition item
[in]	options_count	amount of option definitions to be printed
[in]	out_stream	pointer to output stream where description is printed to

Returns

GATE_RESULT_* values indicating success of failure

gate_app_option_init()

GATE_CORE_API void gate_app_option_init	(	gate_app_option_t *	opt,
		gate_string_t const *	key,
		gate_enumint_t	type,
		void *	ptr_value,
		gate_string_t const *	alias,
		gate_string_t const *	name_value,
		gate_string_t const *	description )

Initializes an option definition with the given arguments.

Parameters

[out]	opt	pointer to option definition to be initialized
[in]	key	option key identifier
[in]	type	data or behavior type of option (see GATE_APP_OPTION_TYPE_*)
[in]	ptr_value	pointer to target variable to be filled with parsed option
[in]	alias	alternative value for "key" to be matched
[in]	name_value	name of option value for automatic help generation
[in]	description	description of option for automatic help generation

gate_app_option_copy()

GATE_CORE_API void gate_app_option_copy	(	gate_app_option_t *	opt_dest,
		gate_app_option_t const *	opt_src )

Initializes an option definition by copying values of another option definition.

Parameters

[out]	opt_dest	pointer to option definition to be initialized
[in]	opt_src	option key identifier

gate_app_option_release()

GATE_CORE_API void gate_app_option_release

(

gate_app_option_t *

opt

)

Releases all acquired resources of an option definition.

Parameters

[in,out]

opt

pointer to option definition to be released

gate_app_init()

GATE_CORE_API void gate_app_init	(	gate_app_t *	app,
		gate_result_t(*	init )(gate_app_t *app, char const *program, char const *const *arguments, gate_size_t argcount, gate_uintptr_t apphandle),
		gate_result_t(*	run )(gate_app_t *app),
		gate_result_t(*	on_signal )(gate_app_t *app, int appsignal) )

Initializes an app object with state callback functions.

Parameters

[in,out]	app	pointer to app object to be initialized
[in]	init	callback to be invoked on startup to initialize global resources
[in]	run	callback to execute main functionality of app
[in]	on_signal	callback to receive external status signal (e.g. for termination)

gate_app_run()

GATE_CORE_API int gate_app_run	(	gate_app_t *	app,
		char const *	program,
		char const *const *	arguments,
		gate_size_t	argcount,
		gate_uintptr_t	apphandle )

perform default application execution on an initalized app object

Parameters

[in]	app	pointer to app object
[in]	program	C string containing programm file path
[in]	arguments	array of C strings containing app arguments
[in]	argcount	amount of items in arguments array
[in]	apphandle	native application handle

Returns

application exit code to be returned on process termination

gate_appservice_init()

GATE_CORE_API void gate_appservice_init	(	gate_appservice_t *	service,
		gate_result_t(*	init_cb )(gate_appservice_t *, char const *, char const *const *, gate_size_t, gate_uintptr_t),
		gate_result_t(*	run_cb )(gate_appservice_t *),
		gate_result_t(*	on_signal_cb )(gate_appservice_t *, int),
		gate_size_t(*	get_servicename_cb )(gate_appservice_t *, char *, gate_size_t),
		gate_result_t(*	on_start_cb )(gate_appservice_t *),
		gate_result_t(*	on_stop_cb )(gate_appservice_t *),
		gate_result_t(*	on_pause_cb )(gate_appservice_t *),
		gate_result_t(*	on_continue_cb )(gate_appservice_t *),
		gate_result_t(*	on_error_cb )(gate_appservice_t *, gate_result_t, gate_int32_t, char const *) )

Initializes an app service object with state callback functions.

Parameters

[in,out]	service	pointer to app object to be initialized
[in]	init_cb	callback to be invoked on startup to initialize global resources
[in]	run_cb	callback to execute main functionality of the service
[in]	on_signal_cb	callback to receive external status signals
[in]	get_servicename_cb	callback to retrieve service name for system registration
[in]	on_start_cb	callback to start service operations
[in]	on_stop_cb	callback to stop service operations
[in]	on_pause_cb	callback to interrupt and pause service operations
[in]	on_continue_cb	callback to continue service operations after interruption
[in]	on_error_cb	callback to notify about detected errors

gate_appservice_run()

GATE_CORE_API int gate_appservice_run	(	gate_appservice_t *	appservice,
		char const *	program,
		char const *const *	arguments,
		gate_size_t	argcount,
		gate_uintptr_t	apphandle )

perform default service execution on an initalized appservice object

Parameters

[in]	appservice	pointer to app object
[in]	program	C string containing programm file path
[in]	arguments	array of C strings containing app arguments
[in]	argcount	amount of items in arguments array
[in]	apphandle	native application handle

Returns

exit code to be returned on process termination