The AXEventKeyValueSet and its associated functions describe the keys and values that constitute events, event declarations and event subscriptions. The functions in this module are not thread safe. Only UTF-8 strings are supported. More...

Typedefs
typedef struct _AXEventKeyValueSet	AXEventKeyValueSet
	The `AXEventKeyValueSet` is an opaque data type required to create event declarations, event subscription and for receiving events.

Functions
AXEventKeyValueSet *	ax_event_key_value_set_new (void)
	Creates a new `AXEventKeyValueSet`. More...

void	ax_event_key_value_set_free (AXEventKeyValueSet *key_value_set)
	Frees an `AXEventKeyValueSet`. More...

gboolean	ax_event_key_value_set_add_key_values (AXEventKeyValueSet key_value_set, GError *error,...)
	Adds a set of key/value pairs to an `AXEventKeyValueSet`. The number of arguments is arbitrary and must be on the form. More...

gboolean	ax_event_key_value_set_add_key_value (AXEventKeyValueSet key_value_set, const gchar key, const gchar name_space, gconstpointer value, AXEventValueType value_type, GError *error)
	Add a key/value pair to an `AXEventKeyValueSet`. If the added key is already in the `AXEventKeyValueSet`, then the value associated with the key will be replaced. More...

gboolean	ax_event_key_value_set_mark_as_source (AXEventKeyValueSet key_value_set, const gchar key, const gchar name_space, GError *error)
	Mark a key in the `AXEventKeyValueSet` as a source. A source key is an identifier used to distinguish between multiple instances of the same event declaration. E.g. if a device has multiple I/O ports then event declarations that represent the state of each port will have the same keys but different values. The key that represents which port the event represents should be marked as source and the key which represents the state should be marked as data. Please note that although it is possible to mark more than one key as a source, only events with zero or one source keys can be used to trigger actions. More...

gboolean	ax_event_key_value_set_mark_as_data (AXEventKeyValueSet key_value_set, const gchar key, const gchar name_space, GError *error)
	Mark a key in the `AXEventKeyValueSet` as data. A data key is a key that represents the state of what the event represents. E.g. an event declaration that represents an I/O port should have a key marked as data which represents the state, high or low, of the port. Please note that although it is possible to mark more than one key as data, only events with one and only one data key can be used to trigger actions. More...

gboolean	ax_event_key_value_set_mark_as_user_defined (AXEventKeyValueSet key_value_set, const gchar key, const gchar name_space, const gchar user_tag, GError **error)
	Mark a key in `AXEventKeyValueSet` with an user defined tag. More...

gboolean	ax_event_key_value_set_add_nice_names (AXEventKeyValueSet key_value_set, const gchar key, const gchar name_space, const gchar key_nice_name, const gchar value_nice_name, GError *error)
	Set the nice names of a key/value pair in the `AXEventKeyValueSet`. Nice names can be used to display human-readable information about the key/value pair. More...

gboolean	ax_event_key_value_set_get_value_type (const AXEventKeyValueSet key_value_set, const gchar key, const gchar name_space, AXEventValueType value_type, GError **error)
	Retrieve the value type of the value associated with a key. More...

gboolean	ax_event_key_value_set_get_integer (const AXEventKeyValueSet key_value_set, const gchar key, const gchar name_space, gint value, GError **error)
	Retrieve the integer value associated with a key. More...

gboolean	ax_event_key_value_set_get_boolean (const AXEventKeyValueSet key_value_set, const gchar key, const gchar name_space, gboolean value, GError **error)
	Retrieve the boolean value associated with a key. More...

gboolean	ax_event_key_value_set_get_double (const AXEventKeyValueSet key_value_set, const gchar key, const gchar name_space, gdouble value, GError **error)
	Retrieve the double value associated with a key. More...

gboolean	ax_event_key_value_set_get_string (const AXEventKeyValueSet key_value_set, const gchar key, const gchar name_space, gchar value, GError *error)
	Retrieve the string value associated with a key. More...

