Data Model Objects

Collaboration diagram for Data Model Objects:

Modules
	Data Model Objects MIBs
	Event Methods
	RPC Methods
	Hierarchical Tree
	Parameters

Macros
#define	amxd_object_for_each(type, it, object)
	Helper macro for iterating object content. More...
#define	amxd_object_iterate(type, it, object)
	Helper macro for iterating object content. More...

Functions
amxd_status_t	amxd_object_new (amxd_object_t **object, const amxd_object_type_t type, const char *name)
	Data model object constructor function. More...
void	amxd_object_free (amxd_object_t **object)
	Data model object destructor function. More...
amxd_status_t	amxd_object_new_instance (amxd_object_t **object, amxd_object_t *templ, const char *name, uint32_t index, amxc_var_t *values)
	Data model object constructor function. More...
amxd_status_t	amxd_object_add_instance (amxd_object_t **object, amxd_object_t *templ, const char *name, uint32_t index, amxc_var_t *values)
	Data model object constructor function. More...
void	amxd_object_delete (amxd_object_t **object)
	Invokes the destroy handler(s) of the object. More...
const char *	amxd_object_get_name (const amxd_object_t *const object, const uint32_t flags)
	Get the name of the object (or index as a string for instance objects) More...
uint32_t	amxd_object_get_index (const amxd_object_t *const object)
	Get the index of an instance object. More...
static amxd_object_type_t	amxd_object_get_type (const amxd_object_t *const object)
	Returns the object type. More...
amxd_status_t	amxd_object_set_attr (amxd_object_t *const object, const amxd_oattr_id_t attr, const bool enable)
	Sets or unsets an object attribute. More...
amxd_status_t	amxd_object_set_attrs (amxd_object_t *const object, const uint32_t bitmask, bool enable)
	Sets or unsets object attributes using a bitmap. More...
uint32_t	amxd_object_get_attrs (const amxd_object_t *const object)
	Gets the set attributes of an object. More...
bool	amxd_object_is_attr_set (const amxd_object_t *const object, const amxd_oattr_id_t attr)
	Checks if an attribute is set. More...

Detailed Description

Macro Definition Documentation

amxd_object_for_each

#define amxd_object_for_each	(		type,
			it,
			object
	)

Value:

    for(amxc_llist_it_t* it = amxd_object_first_ ## type(object), \
        * _next = amxc_llist_it_get_next(it); \
        it; \
        it = _next, \
        _next = amxc_llist_it_get_next(it))

Helper macro for iterating object content.

This helper macro can iterator over:

• all parameters of an object, specify parameter as type
• all functions of an object, specify function as type
• all instances of an template object, specify instance as type
• all child objects of an object, specify child as type

The iterator should not be declared.

Using this macro it is allowed to remove (delete) the iterators containing data structure

The iterator can be converted to the correct type using amxc_container_of macro.

For parameters the iterator is a member of the amxd_param_t structure, for functions the iterator is a member of the amxd_function_t structure, for instances and child objects the iterator is a member of the amxd_object_t structure.

Note

This macro can not be nested. Use amxd_object_iterate if you need nested loops to iterate over the content of objects.

Parameters

type	can be one of [parameter, function, child, instance]
it	a linked list iterator
object	the object

Definition at line 113 of file amxd_object.h.

amxd_object_iterate

#define amxd_object_iterate	(		type,
			it,
			object
	)

Value:

    for(amxc_llist_it_t* it = amxd_object_first_ ## type(object); \
        it; \
        it = amxc_llist_it_get_next(it))

Helper macro for iterating object content.

This helper macro can iterator over:

• all parameters of an object, specify parameter as type
• all functions of an object, specify function as type
• all instances of an template object, specify instance as type
• all child objects of an object, specify child as type

The iterator should not be declared.

Warning

Do not delete the iterator or its containing data structure. If you want to be able to delete the current iterator (or its containing data structure), use the macro amxd_object_for_each

The iterator can be converted to the correct type using amxc_container_of macro. For parameters the iterator is a member of the amxd_param_t structure, for functions the iterator is a member of the amxd_function_t structure, for instances and child objects the iterator is a member of the amxd_object_t structure.

Parameters

type	can be one of [parameter, function, child, instance]
it	a linked list iterator
object	the object

Definition at line 149 of file amxd_object.h.

Function Documentation

amxd_object_add_instance()

