The AXEventHandler is the main entry point into the event system. The functions in this module are thread safe. More...

Typedefs
typedef struct _AXEventHandler	AXEventHandler
	The `AXEventHandler` is an opaque data type used as an entry point into the event system.

typedef void(*	AXSubscriptionCallback) (guint subscription, AXEvent *event, gpointer user_data)
	This is the prototype of the callback function called whenever an event matching a subscription is received. More...

typedef void(*	AXDeclarationCompleteCallback) (guint declaration, gpointer user_data)
	This is the prototype of the callback function called when a declaration has registered with the event system. More...

Functions
AXEventHandler *	ax_event_handler_new (void)
	Creates a new `AXEventHandler`. More...

void	ax_event_handler_free (AXEventHandler *event_handler)
	Destroys an `AXEventHandler` an deallocates all associated declarations and subscriptions. Any pending callbacks associated with the `AXEventHandler` will be cancelled. More...

gboolean	ax_event_handler_declare (AXEventHandler event_handler, AXEventKeyValueSet key_value_set, gboolean stateless, guint declaration, AXDeclarationCompleteCallback callback, gpointer user_data, GError *error)
	Declares a new event. More...

gboolean	ax_event_handler_declare_from_template (AXEventHandler event_handler, const char event_template, AXEventKeyValueSet key_value_set, guint declaration, AXDeclarationCompleteCallback callback, gpointer user_data, GError **error)
	Declares a new event based upon an event template. More...

gboolean	ax_event_handler_undeclare (AXEventHandler event_handler, guint declaration, GError *error)
	Undeclares an event. Any pending callbacks associated with the declaration will be cancelled. More...

gboolean	ax_event_handler_send_event (AXEventHandler event_handler, guint declaration, AXEvent event, GError **error)
	Sends an event. More...

gboolean	ax_event_handler_subscribe (AXEventHandler event_handler, AXEventKeyValueSet key_value_set, guint subscription, AXSubscriptionCallback callback, gpointer user_data, GError *error)
	Subscribes to an event or a set of events. More...

gboolean	ax_event_handler_unsubscribe (AXEventHandler event_handler, guint subscription, GError *error)
	Unsubscribes from an event or a set of events. More...

Detailed Description

The AXEventHandler is the main entry point into the event system. The functions in this module are thread safe.

Typedef Documentation

◆ AXSubscriptionCallback

typedef void(* AXSubscriptionCallback) (guint subscription, AXEvent *event, gpointer user_data)

This is the prototype of the callback function called whenever an event matching a subscription is received.

Parameters

subscription	The subscription handle associated with the subscription.
event	The received event. It's the responsibility of of the callback receiver to free the event.
user_data	The user_data pointer supplied to `ax_event_handler_subscribe` when the subscription was set up.

Examples:: ax_event_subscription_example.c.

◆ AXDeclarationCompleteCallback

typedef void(* AXDeclarationCompleteCallback) (guint declaration, gpointer user_data)

This is the prototype of the callback function called when a declaration has registered with the event system.

Parameters

declaration	The handle associated with a declaration.
user_data	The user_data pointer supplied to `ax_event_handler_declare` or `ax_event_handler_declare_from_template` when the declaration was set up.

Function Documentation

◆ ax_event_handler_new()

AXEventHandler* ax_event_handler_new ( void )

Creates a new AXEventHandler.

Returns: a newly allocated AXEventHandler.

Examples:: ax_event_property_state_declaration_example.c, ax_event_property_state_declaration_from_template_example.c, ax_event_stateless_declaration_example.c, ax_event_stateless_declaration_from_template_example.c, and ax_event_subscription_example.c.

◆ ax_event_handler_free()

void ax_event_handler_free ( AXEventHandler * event_handler )

Destroys an AXEventHandler an deallocates all associated declarations and subscriptions. Any pending callbacks associated with the AXEventHandler will be cancelled.

Parameters

event_handler An AXEventHandler.

Examples:: ax_event_property_state_declaration_example.c, ax_event_property_state_declaration_from_template_example.c, ax_event_stateless_declaration_example.c, ax_event_stateless_declaration_from_template_example.c, and ax_event_subscription_example.c.

◆ ax_event_handler_declare()

gboolean ax_event_handler_declare	(	AXEventHandler *	event_handler,
		AXEventKeyValueSet *	key_value_set,
		gboolean	stateless,
		guint *	declaration,
		AXDeclarationCompleteCallback	callback,
		gpointer	user_data,
		GError **	error
	)

Declares a new event.

Parameters

event_handler	An `AXEventHandler`.
key_value_set	An `AXEventKeyValueSet` describing the event.
stateless	`TRUE` if the event is a stateless event, otherwise `FALSE`.
declaration	The return location for a unique handle associated with the resulting declaration.
callback	A callback function that will be called when the declaration has been registered with the event system or `NULL`.
user_data	A pointer that will be supplied with the call to the `callback` function.
error	The return location for an error or `NULL`.