gboolean	ax_event_key_value_set_get_element (const AXEventKeyValueSet key_value_set, const gchar key, const gchar name_space, AXEventElementItem item, GError *error)
	Retrieve the element item associated with a key. More...

gboolean	ax_event_key_value_set_remove_key (AXEventKeyValueSet key_value_set, const gchar key, const gchar name_space, GError *error)
	Removes a key and its associated value from an `AXEventKeyValueSet`. More...

Detailed Description

The AXEventKeyValueSet and its associated functions describe the keys and values that constitute events, event declarations and event subscriptions. The functions in this module are not thread safe. Only UTF-8 strings are supported.

AXEventKeyValueSet

All events are expressed as a set of key/value pairs, where the key should be assigned to a namespace. For exampel, the event describing that the first I/O port is active is described by the following key/value pairs

   tns1:topic0=Device
tnsaxis:topic1=IO
tnsaxis:topic2=Port
          port=0
         state=1

Where

tns1: is a namespace defined by Onvif.
tnsaxis: is a namespace defined by Axis.
topic0: is a key.
Device: is a value.

The namespace's primary purpose is to avoid name clashes but is also used to distinguish between events declared by different vendors. Each vendor should define their own namespace. In the I/O port example, the keys "port" and "state" are not assigned to a namespace.

The key in a key/value set is always a string. The value is typed and can be an integer, a boolean, a double or a string.

All aspects of the axevent library

Event declarations
Event subscriptions
Events

are represented as AXEventKeyValueSets.

Examples

This example shows how an AXEventKeyValueSet is created, key by key.

ax_event_key_value_set_example1.c

It is also possible to add all key/value pairs in one function call. This is shown in the example below.

ax_event_key_value_set_example2.c

Both examples produce equivalent AXEventKeyValueSets. The functions ax_event_key_value_set_add_key_value() and ax_event_key_value_set_add_key_values() can be used interchangeably to add key/value pairs to the same instance of AXEventKeyValueSet. They can also be used more than once.

Function Documentation

◆ ax_event_key_value_set_new()

AXEventKeyValueSet* ax_event_key_value_set_new ( void )

Creates a new AXEventKeyValueSet.

Returns: A newly allocated AXEventKeyValueSet.

Examples:: ax_event_key_value_set_example1.c, ax_event_key_value_set_example2.c, 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_key_value_set_free()

void ax_event_key_value_set_free ( AXEventKeyValueSet * key_value_set )

Frees an AXEventKeyValueSet.

Parameters

key_value_set An AXEventKeyValueSet

Examples:: ax_event_key_value_set_example1.c, ax_event_key_value_set_example2.c, ax_event_property_state_declaration_example.c, and ax_event_subscription_example.c.

◆ ax_event_key_value_set_add_key_values()

gboolean ax_event_key_value_set_add_key_values	(	AXEventKeyValueSet *	key_value_set,
		GError **	error,
			...
	)

Adds a set of key/value pairs to an AXEventKeyValueSet. The number of arguments is arbitrary and must be on the form.

(const char *key, const char *name_space, gpointer, ValueSort)

where name_space may be NULL. The last argument to ax_event_key_value_set_add_key_values must be NULL.

Keys that are already in the AXEventKeyValueSet will be replaced.

Parameters

key_value_set	The `AXEventKeyValueSet`
error	The return location for an error.
...	List of arguments.

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

Examples:: ax_event_key_value_set_example2.c, 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_subscription_example.c.

◆ ax_event_key_value_set_add_key_value()

gboolean ax_event_key_value_set_add_key_value	(	AXEventKeyValueSet *	key_value_set,
		const gchar *	key,
		const gchar *	name_space,
		gconstpointer	value,
		AXEventValueType	value_type,
		GError **	error
	)

Add a key/value pair to an AXEventKeyValueSet. If the added key is already in the AXEventKeyValueSet, then the value associated with the key will be replaced.

Parameters

