Parameters

Collaboration diagram for Parameters:

Macros
#define	amxd_object_set_value(type, object, name, value)    amxd_object_set_ ## type(object, name, value)
	Helper macro for setting a value. More...
#define	amxd_object_get_value(type, object, name, status)    amxd_object_get_ ## type(object, name, status)
	Helper macro for getting a value. More...

Functions
amxd_status_t	amxd_object_add_param (amxd_object_t *const object, amxd_param_t *const param)
	Adds a parameter definition to an object. More...
amxd_param_t *	amxd_object_get_param_def (const amxd_object_t *const object, const char *name)
	Gets a parameter definition from an object. More...
amxd_status_t	amxd_object_set_param (amxd_object_t *const object, const char *name, amxc_var_t *const value)
	Sets a value for a parameter in a data model object. More...
amxd_status_t	amxd_object_set_params (amxd_object_t *const object, amxc_var_t *const values)
	Sets multiple parameter values in a data model object. More...
amxd_status_t	amxd_object_get_param (amxd_object_t *const object, const char *name, amxc_var_t *const value)
	Gets a single parameter value. More...
const amxc_var_t *	amxd_object_get_param_value (const amxd_object_t *const object, const char *name)
	Gets the variant in which the parameter value is stored. More...
amxd_status_t	amxd_object_get_params (amxd_object_t *const object, amxc_var_t *const params, amxd_dm_access_t access)
	Gets all parameter values of an object. More...

Detailed Description

Macro Definition Documentation

amxd_object_get_value

#define amxd_object_get_value	(		type,
			object,
			name,
			status
	)		amxd_object_get_ ## type(object, name, status)

Helper macro for getting a value.

This helper macro gets a value, using a type indicator

Parameters

type	the data type that must be returned
object	pointer to a data model object
name	parameter name
status	optional pointer to a amxd_status_t or NULL

Definition at line 100 of file amxd_object_parameter.h.

amxd_object_set_value

#define amxd_object_set_value	(		type,
			object,
			name,
			value
	)		amxd_object_set_ ## type(object, name, value)

Helper macro for setting a value.

This helper macro sets a value for a certain parameter

Parameters

type	the data type, must be a valid parameter type, or must be convertable to a valid parameter type
object	pointer to a data model object
name	parameter name
value	the new value, must match the given type

Definition at line 85 of file amxd_object_parameter.h.

Function Documentation

amxd_object_add_param()

amxd_status_t amxd_object_add_param	(	amxd_object_t *const	object,
		amxd_param_t *const	param
	)

Adds a parameter definition to an object.

The parameter definition can be created using amxd_param_new.

Adding the parameter definition to an object fails when:

• The parameter definition was already added to an object
• The amxd_oattr_locked atrtribute was set on the object
• The parameter definition is a key parameter and the object is a mult-instance object with instances, is an instance object, is a singleton object, is a mib definition.
• The object contains already a parameter with the same name

When adding a parameter definition to a multi-instance object or an instance object and none of the following parameters attributes are set:

• amxd_pattr_instance
• amxd_pattr_template The amxd_pattr_instance attribute is set automatically.

Parameters

object	pointer to a data model object, the parameter definition is added to this object
param	pointer to the parameter definition

Returns

• amxd_status_ok: parameter definition is added to the data model object
• amxd_status_duplicate: parameter definition can not be added, another parameter exists with the same name
• amxd_status_invalid_attr: parameter can not be added because the object and parameter attributes do not match
• amxd_status_unknown_error: any other error

Definition at line 96 of file amxd_object_parameter.c.

                                                               {
    amxd_status_t retval = amxd_status_unknown_error;
    amxd_param_t* object_param = NULL;
    when_null(object, exit);
    when_null(param, exit);
    when_not_null(param->it.llist, exit);
 
    when_true(amxd_object_is_attr_set(object, amxd_oattr_locked), exit);
 
    retval = amxd_object_check_key_param(object, param);
    when_failed(retval, exit);
 
    amxc_llist_for_each(it, (&object->parameters)) {
        const char* object_param_name = NULL;
        const char* param_name = NULL;
        object_param = amxc_llist_it_get_data(it, amxd_param_t, it);
        object_param_name = amxd_param_get_name(object_param);
        param_name = amxd_param_get_name(param);
        if(strcmp(param_name, object_param_name) == 0) {
            retval = amxd_status_duplicate;
            goto exit;
        }
        object_param = NULL;
    }
 
    // parameters added to template object by default only work on
    // instances. This is a design descision.
    // For other behavior set the attributes before adding the parameter
    // to the object
    if((amxd_object_get_type(object) == amxd_object_template) ||
       (amxd_object_get_type(object) == amxd_object_instance)) {
        if((param->attr.instance == 0) && (param->attr.templ == 0)) {
            param->attr.instance = 1;
        }
    }
 
    if(amxd_object_get_type(object) == amxd_object_instance) {
        if((param->attr.templ == 1) && (param->attr.instance == 0)) {
            retval = amxd_status_invalid_attr;
            goto exit;
        }
    }
 
    amxc_llist_append(&object->parameters, &param->it);
 
exit:
    return retval;
}

