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...

typedef void(*	AXUnsubscribeCompleteCallback) (guint declaration, gpointer user_data, GError *error)
	This is the prototype of the callback function called when a subscription has been removed. 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_declare2 (AXEventHandler event_handler, AXEventKeyValueSet key_value_set, gboolean stateless, gchar property_name, 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. This function is deprecated, use ax_event_handler_unsubscribe_and_notify instead. More...

gboolean	ax_event_handler_unsubscribe_and_notify (AXEventHandler event_handler, guint subscription, AXUnsubscribeCompleteCallback callback, gpointer user_data, GError *error)
	Asynchronously unsubscribes from an event or a set of events. When unsubscribe has completed, the user provided callback will be called. The callback will be called from the default GMainContext. 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.

◆ AXUnsubscribeCompleteCallback

typedef void(* AXUnsubscribeCompleteCallback) (guint declaration, gpointer user_data, GError *error)

This is the prototype of the callback function called when a subscription has been removed.

Parameters

declaration	The handle associated with a declaration.
user_data	The user_data pointer supplied to `ax_event_handler_unsubscribe_and_notify`.
error	Error information if anything goes wrong. Needs to be freed by the user if not NULL.

Examples: ax_event_subscription_example.c.

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_declare2()

gboolean ax_event_handler_declare2	(	AXEventHandler *	event_handler,
		AXEventKeyValueSet *	key_value_set,
		gboolean	stateless,
		gchar *	property_name,
		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`.
property_name	The name of the key that should be a stateful property. This is only used for stateful events.
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.

◆ 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. This function is deprecated, use ax_event_handler_unsubscribe_and_notify instead.

This is a blocking call which uses the default GMainContext to conduct the unsubscribe operation. Must not be called from within the default GMainContext.

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.

◆ ax_event_handler_unsubscribe_and_notify()

gboolean ax_event_handler_unsubscribe_and_notify	(	AXEventHandler *	event_handler,
		guint	subscription,
		AXUnsubscribeCompleteCallback	callback,
		gpointer	user_data,
		GError **	error
	)

Asynchronously unsubscribes from an event or a set of events. When unsubscribe has completed, the user provided callback will be called. The callback will be called from the default GMainContext.

Parameters

event_handler	An `AXEventHandler`
subscription	A subscription handle previously obtained from `ax_event_handler_subscribe`.
callback	A callback function which will be called when unsubscribing has been completed.
user_data	A pointer to data which will be supplied `callback` function.
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

◆ AXUnsubscribeCompleteCallback

Function Documentation

◆ ax_event_handler_new()

◆ ax_event_handler_free()

◆ ax_event_handler_declare()

◆ ax_event_handler_declare2()

◆ ax_event_handler_declare_from_template()

◆ ax_event_handler_undeclare()

◆ ax_event_handler_send_event()

◆ ax_event_handler_subscribe()

◆ ax_event_handler_unsubscribe()

◆ ax_event_handler_unsubscribe_and_notify()