key_value_set	The `AXEventKeyValueSet`
key	The key.
name_space	The namespace of the key or `NULL`.
value	The value associated with the key.
value_type	The type of the value held by #value.
error	Return location for an error.

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

Examples:: ax_event_key_value_set_example1.c, and ax_event_stateless_declaration_from_template_example.c.

◆ ax_event_key_value_set_mark_as_source()

gboolean ax_event_key_value_set_mark_as_source	(	AXEventKeyValueSet *	key_value_set,
		const gchar *	key,
		const gchar *	name_space,
		GError **	error
	)

Mark a key in the AXEventKeyValueSet as a source. A source key is an identifier used to distinguish between multiple instances of the same event declaration. E.g. if a device has multiple I/O ports then event declarations that represent the state of each port will have the same keys but different values. The key that represents which port the event represents should be marked as source and the key which represents the state should be marked as data. Please note that although it is possible to mark more than one key as a source, only events with zero or one source keys can be used to trigger actions.

Parameters

key_value_set	The `AXEventKeyValueSet`
key	The key.
name_space	The namespace of the key or `NULL`.
error	Return location for an error.

Returns: TRUE if 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.

◆ ax_event_key_value_set_mark_as_data()

gboolean ax_event_key_value_set_mark_as_data	(	AXEventKeyValueSet *	key_value_set,
		const gchar *	key,
		const gchar *	name_space,
		GError **	error
	)

Mark a key in the AXEventKeyValueSet as data. A data key is a key that represents the state of what the event represents. E.g. an event declaration that represents an I/O port should have a key marked as data which represents the state, high or low, of the port. Please note that although it is possible to mark more than one key as data, only events with one and only one data key can be used to trigger actions.

Parameters

key_value_set	The `AXEventKeyValueSet`
key	The key.
name_space	The namespace of the key or `NULL`.
error	Return location for an error.

Returns: TRUE if 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_key_value_set_mark_as_user_defined()

gboolean ax_event_key_value_set_mark_as_user_defined	(	AXEventKeyValueSet *	key_value_set,
		const gchar *	key,
		const gchar *	name_space,
		const gchar *	user_tag,
		GError **	error
	)

Mark a key in AXEventKeyValueSet with an user defined tag.

Parameters

key_value_set	The `AXEventKeyValueSet`
key	The key.
name_space	The namespace of the key or `NULL`.
user_tag	The user defined tag.
error	Return location for an error.

Returns: TRUE if 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.

◆ ax_event_key_value_set_add_nice_names()

gboolean ax_event_key_value_set_add_nice_names	(	AXEventKeyValueSet *	key_value_set,
		const gchar *	key,
		const gchar *	name_space,
		const gchar *	key_nice_name,
		const gchar *	value_nice_name,
		GError **	error
	)

Set the nice names of a key/value pair in the AXEventKeyValueSet. Nice names can be used to display human-readable information about the key/value pair.

Parameters

key_value_set	The `AXEventKeyValueSet`
key	The key.
name_space	The namespace of the key or `NULL`.
key_nicename	The nice name of the key or `NULL`.
value_nice_name	The nice name of the value or `NULL`.
error	Return location for an error.

Returns: TRUE if 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.

◆ ax_event_key_value_set_get_value_type()

gboolean ax_event_key_value_set_get_value_type	(	const AXEventKeyValueSet *	key_value_set,
		const gchar *	key,
		const gchar *	name_space,
		AXEventValueType *	value_type,
		GError **	error
	)

Retrieve the value type of the value associated with a key.

Parameters

key_value_set	The `AXEventKeyValueSet`
key	The key.
name_space	The namespace of the key or `NULL`.
value_type	Return location for the value type.
error	Return location for an error.

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

◆ ax_event_key_value_set_get_integer()

gboolean ax_event_key_value_set_get_integer	(	const AXEventKeyValueSet *	key_value_set,
		const gchar *	key,
		const gchar *	name_space,
		gint *	value,
		GError **	error
	)

