Event Methods

Collaboration diagram for Event Methods:

Functions
void	amxd_object_send_signal (amxd_object_t *const object, const char *name, amxc_var_t *const data, bool trigger)
	Send an object signal/event. More...
AMXD_INLINE void	amxd_object_emit_signal (amxd_object_t *const object, const char *name, amxc_var_t *const data)
	Emit an object signal/event. More...
AMXD_INLINE void	amxd_object_trigger_signal (amxd_object_t *const object, const char *name, amxc_var_t *const data)
	Emit an object signal/event. More...
void	amxd_object_send_add_inst (amxd_object_t *instance, bool trigger)
	Send an add instance object event. More...
AMXD_INLINE void	amxd_object_emit_add_inst (amxd_object_t *instance)
	Emit an add instance object event. More...
AMXD_INLINE void	amxd_object_trigger_add_inst (amxd_object_t *instance)
	Trigger an add instance object event. More...
void	amxd_object_send_del_inst (amxd_object_t *instance, bool trigger)
	Send a delete instance object event. More...
AMXD_INLINE void	amxd_object_emit_del_inst (amxd_object_t *instance)
	Emit a delete instance object event. More...
AMXD_INLINE void	amxd_object_trigger_del_inst (amxd_object_t *instance)
	Trigger a delete instance object event. More...
void	amxd_object_send_changed (amxd_object_t *object, amxc_var_t *params, bool trigger)
	Send an object changed event. More...
AMXD_INLINE void	amxd_object_emit_changed (amxd_object_t *object, amxc_var_t *params)
	Emit an object changed event. More...
AMXD_INLINE void	amxd_object_trigger_changed (amxd_object_t *object, amxc_var_t *params)
	Trigger an object changed event. More...
amxd_status_t	amxd_object_new_pi (amxd_object_t *object, uint32_t sec)
	Creates and starts a periodic inform event timer. More...
amxd_status_t	amxd_object_delete_pi (amxd_object_t *object)
	Stops and deletes a periodic inform event timer. More...
amxd_status_t	amxd_object_add_event_ext (amxd_object_t *const object, const char *event_name, amxc_var_t *event_data)
	Adds an event definition to the object. More...
amxd_status_t	amxd_object_add_event (amxd_object_t *const object, const char *event_name)
	Adds an event definition to the object. More...
void	amxd_object_remove_event (amxd_object_t *const object, const char *event_name)
	Removes an event definition to the object. More...
amxc_var_t *	amxd_object_new_event_data (const amxd_object_t *object, const char *event_name)
	Allocates a variant that contains the predefined event data. More...

Detailed Description

Function Documentation

amxd_object_add_event()

amxd_status_t amxd_object_add_event	(	amxd_object_t *const	object,
		const char *	event_name
	)

Adds an event definition to the object.

Events can be defined and stored in the data model definition.

If an event data template must be added use function amxd_object_add_event_ext.

This function wil call amxd_object_add_event_ext and set the event data pointer to NULL.

Parameters

object	The object in which an event must be defined.
event_name	The name of the event.

Returns

amxd_status_ok when the event definition was successfully added to the object definition Any other value indicates an error.

Definition at line 411 of file amxd_object_event.c.

                                                            {
    return amxd_object_add_event_ext(object, event_name, NULL);
}

amxd_object_add_event_ext()

amxd_status_t amxd_object_add_event_ext	(	amxd_object_t *const	object,
		const char *	event_name,
		amxc_var_t *	event_data
	)

Adds an event definition to the object.

Events and the data they can contain can be defined and stored in the data model definition.

To allocate a variant containing the event data the function amxd_object_new_event_data can be used.

Parameters

object	The object in which an event must be defined.
event_name	The name of the event.
event_data	(optional) The event data definition template.

Returns

amxd_status_ok when the event definition was successfully added to the object definition Any other value indicates an error.

Definition at line 376 of file amxd_object_event.c.

                                                                {
    amxd_status_t retval = amxd_status_unknown_error;
    amxd_dm_t* dm = amxd_object_get_dm(object);
 
    when_null(dm, exit);
 
    if(event_data != NULL) {
        when_failed(amxc_var_set_key(&object->events,
                                     event_name,
                                     event_data,
                                     AMXC_VAR_FLAG_DEFAULT | AMXC_VAR_FLAG_UPDATE), exit);
    } else {
        amxc_var_t* event = amxc_var_get_key(&object->events,
                                             event_name,
                                             AMXC_VAR_FLAG_DEFAULT);
        if(event == NULL) {
            when_null(amxc_var_add_new_key(&object->events,
                                           event_name), exit);
        } else {
            amxc_var_set_type(event, AMXC_VAR_ID_NULL);
        }
    }
 
    amxp_sigmngr_add_signal(&dm->sigmngr, event_name);
    retval = amxd_status_ok;
 
exit:
    if(retval != amxd_status_ok) {
        amxc_var_delete(&event_data);
    }
    return retval;
}