amxd_object_get_param()

amxd_status_t amxd_object_get_param	(	amxd_object_t *const	object,
		const char *	name,
		amxc_var_t *const	value
	)

Gets a single parameter value.

This function invokes an action_object_read and can read private and protected parameters.

The default implementation of the action_object_read will fetch the real value of the paranmeter.

The action_object_read implementation can be overriden.

As an alternative to get a single parameter value of an object the macro amxd_object_get_value can be used.

Parameters

object	pointer to a data model object
name	the name of the parameter
value	an initialized variant, the value of the parameter will be copied in this variant.

Returns

amxd_status_ok when the new value is set correctly.

Definition at line 252 of file amxd_object_parameter.c.

                                                             {
    amxd_status_t retval = amxd_status_unknown_error;
    amxc_var_t args;
    amxc_var_t* params = NULL;
    amxc_var_t params_value;
    amxd_param_t* def = NULL;
 
    amxc_var_init(&args);
    amxc_var_init(&params_value);
    when_null(object, exit);
    when_null(value, exit);
    when_str_empty(name, exit);
 
    def = amxd_object_get_param_def(object, name);
    if(def != NULL) {
        if(!amxd_param_has_action(def, action_param_read)) {
            if(!amxd_object_has_action(object, action_object_read)) {
                amxc_var_copy(value, &def->value);
                retval = amxd_status_ok;
                goto exit;
            }
        }
    }
 
    amxc_var_set_type(&args, AMXC_VAR_ID_HTABLE);
    amxc_var_add_key(uint32_t, &args, "access", amxd_dm_access_private);
    params = amxc_var_add_key(amxc_llist_t, &args, "parameters", NULL);
    amxc_var_add(cstring_t, params, name);
    retval = amxd_dm_invoke_action(object,
                                   NULL,
                                   action_object_read,
                                   &args,
                                   &params_value);
    if(retval == amxd_status_ok) {
        amxc_var_t* param_val = amxc_var_get_path(&params_value,
                                                  name,
                                                  AMXC_VAR_FLAG_DEFAULT);
        when_null_status(param_val, exit, retval = amxd_status_parameter_not_found);
        amxc_var_copy(value, param_val);
    }
 
exit:
    amxc_var_clean(&params_value);
    amxc_var_clean(&args);
    return retval;
}

amxd_object_get_param_def()

amxd_param_t* amxd_object_get_param_def	(	const amxd_object_t *const	object,
		const char *	name
	)

Gets a parameter definition from an object.

Parameters

object	pointer to a data model object
name	name of the parameter

Returns

a pointer to a parameter definition or NULL if no parameter definition is found for the given name.

Definition at line 146 of file amxd_object_parameter.c.

                                                          {
    amxd_param_t* param = NULL;
    amxd_path_t param_path;
    amxd_object_t* real_obj = (amxd_object_t*) object;
    const char* rel_path = NULL;
 
    amxd_path_init(&param_path, name);
 
    when_null(object, exit);
    when_str_empty(name, exit);
    when_true(object->type == amxd_object_root, exit);
 
    rel_path = amxd_path_get(&param_path, AMXD_OBJECT_TERMINATE);
    real_obj = amxd_object_findf(real_obj, "%s", rel_path);
    when_null(real_obj, exit);
 
    amxc_llist_for_each(it, (&real_obj->parameters)) {
        const char* param_name = NULL;
        param = amxc_llist_it_get_data(it, amxd_param_t, it);
        param_name = amxd_param_get_name(param);
        if(strcmp(param_name, amxd_path_get_param(&param_path)) == 0) {
            break;
        }
        param = NULL;
    }
 
exit:
    amxd_path_clean(&param_path);
    return param;
}

amxd_object_get_param_value()

const amxc_var_t* amxd_object_get_param_value	(	const amxd_object_t *const	object,
		const char *	name
	)

Gets the variant in which the parameter value is stored.

This function will return the pointer to the amxc_var_t structure in which the value of the parameter is stored.

Parameters

object	pointer to a data model object
name	the name of the parameter

Returns

The pointer to the variant containing the parameters value or NULL if the object doesn't contain a parameter with the given name.

Definition at line 301 of file amxd_object_parameter.c.

                                                                {
    amxc_var_t* value = NULL;
    amxd_param_t* param = amxd_object_get_param_def(object, name);
    if(param != NULL) {
        value = &param->value;
    }
 
    return value;
}

amxd_object_get_params()