amxd_status_t amxd_object_add_instance	(	amxd_object_t **	object,
		amxd_object_t *	templ,
		const char *	name,
		uint32_t	index,
		amxc_var_t *	values
	)

Data model object constructor function.

Creates a new instance of a template object and sets the values of the parameters if provided.

If the template contains key parameters, the values for these parameters must be provided.

This function calls amxd_object_new_instance to allocate memory for the object and to check if it can be created (unique name, index and key values)

If creation is successful, the values for the key parameters and other parameters are set in one go.

To be able to create a new object a valid name must be given or NULL. The name of each node (object) in the hierarchy MUST start with a letter or underscore, and subsequent characters MUST be letters, digits, underscores or hyphens.

The name and index (if given) must be unique in the context of the template object - no other instance can exist with the same name or index.

The instance inherits all attributes, all parameters (except template only parameters) and all functions (except template only functions) of the template object.

The newly created object will have as parent the template object.

To remove an instance use amxd_object_delete

Note

Adding an instance with this function will not generate events. If events must be sent automatically, the instance should be created with a transaction. Alternatively, it is possible to use functions amxd_object_send_add_inst or amxd_object_emit_add_inst to send the events.

Parameters

object	pointer to an object pointer. The address of the new allocated object is stored in this pointer.
templ	pointer to template object.
name	A valid object name or NULL. The name of each object in the hierarchy MUST start with a letter or underscore, and subsequent characters MUST be letters, digits, underscores or hyphens.'
index	A uinique index or 0
values	A variant containing a hash table with at least all the values for key parameters. These values will be used to set the parameter values.

Returns

amxd_status_ok when the object is created, or another status code when failed creating the object

Definition at line 301 of file amxd_action_object_add_inst.c.

                                                           {
    amxd_status_t status = amxd_status_unknown_error;
    amxc_var_t args;
    amxc_var_t* var_index = NULL;
    amxc_var_t retval;
 
    amxc_var_init(&args);
    amxc_var_init(&retval);
    when_null(templ, exit);
 
    if(instance != NULL) {
        *instance = NULL;
    }
 
    amxc_var_set_type(&args, AMXC_VAR_ID_HTABLE);
    amxc_var_set_key(&args, "parameters", values, AMXC_VAR_FLAG_COPY);
    amxc_var_add_key(uint32_t, &args, "access", amxd_dm_access_private);
    amxc_var_add_key(bool, &args, "set_read_only", true);
    amxc_var_add_key(uint32_t, &args, "index", index);
    amxc_var_add_key(cstring_t, &args, "name", name);
 
    status = amxd_dm_invoke_action(templ,
                                   NULL,
                                   action_object_add_inst,
                                   &args,
                                   &retval);
    when_failed(status, exit);
 
    var_index = amxc_var_get_path(&retval, "index", AMXC_VAR_FLAG_DEFAULT);
    index = amxc_var_dyncast(uint32_t, var_index);
 
    if(instance != NULL) {
        *instance = amxd_object_get_instance(templ, NULL, index);
    }
 
exit:
    amxc_var_clean(&args);
    amxc_var_clean(&retval);
    return status;
}

amxd_object_delete()

void amxd_object_delete

(

amxd_object_t **

object

)

Invokes the destroy handler(s) of the object.

This method doesn't remove the object from the data model.

To remove the object, including the subtree, and free all allocated memory use amxd_object_free

Note

Deleting an instance with this function will not generate events. If events must be sent automatically, the instance should be deleted with a transaction. Alternatively, it is possible to use functions amxd_object_send_del_inst or amxd_object_emit_del_inst to send the events.

Parameters

object

pointer to an object pointer.

Definition at line 80 of file amxd_action_object_destroy.c.

                                                {
    when_null(object, exit);
    when_null(*object, exit);
 
    amxd_dm_invoke_action(*object,
                          NULL,
                          action_object_destroy,
                          NULL,
                          NULL);
 
    *object = NULL;
 
exit:
    return;
}

amxd_object_free()

void amxd_object_free

(

amxd_object_t **

object

)

Data model object destructor function.

Frees all memory allocated for an object.

If the object was in a data model tree, it is removed from that tree.

If the object has childeren (or instances) all these are freed and removed as well.

Parameters

object

pointer to an object pointer.