amxd_object_delete_pi()

amxd_status_t amxd_object_delete_pi

(

amxd_object_t *

object

)

Stops and deletes a periodic inform event timer.

A periodic inform timer can be created and started using amxd_object_new_pi.

This function will stop and deletes the periodic inform timer for the object.

Parameters

object

The object for which a periodic inform event must be stopped.

Returns

amxd_status_ok when periodic inform timer was created and started successfully. Any other value indicates an error.

Definition at line 355 of file amxd_object_event.c.

                                                           {
    amxd_status_t status = amxd_status_unknown_error;
    amxp_timer_t* timer = NULL;
 
    when_null(object, exit);
    when_true(object->type == amxd_object_root, exit);
 
    timer = (amxp_timer_t*) amxd_object_get_action_cb_data(object,
                                                           action_object_destroy,
                                                           amxd_object_delete_timer);
    when_null(timer, exit);
    amxp_timer_delete(&timer);
    status = amxd_object_remove_action_cb(object,
                                          action_object_destroy,
                                          amxd_object_delete_timer);
 
exit:
    return status;
 
}

amxd_object_emit_add_inst()

AMXD_INLINE void amxd_object_emit_add_inst

(

amxd_object_t *

instance

)

Emit an add instance object event.

See also

amxd_object_send_add_inst.

This function will call amxd_object_send_add_inst with trigger set to false.

Parameters

instance

The newly added instance.

Definition at line 230 of file amxd_object_event.h.

                                                        {
    amxd_object_send_add_inst(instance, false);
}

amxd_object_emit_changed()

AMXD_INLINE void amxd_object_emit_changed	(	amxd_object_t *	object,
		amxc_var_t *	params
	)

Emit an object changed event.

See also

amxd_object_send_changed.

This function will call amxd_object_send_changed with trigger set to false.

Parameters

object	The object for which the changed event must be sent.
params	A hash table of the parameters with their original values (before the change)

Definition at line 399 of file amxd_object_event.h.

                                                  {
    amxd_object_send_changed(object, params, false);
}

amxd_object_emit_del_inst()

AMXD_INLINE void amxd_object_emit_del_inst

(

amxd_object_t *

instance

)

Emit a delete instance object event.

See also

amxd_object_send_del_inst.

This function will call amxd_object_send_del_inst with trigger set to false.

Parameters

instance

The instance that will be deleted.

Definition at line 317 of file amxd_object_event.h.

                                                        {
    amxd_object_send_del_object(instance, false);
}

amxd_object_emit_signal()

AMXD_INLINE void amxd_object_emit_signal	(	amxd_object_t *const	object,
		const char *	name,
		amxc_var_t *const	data
	)

Emit an object signal/event.

See also

amxd_object_send_signal.

This function will call amxd_object_send_signal with trigger set to false.

Parameters

object	the object for which the event must be send.
name	the event name.
data	(optional, can be NULL) the event data.

Definition at line 142 of file amxd_object_event.h.

                                                     {
    amxd_object_send_signal(object, name, data, false);
}

amxd_object_new_event_data()

amxc_var_t* amxd_object_new_event_data	(	const amxd_object_t *	object,
		const char *	event_name
	)

Allocates a variant that contains the predefined event data.

This function allocates a variant on the heap. The returned variant pointer can be used to set the correct event values for the event data.

The returned pointer must be freed using amxc_var_delete.

Parameters

object	The object from which an event must be removed.
event_name	The name of the event.

Returns

A pointer to a amxc_var_t structure or a NULL pointer if no such event was defined.

Definition at line 424 of file amxd_object_event.c.

                                                               {
    amxc_var_t* data = NULL;
 
    when_null(object, exit);
    when_str_empty(event_name, exit);
 
    data = amxc_var_get_key(&object->events, event_name, AMXC_VAR_FLAG_COPY);
    when_not_null(data, exit);
 
    if(amxd_object_get_type(object) == amxd_object_instance) {
        object = amxd_object_get_parent(object);
    } else {
        object = amxd_object_get_base(object);
    }
    while(object != NULL) {
        data = amxc_var_get_key(&object->events, event_name, AMXC_VAR_FLAG_COPY);
        if(data != NULL) {
            break;
        }
        object = amxd_object_get_base(object);
    }
 
exit:
    return data;
}

