Data Model Default Object Action Implementations

Collaboration diagram for Data Model Default Object Action Implementations:

Functions
amxd_status_t	amxd_action_object_list (amxd_object_t *const object, amxd_param_t *const param, amxd_action_t reason, const amxc_var_t *const args, amxc_var_t *const retval, void *priv)
	Default object list action implementation. More...
amxd_status_t	amxd_action_object_describe (amxd_object_t *object, amxd_param_t *param, amxd_action_t reason, const amxc_var_t *const args, amxc_var_t *const retval, void *priv)
	Default object describe action implementation. More...
amxd_status_t	amxd_action_object_destroy (amxd_object_t *object, amxd_param_t *const param, amxd_action_t reason, const amxc_var_t *const args, amxc_var_t *const retval, void *priv)
	Default object destroy action implementation. More...
amxd_status_t	amxd_action_object_validate (amxd_object_t *const object, amxd_param_t *const param, amxd_action_t reason, const amxc_var_t *const args, amxc_var_t *const retval, void *priv)
	Default object validate action implementation. More...

Detailed Description

Function Documentation

amxd_action_object_describe()

amxd_status_t amxd_action_object_describe	(	amxd_object_t *	object,
		amxd_param_t *	param,
		amxd_action_t	reason,
		const amxc_var_t *const	args,
		amxc_var_t *const	retval,
		void *	priv
	)

Default object describe action implementation.

This action is mainly invoked for introspection purposes.

For this action the args must be a htable variant and may contain the following parameters in the htable:

• events - boolean (default = true)
• functions - boolean (default = true)
• instances - boolean (default = true) - only applicable on multi-instance objects
• objects - boolean (default = true)
• parameters - boolean (default = true)
• template_info - boolean (default = true) - only applicable on multi-instance objects
• access - integer (default = amxd_dm_access_public)
• no-param-value - boolean (default = false)

All these are optional, when the boolean parameters are not available, true is used as the default value.

The access parameter, when not available, will be set to amxd_dm_access_public

The return value will be a htable variant. The return value is put in the retval argument and can contain:

• the object attributes (attributes) as a htable variant
• the object name (name) as a string
• the object path (name notation object) as a string
• the object path (index notation path) as a string
• the list of sub-objects (objects) as a list variant
• the list of parameters (parameters) as a htable variant, each parameter is represented as a htable where the key is the parameter value and the value is the parameter description.
• the object type id ('type_id') as an integer
• the object type name ('type_name') as a string

When access is set to amxd_dm_access_public, only parameters and objects defined as public are added to the description. If access is set to amxd_dm_access_protected, parameters and objects defined as protected are added to the description.

When template_info is set to true, all parameters, functions and objects defined in the multi-instance object are added to the description.

Example of input arguments htable

args = {
   access = amxd_dm_access_protected,
   events = false,
   functions = true,
   instances = true,
   objects = true,
   parameters = true,
   template_info = false
}

Example of retval htable

retval =
{
   attributes = {
       locked = false,
       persistent = false
       private = false,
       protected = false,
       read-only = false,
   },
   name = "MyRootObject",
   object = "MyRootObject.",
   objects = [
       "MyTemplateObject"
   ],
   parameters = {
       Configured = {
           attributes = {
               counter = false,
               instance = false,
               key = false,
               mutable = false,
               persistent = false
               private = false,
               protected = false,
               read-only = false,
               template = false,
               unique = false,
               volatile = false,
           },
           flags = [
           ],
           name = "Configured",
           type_id = 12
           type_name = "bool",
           value = true,
       }
   }
   path = "MyRootObject.",
   type_id = 1,
   type_name = "singleton",
}

Parameters

object	The data model object on which the action is invoked.
param	For object actions this is always NULL
reason	The action reason. This should be action_object_describe or action_any If the reason is any other action, status amxd_status_function_not_implemented must be returned.
args	A variant containing the action arguments
retval	A variant that must be filled with the action return data
priv	An opaque pointer (user data), that is added when the action callback was set. This pointer can be NULL.

Returns

• amxd_status_ok if successful.
• amxd_status_function_not_implemented if called for the wrong reason
• amxd_status_invalid_function_argument if the args is not a htable variant
• amxd_status_object_not_found if the object can not be accessed

amxd_action_object_destroy()

amxd_status_t amxd_action_object_destroy	(	amxd_object_t *	object,
		amxd_param_t *const	param,
		amxd_action_t	reason,
		const amxc_var_t *const	args,
		amxc_var_t *const	retval,
		void *	priv
	)