Definition at line 153 of file amxd_object.c.

                                              {
    amxd_object_type_t object_type;
    amxd_param_t* counter = NULL;
 
    when_null(object, exit);
    when_null((*object), exit);
 
    object_type = amxd_object_get_type(*object);
    if((object_type == amxd_object_instance) || (object_type == amxd_object_template)) {
        counter = amxd_object_get_param_counter_by_counted_object(*object);
    }
 
    amxd_object_clean((*object));
 
    if(amxc_llist_is_empty(&(*object)->derived_objects)) {
        free((*object));
    }
 
    *object = NULL;
 
    when_null(counter, exit);
 
    if(object_type == amxd_object_instance) {
        amxd_param_counter_update(counter);
    } else if(object_type == amxd_object_template) {
        amxd_param_delete(&counter);
    }
 
exit:
    return;
}

amxd_object_get_attrs()

uint32_t amxd_object_get_attrs

(

const amxd_object_t *const

object

)

Gets the set attributes of an object.

This function returns the set attributes of an object as a bitmask. To verify if a certain attribute is set, use the macro IS_BIT_SET.

uint32_t attrs = amxd_object_get_attrs(object);
 
if(IS_BIT_SET(attrs, amxd_oattr_persistent)) {
    // do something
}

To verify that one single attribute is set the function amxd_object_is_attr_set can be used.

Parameters

object

the object pointer

Returns

Returns the attributes set on the object as a bitmask.

Definition at line 334 of file amxd_object.c.

                                                                  {
    uint32_t attributes = 0;
    when_null(object, exit);
 
    attributes |= object->attr.read_only << amxd_oattr_read_only;
    attributes |= object->attr.persistent << amxd_oattr_persistent;
    attributes |= object->attr.priv << amxd_oattr_private;
    attributes |= object->attr.prot << amxd_oattr_protected;
    attributes |= object->attr.locked << amxd_oattr_locked;
 
exit:
    return attributes;
}

amxd_object_get_index()

uint32_t amxd_object_get_index

(

const amxd_object_t *const

object

)

Get the index of an instance object.

This function returns the index of an instance object. For singletons or template objects this function will always return 0.

Parameters

object

the object pointer

Returns

Returns the index of an instance object or 0.

Definition at line 265 of file amxd_object.c.

                                                                  {
    return object == NULL ? 0 : object->index;
}

amxd_object_get_name()

const char* amxd_object_get_name	(	const amxd_object_t *const	object,
		const uint32_t	flags
	)

Get the name of the object (or index as a string for instance objects)

Depending on the flags given the name or index is returned for instance objects, for all other types of objects the flags are ignored

Parameters

object	the object pointer
flags	can be one of AMXD_OBJECT_NAMED or AMXD_OBJECT_INDEXED

Returns

Returns the name of the object or NULL.

Definition at line 239 of file amxd_object.c.

                                                       {
    const char* name = NULL;
 
    when_null(object, exit);
    if(object->type == amxd_object_instance) {
        if((flags & AMXD_OBJECT_INDEXED) == AMXD_OBJECT_INDEXED) {
            name = object->index_name;
        } else {
            name = object->name;
        }
    } else {
        name = object->name;
        if((name == NULL) && (object->derived_from.llist != NULL)) {
            amxd_object_t* super = amxc_container_of(object->derived_from.llist,
                                                     amxd_object_t,
                                                     derived_objects);
 
            name = amxd_object_get_name(super, AMXD_OBJECT_NAMED);
        }
    }
 
exit:
    return name;
}

amxd_object_get_type()

static amxd_object_type_t amxd_object_get_type ( const amxd_object_t *const  object )

inlinestatic

Returns the object type.

The type of a data model object can be:

• amxd_object_root: The root of the data model. (only one of this type in the data model tree)
• amxd_object_singleton
• amxd_object_template
• amxd_object_instance
• amxd_object_mib: a mib object can not be in the data model hierarchy is only used to extend objects

Parameters

object

the object pointer

Returns

Returns the object type.

Definition at line 586 of file amxd_object.h.

                                                                           {
    return object == NULL ? amxd_object_invalid : object->type;
}

amxd_object_is_attr_set()

bool amxd_object_is_attr_set	(	const amxd_object_t *const	object,
		const amxd_oattr_id_t	attr
	)

Checks if an attribute is set.

The following attribute identifiers can be checked

• amxd_oattr_read_only
• amxd_oattr_persistent
• amxd_oattr_private
• amxd_oattr_locked
• amxd_oattr_protected

Parameters

object	the object pointer
attr	the object attribute id

Returns

Returns true if attribute is set and false when unset