amxd_object_new_pi()

amxd_status_t amxd_object_new_pi	(	amxd_object_t *	object,
		uint32_t	sec
	)

Creates and starts a periodic inform event timer.

A periodic inform timer will send an event at a regular interval. The event will contain all parameters of the object and their values at that moment.

A periodic inform timer can be used to send the values of volatile parameters (typically statistics).

Only one periodic inform timer can be created for an object.

Use amxd_object_delete_pi to stop and delete the periodic inform timer.

When the object is deleted the timer will be stopped and deleted as well.

Example of a periodic inform event:

{
    path = "Greeter.Statistics.",
    object = "Greeter.Statistics.",
    eobject = "Greeter.Statistics.",
    notification = "dm:periodic-inform",
    parameters = {
        AddHistoryCount = 0,
        DelHistoryCount = 0,
        EventCount = 6
    }
}

The event data:

• The object path (path, object, eobject - see amxd_object_send_signal) This is the path to the multi-instance object.
• notification: the event name
• parameters: All parameters of the object and their values as a hash table.

Parameters

object	The object for which a periodic inform event must be created.
sec	Interval in seconds at which the event must be sent.

Returns

amxd_status_ok when periodic inform timer was created and started successfully. Any other value indicates an error.

Definition at line 329 of file amxd_object_event.c.

                                               {
    amxd_status_t status = amxd_status_unknown_error;
    amxp_timer_t* timer = NULL;
 
    when_null(object, exit);
    when_true(sec == 0, exit);
    when_true(object->type == amxd_object_root, exit);
    when_true(amxd_object_has_action_cb(object,
                                        action_object_destroy,
                                        amxd_object_delete_timer), exit);
 
    amxp_timer_new(&timer, amxd_periodic_inform, object);
    when_null(timer, exit);
 
    amxp_timer_set_interval(timer, sec * 1000);
    amxp_timer_start(timer, sec * 1000);
 
    status = amxd_object_add_action_cb(object,
                                       action_object_destroy,
                                       amxd_object_delete_timer,
                                       timer);
exit:
    return status;
}

amxd_object_remove_event()

void amxd_object_remove_event	(	amxd_object_t *const	object,
		const char *	event_name
	)

Removes an event definition to the object.

This function will remove an event definition from the data model definition.

Events definitions can be added using amxd_object_add_event or amxd_object_add_event_ext.

Parameters

object	The object from which an event must be removed.
event_name	The name of the event.

Returns

amxd_status_ok when the event definition was successfully removed from the object definition Any other value indicates an error.

Definition at line 416 of file amxd_object_event.c.

                                                      {
    amxc_var_t* event = amxc_var_get_key(&object->events,
                                         event_name,
                                         AMXC_VAR_FLAG_DEFAULT);
    amxc_var_delete(&event);
}

amxd_object_send_add_inst()

void amxd_object_send_add_inst	(	amxd_object_t *	instance,
		bool	trigger
	)

Send an add instance object event.

Creates a data model add instance event and calls all connected functions. When the trigger argument is set to true the connected functions (callback functions) are called immediately, when set to false the functions will be called from the eventloop implementation.

Besides the base event data an add instance event contains the index and name of the newly added instance, a hash table containing the key parameters and a hash table containing all parameters.

Example of an add instance event:

{
    path = "Greeter.History.1.Info.",
    object = "Greeter.History.1.Info.",
    eobject = "Greeter.History.[1].Info.",
    notification = "dm:instance-added",
    index = 1,
    name = "cpe-Info-1",
    keys = {
        Alias = "cpe-Info-1"
    },
    parameters = {
        Alias = "cpe-Info-1",
        Disabled = 0,
        Flags = "",
        Number = 0,
        SignedNumber = -100,
        Text = ""
    }
}

The event data:

• The object path (path, object, eobject - see amxd_object_send_signal) This is the path to the multi-instance object.
• index: The index of the newly added instance
• name: The object name of the newly added instance (mostly the value of the Alias parameter)
• keys: The key parameters and their values as a hash table.
• parameters: All parameters and their values as a hash table.

Parameters

instance	The newly added instance.
trigger	when set to true, call callback functions immediately.