Default object destroy action implementation.

This action is invoked when the object is removed from the data model. This action should never fail, it should either return amxd_status_ok or amxd_status_function_not_implemented if called for the wrong reason.

The object pointer becomes invalid when returning from this action implementation, as it will be deleted from memory and removed from the data model.

When adding private data to the object pointer, this action provides you with the possiblity to do some clean-up (like deleting the private data).

The default implementation is doing nothing.

Parameters

object	The data model object on which the action is invoked.
param	For object actions this is always NULL
reason	The action reason. This should be action_object_destroy or action_any If the reason is any other action, status amxd_status_function_not_implemented must be returned.
args	Not used in the object destroy action
retval	Not used in the object destroy action
priv	An opaque pointer (user data), that is added when the action callback was set. This pointer can be NULL.

Returns

• amxd_status_ok if successful.
• amxd_status_function_not_implemented if called for the wrong reason

amxd_action_object_list()

amxd_status_t amxd_action_object_list	(	amxd_object_t *const	object,
		amxd_param_t *const	param,
		amxd_action_t	reason,
		const amxc_var_t *const	args,
		amxc_var_t *const	retval,
		void *	priv
	)

Default object list action implementation.

This action is mainly invoked for introspection purposes.

For this action the args must be a htable variant and may contain the following parameters in the htable:

• events - boolean (default = true)
• functions - boolean (default = true)
• instances - boolean (default = true) - only applicable on multi-instance objects
• objects - boolean (default = true)
• parameters - boolean (default = true)
• template_info - boolean (default = true) - only applicable on multi-instance objects
• access - integer (default = amxd_dm_access_public)

All these are optional, when the boolean parameters are not available, true is used as the default value.

The access parameter, when not available, will be set to amxd_dm_access_public

The return value will be a htable variant, containing list variants for each requested and available topic. The returned htable variant must contain:

• a list of events, if any available and the events input argument is set to true.
• a list of functions, if any available and the functions input argument is set to true.
• a list of instances, if any available and the instances input argument is set to true.
• a list of objects, if any available and the objects input argument is set to true.
• a list of parameters, if any available and the parameters input argument is set to true

When access is set to amxd_dm_access_public, only parameters and objects defined as public must be added to the lists. If access is set to amxd_dm_access_protected, parameters and objects defined as protected must be added to the lists.

When template_info is set to true, all parameters, functions and objects defined in the multi-instance object must be added to the lists.

Example of input arguments htable

args = {
   access = amxd_dm_access_protected,
   events = false,
   functions = true,
   instances = true,
   objects = true,
   parameters = true,
   template_info = false
}

Example of retval htable

retval =
{
    functions = [
        "_list",
        "_describe",
        "_get",
        "_get_instances",
        "_get_supported",
        "_set",
        "_add",
        "_del",
        "_exec"
    ],
    objects = [
        "MyTemplateObject"
    ],
    parameters = [
        "Configured"
    ]
}

Parameters

object	The data model object on which the action is invoked.
param	For object actions this is always NULL
reason	The action reason. This should be action_object_list or action_any If the reason is any other action, status amxd_status_function_not_implemented must be returned.
args	A variant containing the action arguments
retval	A variant that must be filled with the action return data
priv	An opaque pointer (user data), that is added when the action callback was set. This pointer can be NULL.

Returns

• amxd_status_ok if successful.
• amxd_status_function_not_implemented if called for the wrong reason
• amxd_status_invalid_function_argument if the args is not a htable variant
• amxd_status_object_not_found if the object can not be accessed

amxd_action_object_validate()

amxd_status_t amxd_action_object_validate	(	amxd_object_t *const	object,
		amxd_param_t *const	param,
		amxd_action_t	reason,
		const amxc_var_t *const	args,
		amxc_var_t *const	retval,
		void *	priv
	)

Default object validate action implementation.

This default implementation will check for instances that no duplicate instance is created. It will check that the key parameters are not introducing a duplicate key with other instances of the same multi-instance object.

For singleton objects this validate action is doing nothing.

Parameters

object	The data model object on which the action is invoked.
param	For object actions this is always NULL
reason	The action reason. This should be action_object_validate or action_any If the reason is any other action, status amxd_status_function_not_implemented must be returned.
args	Not used in the object validate action
retval	Not used in the object validate action
priv	An opaque pointer (user data), that is added when the action callback was set. This pointer can be NULL.

Returns

• amxd_status_ok if the object is valid.
• amxd_status_function_not_implemented if called for the wrong reason