Definition at line 348 of file amxd_object.c.

                                                         {
    uint32_t flags = 0;
    bool retval = false;
    when_null(object, exit);
    when_true(attr < 0 || attr > amxd_oattr_max, exit);
 
    flags = amxd_object_get_attrs(object);
    retval = (flags & (1 << attr)) != 0 ? true : false;
 
exit:
    return retval;
}

amxd_object_new()

amxd_status_t amxd_object_new	(	amxd_object_t **	object,
		const amxd_object_type_t	type,
		const char *	name
	)

Data model object constructor function.

Allocates memory for a new data model object and initializes the object.

The following object types can be created with this function:

• singelton objects
• template objects
• mib objects

Instances of template objects must be created with the function amxd_object_new_instance or amxd_object_add_instance

To be able to create a new object a valid name must be given. The name of each node (object) in the hierarchy MUST start with a letter or underscore, and subsequent characters MUST be letters, digits, underscores or hyphens.

No attributes are set. Object attributes can be changed by using one of the following functions:

• amxd_object_set_attr
• amxd_object_set_attrs

The newly created object is not added to the data model tree automatically. You can add the new object in the data model by using the function amxd_object_add_object.

Use amxd_object_delete to remove the object and free all allocated memory.

Parameters

object	pointer to an object pointer. The address of the new allocated object is stored in this pointer.
type	the object type that needs to be created. this can be one of amxd_object_singleton, amxd_object_template, amxd_object_mib
name	A valid object name. The name of each object in the hierarchy MUST start with a letter or underscore, and subsequent characters MUST be letters, digits, underscores or hyphens.

Returns

amxd_status_ok when the object is created, or another status code when failed creating the object

Definition at line 185 of file amxd_object.c.

                                                {
    amxd_status_t retval = amxd_status_unknown_error;
    when_null(object, exit);
    when_true_status(!amxd_object_type_is_valid(type),
                     exit,
                     retval = amxd_status_invalid_type);
    when_true_status(!amxd_name_is_valid(name),
                     exit,
                     retval = amxd_status_invalid_name);
 
    *object = (amxd_object_t*) calloc(1, sizeof(amxd_object_t));
    when_null((*object), exit);
 
    retval = amxd_object_init(*object, type, name, NULL, NULL);
    when_failed(retval, exit);
 
exit:
    return retval;
}

amxd_object_new_instance()

amxd_status_t amxd_object_new_instance	(	amxd_object_t **	object,
		amxd_object_t *	templ,
		const char *	name,
		uint32_t	index,
		amxc_var_t *	values
	)

Data model object constructor function.

Creates a new instance of a template object. When passing a NULL pointer for the name, the name is the same as the index (but in string format). When passing 0 for the index. the next index is taken.

This function only allocates memory to store the object but will not assign values to the parameters. The parameter values passed to this function are only used to check if no other instance exists with the same values for the key parameters.

If creation is successful, the values for the key parameters and other parameters must still be set. Use amxd_object_add_instance to create an instance an fill the parameter values in one go.

To be able to create a new object a valid name must be given or NULL. The name of each node (object) in the hierarchy MUST start with a letter or underscore, and subsequent characters MUST be letters, digits, underscores or hyphens.

The name and index (if given) must be unique in the context of the template object - no other instance can exist with the same name or index.

The instance inherts all attributes, all parameters (except template only paramters) and all functions (except template only functions) of the template object .

The newly created object will have as parent the template object.

To remove an instance use amxd_object_delete

Parameters

object	pointer to an object pointer. The address of the new allocated object is stored in this pointer.
templ	pointer to template object.
name	A valid object name or NULL. The name of each object in the hierarchy MUST start with a letter or underscore, and subsequent characters MUST be letters, digits, underscores or hyphens.'
index	A uinique index or 0
values	A variant containing a hash table with at least all the values for key parameters. These are used to verify that the innstance is unique.

Returns

amxd_status_ok when the object is created, or another status code when failed creating the object