Definition at line 243 of file amxd_object_event.c.

                                                                      {
    when_null(instance, exit);
    when_true(amxd_object_get_type(instance) != amxd_object_instance, exit);
 
    amxd_object_send_event_add(instance, INT32_MAX, &trigger);
    amxd_object_for_each(child, it, instance) {
        amxd_object_t* object = amxc_container_of(it, amxd_object_t, it);
        amxd_object_hierarchy_walk(object,
                                   amxd_direction_down,
                                   amxd_object_event_filter_add,
                                   amxd_object_send_event_add,
                                   INT32_MAX,
                                   &trigger);
    }
 
exit:
    return;
}

amxd_object_send_changed()

void amxd_object_send_changed	(	amxd_object_t *	object,
		amxc_var_t *	params,
		bool	trigger
	)

Send an object changed event.

Creates a data model object changed event and calls all connected functions. When the trigger argument is set to true the connected functions (callback functions) are called immediately, when set to false the functions will be called from the eventloop implementation.

Besides the base event data an object changed event contains all changed parameters. For each changed parameter the event will contain the value of the parameter before the change and the changed value

Example of an add instance event:

{
    path = "Greeter.History.1.Info.1.",
    object = "Greeter.History.1.Info.cpe-Info-1.",
    eobject = "Greeter.History.[1].Info.[cpe-Info-1].",
    notification = "dm:object-changed",
    parameters = {
        Number = {
            from = 0,
            to = 101
        },
        Text = {
            from = "",
            to = "Hello"
        }
    },
}

The event data:

• The object path (path, object, eobject - see amxd_object_send_signal) This is the path to the object that has been changed.
• notification: the name of the event
• parameters: All changed parameters as a hash table, each parameter is represented as a hash table that contains the original value (from) and the new value (to).

Parameters

object	The object for which the changed event must be sent.
params	A hash table of the parameters with their original values (before the change)
trigger	when set to true, call callback functions immediately.

Definition at line 280 of file amxd_object_event.c.

                                            {
    const amxc_htable_t* tparams = NULL;
    amxc_var_t data;
    amxc_var_t values;
    amxc_var_t* parameters = NULL;
    amxc_var_init(&data);
    amxc_var_init(&values);
 
    when_null(object, exit);
    when_null(params, exit);
    when_true(amxc_var_type_of(params) != AMXC_VAR_ID_HTABLE, exit);
    amxc_var_set_type(&values, AMXC_VAR_ID_HTABLE);
 
    amxc_var_for_each(ovalue, params) {
        amxd_param_t* param_def = amxd_object_get_param_def(object, amxc_var_key(ovalue));
        if(param_def == NULL) {
            amxc_var_set_type(&values, AMXC_VAR_ID_HTABLE);
            amxd_object_get_params_filtered(amxd_param_get_owner(param_def),
                                            &values,
                                            "attributes.volatile==false",
                                            amxd_dm_access_protected);
            break;
        }
        if(!amxd_param_is_attr_set(param_def, amxd_pattr_variable)) {
            amxc_var_set_key(&values, amxc_var_key(ovalue), &param_def->value, AMXC_VAR_FLAG_COPY);
        }
    }
 
    amxc_var_set_type(&data, AMXC_VAR_ID_HTABLE);
    parameters = amxc_var_add_key(amxc_htable_t, &data, "parameters", NULL);
    amxc_var_for_each(ovalue, params) {
        const char* name = amxc_var_key(ovalue);
        amxd_build_param_changed(name, &values, parameters, ovalue);
    }
 
    tparams = amxc_var_constcast(amxc_htable_t, parameters);
 
    if(!amxc_htable_is_empty(tparams)) {
        amxd_dm_event("dm:object-changed", object, &data, trigger);
    }
 
exit:
    amxc_var_clean(&values);
    amxc_var_clean(&data);
    return;
}

amxd_object_send_del_inst()

void amxd_object_send_del_inst	(	amxd_object_t *	instance,
		bool	trigger
	)

Send a delete instance object event.

Creates a data model delete instance event and calls all connected functions. When the trigger argument is set to true the connected functions (callback functions) are called immediately, when set to false the functions will be called from the eventloop implementation.

Besides the base event data a delete instance event contains the index and name of the newly deleted instance, a hash table containing the key parameters and their values and a hash table containing all parameters and their last known values.

Example of a delete instance event:

{
    path = "Greeter.History.1.Info.",
    object = "Greeter.History.1.Info.",
    eobject = "Greeter.History.[1].Info.",
    notification = "dm:instance-removed",
    index = 1,
    name = "cpe-Info-1",
    keys = {
        Alias = "cpe-Info-1"
    },
    parameters = {
        Alias = "cpe-Info-1",
        Disabled = 0,
        Flags = "",
        Number = 0,
        SignedNumber = -100,
        Text = ""
    }
}

The event data:

• The object path (path, object, eobject - see amxd_object_send_signal) This is the path to the multi-instance object that contained the instance.
• index: The index of the deleted instance
• name: The object name of the deleted instance (mostly the value of the Alias parameter)
• keys: The key parameters and their last known values as a hash table.
• parameters: All parameters and their last known values as a hash table.

Warning

It is possible that when the callback functions are called that the object already is deleted, so it will not be accessible anymore.

Parameters

instance	The instance that is going to be deleted.
trigger	when set to true, call callback functions immediately.

Definition at line 276 of file amxd_object_event.c.

                                                                      {
    amxd_object_send_del_object(instance, trigger);
}

amxd_object_send_signal()

void amxd_object_send_signal	(	amxd_object_t *const	object,
		const char *	name,
		amxc_var_t *const	data,
		bool	trigger
	)

Send an object signal/event.

Creates a data model event and calls all connected functions. When the trigger argument is set to true the connected functions (callback functions) are called immediately, when set to false the functions will be called from the eventloop implementation.

A data model event always contains the name of the event and the object path in different formats.

Example of a base event:

{
    path = "Greeter.History.1.Info.1."
    object = "Greeter.History.1.Info.cpe-Info-1.",
    eobject = "Greeter.History.[1].Info.[cpe-Info-1].",
    notification = "dm:object-changed",
}

The base event data:

• path: is the USP compatible object path using the indices for the instances.
• object: the object path using the names of the instances, be aware that when the instance contains an Alias parameter, the value of the Alias parameter is used as the name of the instance. An Alias parameter value may contain dots.
• eobject: the object path using the names of the instances put between brackets.
• notification: the name of the event.

Other data can be provided in an event. Which extra data is added, depends on the event type itself.

Warning

It is recommended to use the path and avoid to use the object or eobject. The path is compatible with USP specifications while object and eobject paths can only be used in ambiorix APIs.

Parameters

object	the object for which the event must be sent.
name	the event name.
data	(optional, can be NULL) the event data.
trigger	when set to true, call callback functions immediately.

Definition at line 230 of file amxd_object_event.c.

                                           {
 
    when_null(object, exit);
    when_str_empty(name, exit);
 
    amxd_dm_event(name, object, data, trigger);
exit:
    return;
}

amxd_object_trigger_add_inst()

AMXD_INLINE void amxd_object_trigger_add_inst

(

amxd_object_t *

instance

)

Trigger an add instance object event.

See also

amxd_object_send_add_inst.

This function will call amxd_object_send_add_inst with trigger set to true.

Parameters

instance

The newly added instance.

Definition at line 246 of file amxd_object_event.h.

                                                           {
    amxd_object_send_add_inst(instance, true);
}

amxd_object_trigger_changed()

AMXD_INLINE void amxd_object_trigger_changed	(	amxd_object_t *	object,
		amxc_var_t *	params
	)

Trigger an object changed event.

See also

amxd_object_send_changed.

This function will call amxd_object_send_changed with trigger set to true.

Parameters

object	The object for which the changed event must be sent.
params	A hash table of the parameters with their original values (before the change)

Definition at line 417 of file amxd_object_event.h.

                                                     {
    amxd_object_send_changed(object, params, true);
}

amxd_object_trigger_del_inst()

AMXD_INLINE void amxd_object_trigger_del_inst

(

amxd_object_t *

instance

)

Trigger a delete instance object event.

See also

amxd_object_send_del_inst.

This function will call amxd_object_send_del_inst with trigger set to true.

Parameters

instance

The instance that will be deleted.

Definition at line 333 of file amxd_object_event.h.

                                                           {
    amxd_object_send_del_object(instance, true);
}

amxd_object_trigger_signal()

AMXD_INLINE void amxd_object_trigger_signal	(	amxd_object_t *const	object,
		const char *	name,
		amxc_var_t *const	data
	)

Emit an object signal/event.

See also

amxd_object_send_signal.

This function will call amxd_object_send_signal with trigger set to true.

Parameters

object	the object for which the event must be send.
name	the event name.
data	(optional, can be NULL) the event data.

Definition at line 162 of file amxd_object_event.h.

                                                        {
    amxd_object_send_signal(object, name, data, true);
}