Retrieve the integer value associated with a key.

Parameters

key_value_set	The `AXEventKeyValueSet`
key	The key.
name_space	The namespace of the key or `NULL` if the key is in the global namespace.
value	Return location for the integer value.
error	Return location for an error or `NULL`

Returns: TRUE if the key was found, 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_key_value_set_get_boolean()

gboolean ax_event_key_value_set_get_boolean	(	const AXEventKeyValueSet *	key_value_set,
		const gchar *	key,
		const gchar *	name_space,
		gboolean *	value,
		GError **	error
	)

Retrieve the boolean value associated with a key.

Parameters

key_value_set	The `AXEventKeyValueSet`.
key	The key.
name_space	The namespace of the key or `NULL` if the key is in the global namespace.
value	Return location for the boolean value.
error	Return location for an error or `NULL`.

Returns: TRUE if the key was found, 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_key_value_set_get_double()

gboolean ax_event_key_value_set_get_double	(	const AXEventKeyValueSet *	key_value_set,
		const gchar *	key,
		const gchar *	name_space,
		gdouble *	value,
		GError **	error
	)

Retrieve the double value associated with a key.

Parameters

key_value_set	The `AXEventKeyValueSet`.
key	The key.
name_space	The namespace of the key or `NULL` if the key is in the global namespace.
value	Return location for the double value.
error	Return location for an error or `NULL`

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

◆ ax_event_key_value_set_get_string()

gboolean ax_event_key_value_set_get_string	(	const AXEventKeyValueSet *	key_value_set,
		const gchar *	key,
		const gchar *	name_space,
		gchar **	value,
		GError **	error
	)

Retrieve the string value associated with a key.

Parameters

key_value_set	The `AXEventKeyValueSet`.
key	The key.
name_space	The namespace of the key or `NULL` if the key is in the global namespace.
value	Return location for the string value. If the value is found, value will point to a newly allocated string. The caller must free the string when it's no longer needed.
error	Return location for an error or `NULL`

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

◆ ax_event_key_value_set_get_element()

gboolean ax_event_key_value_set_get_element	(	const AXEventKeyValueSet *	key_value_set,
		const gchar *	key,
		const gchar *	name_space,
		AXEventElementItem **	item,
		GError **	error
	)

Retrieve the element item associated with a key.

Parameters

key_value_set	The `AXEventKeyValueSet`.
key	The key.
name_space	The namespace of the key or `NULL` if the key is in the global namespace.
item	Return location for the AXEventElementItem. If the value is found, value will point to a newly allocated item. The caller must free the item when it's no longer needed.
error	Return location for an error or `NULL`

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

◆ ax_event_key_value_set_remove_key()

gboolean ax_event_key_value_set_remove_key	(	AXEventKeyValueSet *	key_value_set,
		const gchar *	key,
		const gchar *	name_space,
		GError **	error
	)

Removes a key and its associated value from an AXEventKeyValueSet.

Parameters

key_value_set	The `AXEventKeyValueSet`
key	The key to remove.
name_space	The namespace of the key or `NULL`.
error	Return location for an error.

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

Typedefs

Functions

Detailed Description

AXEventKeyValueSet

Examples

Function Documentation

◆ ax_event_key_value_set_new()

◆ ax_event_key_value_set_free()

◆ ax_event_key_value_set_add_key_values()

◆ ax_event_key_value_set_add_key_value()

◆ ax_event_key_value_set_mark_as_source()

◆ ax_event_key_value_set_mark_as_data()

◆ ax_event_key_value_set_mark_as_user_defined()

◆ ax_event_key_value_set_add_nice_names()

◆ ax_event_key_value_set_get_value_type()

◆ ax_event_key_value_set_get_integer()

◆ ax_event_key_value_set_get_boolean()

◆ ax_event_key_value_set_get_double()

◆ ax_event_key_value_set_get_string()

◆ ax_event_key_value_set_get_element()

◆ ax_event_key_value_set_remove_key()