Returns: TRUE if the declaration was successful otherwise FALSE. If FALSE and error is not NULL, then error contains a detailed description of the error.

Examples:: ax_event_property_state_declaration_example.c, and ax_event_stateless_declaration_example.c.

◆ ax_event_handler_declare_from_template()

gboolean ax_event_handler_declare_from_template	(	AXEventHandler *	event_handler,
		const char *	event_template,
		AXEventKeyValueSet *	key_value_set,
		guint *	declaration,
		AXDeclarationCompleteCallback	callback,
		gpointer	user_data,
		GError **	error
	)

Declares a new event based upon an event template.

Parameters

event_handler	An `AXEventHandler`.
event_template	The name of the event template.
key_value_set	An `AXEventKeyValueSet` that describes the wild-card values in the event template.
declaration	The return location for a unique handle associated with the declaration.
callback	A callback function that will be called when the declaration has been registered with the event system.
user_data	A pointer that will be supplied with the call to the `callback` function.
error	The return location for an error or `NULL`.

Returns: TRUE if the declaration was successful otherwise FALSE. If FALSE and error is not NULL, then error contains a detailed description of the error.

Examples:: ax_event_property_state_declaration_from_template_example.c, and ax_event_stateless_declaration_from_template_example.c.

◆ ax_event_handler_undeclare()

gboolean ax_event_handler_undeclare	(	AXEventHandler *	event_handler,
		guint	declaration,
		GError **	error
	)

Undeclares an event. Any pending callbacks associated with the declaration will be cancelled.

Parameters

event_handler	An `AXEventHandler`.
declaration	A declaration handle previously obtained from `ax_event_handler_declare`.
error	The return location for an error or `NULL`.

Returns: TRUE if the declaration was successfully undeclared otherwise FALSE. If FALSE and error is not NULL, then error contains a detailed description of the error.

Examples:: ax_event_property_state_declaration_example.c, ax_event_property_state_declaration_from_template_example.c, ax_event_stateless_declaration_example.c, and ax_event_stateless_declaration_from_template_example.c.

◆ ax_event_handler_send_event()

gboolean ax_event_handler_send_event	(	AXEventHandler *	event_handler,
		guint	declaration,
		AXEvent *	event,
		GError **	error
	)

Sends an event.

Parameters

event_handler	An `AXEventHandler`.
declaration	A declaration handle previously obtains from `ax_event_handler_declare`.
event	An `AXEvent` containing the updated values that represent the event.
error	The return location for an error or `NULL`.

Returns: TRUE if the event was successfully sent otherwise FALSE. If FALSE and error is not NULL, then error contains a detailed description of the error.

◆ ax_event_handler_subscribe()

gboolean ax_event_handler_subscribe	(	AXEventHandler *	event_handler,
		AXEventKeyValueSet *	key_value_set,
		guint *	subscription,
		AXSubscriptionCallback	callback,
		gpointer	user_data,
		GError **	error
	)

Subscribes to an event or a set of events.

Parameters

event_handler	An `AXEventHandler`.
key_value_set	An `AXEventKeyValueSet` containing the keys and values matching the keys and values of the event(s) that is/are being subscribed to.
subscription	A return location for a unique handle associated with the subscription.
callback	A callback function which will be called as soon as an event macthing the subscription is received.
user_data	A pointer to data that should be supplied to the `callback` function.
error	The return location for an error or `NULL`.

Returns: TRUE if the subscription was successful otherwise FALSE. If FALSE and error is not NULL, then error contains a detailed description of the error.

Examples:: ax_event_subscription_example.c.

◆ ax_event_handler_unsubscribe()

gboolean ax_event_handler_unsubscribe	(	AXEventHandler *	event_handler,
		guint	subscription,
		GError **	error
	)

Unsubscribes from an event or a set of events.

Parameters

event_handler	An `AXEventHandler`
subscription	A subscription handle previously obtained from `ax_event_handler_subscribe`.
error	The return location for an error or `NULL`.

Returns: TRUE if the unsubscribe was successful otherwise FALSE. If FALSE and error is not NULL, then error contains a detailed description of the error.

Examples:: ax_event_subscription_example.c.

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ AXSubscriptionCallback

◆ AXDeclarationCompleteCallback

Function Documentation

◆ ax_event_handler_new()

◆ ax_event_handler_free()

◆ ax_event_handler_declare()

◆ ax_event_handler_declare_from_template()

◆ ax_event_handler_undeclare()

◆ ax_event_handler_send_event()

◆ ax_event_handler_subscribe()

◆ ax_event_handler_unsubscribe()