Definition at line 350 of file amxd_object_instance.c.

                                                           {
    amxd_status_t retval = amxd_status_unknown_error;
    amxc_var_t templ_params;
    amxc_var_t* tmp_values = NULL;
    amxc_var_t rv;
 
    amxc_var_init(&templ_params);
    amxc_var_init(&rv);
    when_null(object, exit);
    when_null(templ, exit);
    when_true_status(templ->type != amxd_object_template,
                     exit,
                     retval = amxd_status_invalid_type);
    when_true_status(values != NULL && amxc_var_type_of(values) != AMXC_VAR_ID_HTABLE,
                     exit,
                     retval = amxd_status_invalid_value);
    if(values == NULL) {
        amxc_var_new(&tmp_values);
        amxc_var_set_type(tmp_values, AMXC_VAR_ID_HTABLE);
    } else {
        tmp_values = values;
    }
    *object = NULL;
    retval = amxd_object_describe_key_params(templ, &templ_params, amxd_dm_access_private);
    when_failed(retval, exit);
    retval = amxd_object_instance_validate_id(templ, &name, index, &templ_params, tmp_values);
    when_failed(retval, exit);
    retval = amxd_object_instantiate(object, templ, name, index, &templ_params, tmp_values);
    when_failed(retval, exit);
    if(values == NULL) {
        retval = amxd_action_set_values((*object), amxd_dm_access_protected, true,
                                        tmp_values, &rv, true);
    }
 
exit:
    if(values == NULL) {
        amxc_var_delete(&tmp_values);
    }
    amxc_var_clean(&rv);
    amxc_var_clean(&templ_params);
    return retval;
}

amxd_object_set_attr()

amxd_status_t amxd_object_set_attr	(	amxd_object_t *const	object,
		const amxd_oattr_id_t	attr,
		const bool	enable
	)

Sets or unsets an object attribute.

The following attributes can be set - unset:

• amxd_oattr_read_only
• amxd_oattr_persistent
• amxd_oattr_private
• amxd_oattr_locked
• amxd_oattr_protected

Note

• Attributes of a locked object can not be changed
• It is not possible to add functions to a locked object

Parameters

object	the object pointer
attr	the object attribute id
enable	when true, sets the attribute, when false unsets the attribute

Returns

Returns amxd_status_ok when attributes is changed, any other when failed

Definition at line 269 of file amxd_object.c.

                                                      {
    amxd_status_t retval = amxd_status_unknown_error;
    uint32_t flags = 0;
    when_null(object, exit);
 
    when_true_status(object->type == amxd_object_mib,
                     exit,
                     retval = amxd_status_invalid_type);
 
    when_true_status(attr < 0 || attr > amxd_oattr_max,
                     exit,
                     retval = amxd_status_invalid_attr);
 
    when_true(amxd_object_is_attr_set(object, amxd_oattr_locked), exit);
 
    flags = amxd_object_get_attrs(object);
 
    if(enable) {
        flags |= SET_BIT(attr);
    } else {
        flags &= ~SET_BIT(attr);
    }
 
    amxd_object_set_attributes(object, flags);
    retval = amxd_status_ok;
 
exit:
    return retval;
}

amxd_object_set_attrs()

amxd_status_t amxd_object_set_attrs	(	amxd_object_t *const	object,
		const uint32_t	bitmask,
		bool	enable
	)

Sets or unsets object attributes using a bitmap.

The following attributes can be set - unset:

• amxd_oattr_read_only
• amxd_oattr_persistent
• amxd_oattr_private
• amxd_oattr_locked
• amxd_oattr_protected

Use the macro SET_BIT to transform the attribute id to a bit. The bits can be joined together using the bitwise or operator '|'

amxd_object_set_attrs(object,
                      SET_BIT(amxd_oattr_read_only) |
                      SET_BIT(amxd_oattr_persistent),
                      true);

When setting or unsetting one single attribute the function amxd_object_set_attr can be used.

Note

• Attributes of a locked object can not be changed
• It is not possible to add functions to a locked object

Parameters

object	the object pointer
bitmask	the object attribute bitmask
enable	when true, sets the attributes, when false unsets the attributes

Returns

Returns amxd_status_ok when attributes is changed, any other when failed

Definition at line 301 of file amxd_object.c.

                                                 {
    amxd_status_t retval = amxd_status_unknown_error;
    uint32_t flags = 0;
    uint32_t all = 0;
 
    when_null(object, exit);
    when_true_status(object->type == amxd_object_mib,
                     exit,
                     retval = amxd_status_invalid_type);
 
    for(int i = 0; i <= amxd_oattr_max; i++) {
        all |= SET_BIT(i);
    }
 
    when_true_status(bitmask > all, exit, retval = amxd_status_invalid_attr);
 
    flags = amxd_object_get_attrs(object);
 
    if(enable) {
        flags |= bitmask;
    } else {
        flags &= ~bitmask;
    }
 
    amxd_object_set_attributes(object, flags);
    retval = amxd_status_ok;
 
exit:
    return retval;
}