amxd_status_t amxd_object_get_params	(	amxd_object_t *const	object,
		amxc_var_t *const	params,
		amxd_dm_access_t	access
	)

Gets all parameter values of an object.

This function invokes an action_object_read and can read private and protected parameters, depending on the provided access value.

The default implementation of the action_object_read will fetch the real value of the paranmeters.

The action_object_read implementation can be overriden.

A provided variant will be initialized to a variant containing a hash table. For each parameter a key - value pair is added, The key is the parameter name and the value is the parameter value. The type is matching the parameter type.

Using the access value, it is possible to filter out some parameters. When providing amxd_dm_access_public, no private or protected parameters are returned, when using amxd_dm_access_protected no private parameters are returned.

Parameters

object	pointer to a data model object
params	an initialized variant, the variant will be initialized to the hash table type, the value of the parameters will be copied in this hash table.
access	can be set to amxd_dm_access_public, amxd_dm_access_protected, or amxd_dm_access_private

Returns

amxd_status_ok when the new value is set correctly.

Definition at line 314 of file amxd_action_object_read.c.

                                                              {
    amxd_status_t retval = amxd_status_unknown_error;
    amxc_var_t args;
 
    amxc_var_init(&args);
    when_null(object, exit);
    when_null(params, exit);
 
    amxc_var_set_type(&args, AMXC_VAR_ID_HTABLE);
    amxc_var_add_key(uint32_t, &args, "access", access);
    retval = amxd_dm_invoke_action(object,
                                   NULL,
                                   action_object_read,
                                   &args,
                                   params);
 
exit:
    amxc_var_clean(&args);
    return retval;
}

amxd_object_set_param()

amxd_status_t amxd_object_set_param	(	amxd_object_t *const	object,
		const char *	name,
		amxc_var_t *const	value
	)

Sets a value for a parameter in a data model object.

When the type of the new value doesn't match the type of the parameter definition, the new value is converted to the type of the parameter.

This function invokes an action_object_write and can change read-only parameters or private and protected parameters.

The default implementation of the action_object_write will set the new value if possible. The following sets are not allowed and will fail:

• set a value of an instance parameter on a multi-instance object
• set a value of a template parameter on a instance object.

The new parameter value is also validated, the action_param_validate is invoked before applying the value to the parameter. The set fails if the provided value is not valid for the parameter.

The behavior of this function depends on the implementation of

• action action_object_write for the given object
• action action_param_validate for the given parameter definition

Note

No object validation is done, it is the responsibility of the caller of this function to check if the object is valid after setting the value.

As an alternative to set a single parameter value of an object the macro amxd_object_set_value can be used.

Parameters

object	pointer to a data model object
name	name of the parameter
value	the new value

Returns

amxd_status_ok when the new value is set correctly.

Definition at line 221 of file amxd_object_parameter.c.

                                                             {
    amxd_status_t status = amxd_status_unknown_error;
    amxc_var_t* params = NULL;
    amxc_var_t args;
    amxc_var_t retval;
 
    amxc_var_init(&args);
    amxc_var_init(&retval);
    when_null(object, exit);
    when_null(value, exit);
    when_str_empty(name, exit);
 
    amxc_var_set_type(&args, AMXC_VAR_ID_HTABLE);
    params = amxc_var_add_key(amxc_htable_t, &args, "parameters", NULL);
    amxc_var_set_key(params, name, value, 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);
    status = amxd_dm_invoke_action(object,
                                   NULL,
                                   action_object_write,
                                   &args,
                                   &retval);
 
exit:
    amxc_var_clean(&retval);
    amxc_var_clean(&args);
    return status;
}

amxd_object_set_params()

amxd_status_t amxd_object_set_params	(	amxd_object_t *const	object,
		amxc_var_t *const	values
	)

Sets multiple parameter values in a data model object.

The behavior of this function is the same as amxd_object_set_param. The only differences is that the value arguments is a variant containing a hash table where the keys are considered parameter names.

When the object is a template object, it is possible to pass for each instance or some instances a separate hash table as value in the top level table, the key must be the name of the instance.

When a parameter or instance is not found the function fails.

Parameters

object	pointer to a data model object
values	a variant containing a hash table where the keys are the parameter names and the values the new values for the parameters.

Returns

amxd_status_ok when the new value is set correctly.

Definition at line 270 of file amxd_action_object_write.c.

                                                               {
 
    amxd_status_t status = amxd_status_unknown_error;
    amxc_var_t args;
 
    amxc_var_init(&args);
    when_null(object, exit);
    when_true(amxc_var_is_null(values) ||
              amxc_var_type_of(values) != AMXC_VAR_ID_HTABLE,
              exit);
 
    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);
    status = amxd_dm_invoke_action(object,
                                   NULL,
                                   action_object_write,
                                   &args,
                                   NULL);
 
exit:
    amxc_var_clean(&args);
    return status;
}