Data Model Operators

Functions
int	amxb_call (amxb_bus_ctx_t *const bus_ctx, const char *object, const char *method, amxc_var_t *args, amxc_var_t *ret, int timeout)
	Invokes a data model function. More...
amxb_request_t *	amxb_async_call (amxb_bus_ctx_t *const bus_ctx, const char *object, const char *method, amxc_var_t *args, amxb_be_done_cb_fn_t done_fn, void *priv)
	Invokes a data model function. More...
int	amxb_get (amxb_bus_ctx_t *const bus_ctx, const char *object, int32_t depth, amxc_var_t *ret, int timeout)
	Fetches one or more objects or a single parameter. More...
int	amxb_get_filtered (amxb_bus_ctx_t *const bus_ctx, const char *object, const char *filter, int32_t depth, amxc_var_t *ret, int timeout)
	Fetches one or more objects and their parameters that are matching a filter. More...
int	amxb_get_multiple (amxb_bus_ctx_t *const bus_ctx, amxc_var_t *req_paths, int32_t depth, amxc_var_t *ret, int timeout)
	Fetches one or more (root) objects or multiple parameters. More...
int	amxb_set (amxb_bus_ctx_t *const bus_ctx, const char *object, amxc_var_t *values, amxc_var_t *ret, int timeout)
	Sets parameter values of one single object or of multiple instance objects. More...
int	amxb_set_multiple (amxb_bus_ctx_t *const bus_ctx, uint32_t flags, amxc_var_t *req_paths, amxc_var_t *ret, int timeout)
	Sets parameter values for multiple objects (request paths) More...
int	amxb_add (amxb_bus_ctx_t *const bus_ctx, const char *object, uint32_t index, const char *name, amxc_var_t *values, amxc_var_t *ret, int timeout)
	Adds an instance to a multi-instance object. More...
int	amxb_del (amxb_bus_ctx_t *const bus_ctx, const char *object, uint32_t index, const char *name, amxc_var_t *ret, int timeout)
	Deletes one or more instances of a multi-instance object. More...
int	amxb_get_supported (amxb_bus_ctx_t *const bus_ctx, const char *object, uint32_t flags, amxc_var_t *ret, int timeout)
	Gets the supported data model. More...
int	amxb_describe (amxb_bus_ctx_t *const bus_ctx, const char *object, uint32_t flags, amxc_var_t *ret, int timeout)
	Describes an object. More...
int	amxb_list (amxb_bus_ctx_t *const bus_ctx, const char *object, uint32_t flags, amxb_be_cb_fn_t fn, void *priv)
	List the service elements/nodes of an object. More...
int	amxb_get_instances (amxb_bus_ctx_t *const bus_ctx, const char *search_path, int32_t depth, amxc_var_t *ret, int timeout)
	Fetches the instances and the unique keys of a multi-instance object. More...

Detailed Description

Function Documentation

amxb_add()

int amxb_add	(	amxb_bus_ctx_t *const	bus_ctx,
		const char *	object,
		uint32_t	index,
		const char *	name,
		amxc_var_t *	values,
		amxc_var_t *	ret,
		int	timeout
	)

Adds an instance to a multi-instance object.

Using this method, an instance can be created and the parameters values of that instance can be set.

It is not possible to create an instance for a read-only multi instance object.

It is not possible to set the value of read-only parameters using this function.

This function supports following paths:

• object path - must end with a "."

The parameter values must be passed as a variant containing a hash-table where each key is a parameter name and the value is the value for that parameter.

It is possible to choose the index (instance identifier) of the new instance using the index argument. The index provided must not be in use, otherwise the creation of the instance fails. When specifying 0 as the index, the next available index will be chosen. The automatic instance numbering never re-uses an already used index, even if the instance that was using the index has been deleted.

Optionally a name can be specified for the instance. When the multi-instance object has an "Alias" parameter that is defined as a "unique key", the name is used as the value for the "Alias" parameter. When no name needs to be set a NULL pointer can be passed.

When the multi-instance object has "key" parameters the values of these parameters must be given using the "values" argument, except for the "Alias" parameter if a name is provided. The values of "key" parameters can only be set when the instance is created, and are immutable.

Values of non key parameters are optional and can be set later with amxb_set function.

The return value of an add is always an Ambiorix variant and will contain the newly created instance and all its key parameters.

Example of a return variant:

[
    {
        index = 5,
        name = "5",
        object = "Phonebook.Contact.5.",
        parameters = {
        },
        path = "Phonebook.Contact.5."
    }
]

Parameters

bus_ctx	The bus context (or connection)
object	Full multi-instance object path
index	the index of the instance set to 0 to assign an index automatically
name	the name of the instance, or when an Alias parameter exists, the value for the Alias. The name can be NULL.
values	variant hash-table containing the parameter values, can be NULL when key parameters are defined, at least the key parameters must be set and present in the hash-table.
ret	will contain the created object, its key parameters and exta information
timeout	in seconds

Returns

amxd_status_ok_OK when successful, any other value indicates an error.

Definition at line 115 of file amxb_ba_op_add.c.

                          {
    int retval = amxd_status_unknown_error;
    const amxb_be_funcs_t* fns = NULL;
    bool lobject = false;
    amxd_path_t path;
    char* fixed = NULL;
    const char* rel_path = NULL;
 
    amxd_path_init(&path, NULL);
    when_null(bus_ctx, exit);
    when_null(bus_ctx->bus_ctx, exit);
 
    amxd_path_setf(&path, true, "%s", object);
 
    while(amxd_path_get_type(&path) == amxd_path_reference) {
        retval = amxb_follow_reference(bus_ctx, &path, timeout);
        when_failed(retval, exit);
    }
 
    fixed = amxd_path_get_fixed_part(&path, true);
    rel_path = amxd_path_get(&path, AMXD_OBJECT_TERMINATE);
 
    lobject = amxb_is_local_object(bus_ctx, fixed);
    fns = bus_ctx->bus_fn;
 
    if(amxc_var_is_null(values)) {
        amxc_var_set_type(values, AMXC_VAR_ID_HTABLE);
    }
 
    if(lobject || !amxb_is_valid_be_func(fns, add, fns->add)) {
        retval = amxb_invoke_add(bus_ctx, fixed, rel_path, index,
                                 name, values, ret, timeout);
    } else {
        retval = fns->add(bus_ctx->bus_ctx, fixed, rel_path, index,
                          name, values, bus_ctx->access, ret, timeout);
    }
 
exit:
    free(fixed);
    amxd_path_clean(&path);
    return retval;
}

amxb_async_call()

amxb_request_t* amxb_async_call	(	amxb_bus_ctx_t *const	bus_ctx,
		const char *	object,
		const char *	method,
		amxc_var_t *	args,
		amxb_be_done_cb_fn_t	done_fn,
		void *	priv
	)

Invokes a data model function.

Calls a data model method. A data model method is a function that is exposed in the data model in a specific object.

The arguments passed must be in a amxc variant of type AMXC_VAR_ID_HTABLE. The order of the arguments is not important.

This function makes uses of amxb_new_invoke and amxb_async_invoke.

When the method call fails, the done function is called with NULL as amxb_request_t and the status will be the failure status.

The returned amxb_request_t pointer can be used with amxb_wait_for_request to wait until the method call is finished.

The returned pointer must be freed with amxb_close_request. After calling amxb_close_request, the callback function will not be called anymore.

Parameters

bus_ctx	The bus context (or connection)
object	object path to the object that contains the function, object paths must end with a "."
method	name of the function being called
args	the function arguments in a amxc variant htable type
done_fn	a done callback function
priv	private data that will be passed to the callback function (optional, can be NULL)

Returns

returns an amxb_request_t pointer or NULL when failed to call the method.

Definition at line 98 of file amxb_ba_op_call.c.

                                            {
    amxb_invoke_t* invoke_ctx = NULL;
    int retval = amxd_status_unknown_error;
    amxb_request_t* req = NULL;
 
    retval = amxb_new_invoke(&invoke_ctx, bus_ctx, object, NULL, method);
    when_failed(retval, exit);
    amxb_async_invoke(invoke_ctx, args, NULL, done_fn, priv, &req);
 
exit:
    amxb_free_invoke(&invoke_ctx);
    return req;
}

amxb_call()

int amxb_call	(	amxb_bus_ctx_t *const	bus_ctx,
		const char *	object,
		const char *	method,
		amxc_var_t *	args,
		amxc_var_t *	ret,
		int	timeout
	)

Invokes a data model function.

Calls a data model method. A data model method is a function that is exposed in the data model in a specific object.

The arguments passed must be in a amxc variant of type AMXC_VAR_ID_HTABLE. The order of the arguments is not important.

This function makes uses of amxb_new_invoke and Remote Function Invoke.

If no response is received before the timeout expires, this function will return an error, but it is possible that the RPC method is still busy.

Parameters

bus_ctx	The bus context (or connection)
object	object path to the object that contains the function, object paths must end with a "."
method	name of the function being called
args	the function arguments in a amxc variant htable type
ret	will contain the return value(s) and/or the out arguments
timeout	in seconds

Returns

amxd_status_ok remote function has completed successful

Definition at line 78 of file amxb_ba_op_call.c.

                           {
 
    amxb_invoke_t* invoke_ctx = NULL;
    int retval = amxd_status_unknown_error;
 
    retval = amxb_new_invoke(&invoke_ctx, bus_ctx, object, NULL, method);
    when_failed(retval, exit);
    retval = amxb_invoke(invoke_ctx, args, ret, NULL, NULL, timeout);
    when_failed(retval, exit);
 
exit:
    amxb_free_invoke(&invoke_ctx);
    return retval;
}

amxb_del()

int amxb_del	(	amxb_bus_ctx_t *const	bus_ctx,
		const char *	object,
		uint32_t	index,
		const char *	name,
		amxc_var_t *	ret,
		int	timeout
	)

Deletes one or more instances of a multi-instance object.

Using this method, one or more instances can be deleted from a multi-instance object.

It is not possible to delete instances from a read-only multi instance object.

This function supports following paths:

• object path - must end with a "."
• search path - must end with a "." or "*"

The provided paths must either result or point to:

• a multi-instance object (should be exactly one)
• an instance (can be more then one)

When the given path is a multi-instance object, an index or name of the instance that will be deleted must be given. If both an index (instance identifier) and a name are given, the index takes precedence.

When the given path is an instance path, index and name arguments are ignored.

When the given path is a search path where multiple-instances match, all of the matching instances will be deleted and the index and name arguments are ignored.

The full list of deleted objects is returned in a variant containing an array of all deleted object paths, this includes the full tree underneath the delete instance(s).

Parameters

bus_ctx	The bus context (or connection)
object	Full object path or search path
index	the index of the instance that will be deleted
name	the name of the instance that will be deleted
ret	will contain a list of all deleted objects
timeout	in seconds

Returns

amxd_status_ok when successful, any other value indicates an error.

Definition at line 117 of file amxb_ba_op_del.c.

                          {
    int retval = amxd_status_unknown_error;
    const amxb_be_funcs_t* fns = NULL;
    bool lobject = false;
    amxd_path_t path;
    char* fixed = NULL;
    const char* rel_path = NULL;
 
    amxd_path_init(&path, NULL);
    when_null(bus_ctx, exit);
    when_null(bus_ctx->bus_ctx, exit);
 
    amxd_path_setf(&path, true, "%s", object);
 
    while(amxd_path_get_type(&path) == amxd_path_reference) {
        retval = amxb_follow_reference(bus_ctx, &path, timeout);
        when_failed(retval, exit);
    }
 
    fixed = amxd_path_get_fixed_part(&path, true);
    rel_path = amxd_path_get(&path, AMXD_OBJECT_TERMINATE);
 
    lobject = amxb_is_local_object(bus_ctx, fixed);
    fns = bus_ctx->bus_fn;
 
    if(lobject || !amxb_is_valid_be_func(fns, del, fns->del)) {
        retval = amxb_invoke_del(bus_ctx, fixed, rel_path, index,
                                 name, ret, timeout);
    } else {
        retval = fns->del(bus_ctx->bus_ctx, fixed, rel_path, index,
                          name, bus_ctx->access, ret, timeout);
    }
 
exit:
    free(fixed);
    amxd_path_clean(&path);
    return retval;
}

amxb_describe()

int amxb_describe	(	amxb_bus_ctx_t *const	bus_ctx,
		const char *	object,
		uint32_t	flags,
		amxc_var_t *	ret,
		int	timeout
	)

Describes an object.

This function is mainly used for data model introspection. Besides the values of the parameters, more information can be obtained.

Information included in the returned data structure is:

• parameter, object, function attributes
• index and name - for instance objects
• indexed and named object path (path and object fields)
• type information for parameters, objects and functions
• function names, and all function arguments

Use this function for introspection purposes.

Using the flags argument, the requested information can be manipulated:

• AMXB_FLAG_FUNCTIONS - include all RPC methods of the object
• AMXB_FLAG_PARAMETERS - include all parameters of the object
• AMXB_FLAG_EVENTS - include all events of the object
• AMXB_FLAG_OBJECTS - include the names of child objects
• AMXB_FLAG_INSTANCES - include index and name of instance objects
• AMXB_FLAG_EXISTS - return true if the object exists, when this flag is set all others are ignored.

All other flags will be ignored.

The return value of this function is always an Ambiorix variant and will contain the requested information. The return data is stored in the ret argument.

Example of a return variant:

[
    {
        attributes = {
            locked = false,
            persistent = false
            private = false,
            protected = false,
            read-only = false,
        },
        index = 1,
        name = "1",
        object = "Phonebook.Contact.1.E-Mail.",
        objects = [
        ],
        parameters = {
            E-Mail = {
                attributes = {
                    counter = false,
                    instance = true,
                    key = false
                    persistent = false,
                    private = false,
                    protected = false,
                    read-only = false,
                    template = false,
                    unique = false,
                    volatile = false,
                },
                name = "E-Mail",
                type_id = 1,
                type_name = "cstring_t"
                value = "john.d@ambiorix.com",
            }
        }
        path = "Phonebook.Contact.1.E-Mail.",
        type_id = 3,
        type_name = "instance",
    }
]

Parameters

bus_ctx	The bus context (or connection)
object	The object path
flags	bitmap field of or'ed flags
ret	will contain the requested information
timeout	in seconds

Returns

amxd_status_ok when successful, any other value indicates an error.

Definition at line 114 of file amxb_ba_op_describe.c.

                               {
    int retval = amxd_status_unknown_error;
    const amxb_be_funcs_t* fns = NULL;
    bool lobject = false;
    amxd_path_t path;
    char* fixed = NULL;
    const char* rel_path = NULL;
 
    amxd_path_init(&path, NULL);
    when_null(bus_ctx, exit);
    when_null(bus_ctx->bus_ctx, exit);
 
    amxd_path_setf(&path, true, "%s", object);
    fixed = amxd_path_get_fixed_part(&path, true);
    rel_path = amxd_path_get(&path, AMXD_OBJECT_TERMINATE);
 
    lobject = amxb_is_local_object(bus_ctx, fixed);
    fns = bus_ctx->bus_fn;
 
    if(lobject || !amxb_is_valid_be_func(fns, describe, fns->describe)) {
        retval = amxb_invoke_describe(bus_ctx, fixed, rel_path,
                                      flags, ret, timeout);
    } else {
        retval = fns->describe(bus_ctx->bus_ctx, fixed, rel_path,
                               flags, bus_ctx->access, ret, timeout);
    }
 
exit:
    free(fixed);
    amxd_path_clean(&path);
    return retval;
}

amxb_get()

int amxb_get	(	amxb_bus_ctx_t *const	bus_ctx,
		const char *	object,
		int32_t	depth,
		amxc_var_t *	ret,
		int	timeout
	)

Fetches one or more objects or a single parameter.

Using this method, the parameter values of an object can be retrieved.

It is possible to get the parameters from multiple objects at once or to get one single parameter of one or more objects.

This function supports following paths:

• object path - must end with a "."
• search path - can contain expressions or wildcard to filter out instances. they can end with a parameter name, a "." or a "*"
• parameter path - must end with a parameter name (no "." at the end)

In a search path a wildcard "*" or an expression can be put where an instance identifier (instance index) is in an object path.

Examples of valid search paths:

"Phonebook.Contact.*."
"Phonebook.Contact.*"
"Phonebook.Contact.[FirstName == 'Jane']."
"Phonebook.Contact.*.FirstName"
"Device.IP.Interface.[Type=='Normal'].IPv4Address.[AddressingType=='Static'].IPAddress"
"Device.IP.Interface.[Type=='Normal' && Stats.ErrorsSent>0].IPv4Address.[AddressingType=='Static'].IPAddress"

The return value of a get is always an Ambiorix variant:

[
   {
       Phonebook.Contact.1. = {
           FirstName = "John"
           LastName = "Doe",
       },
       Phonebook.Contact.2. = {
           FirstName = "Jane"
           LastName = "Doe",
       },
       Phonebook.Contact.3. = {
           FirstName = "Eva"
           LastName = "Elliott",
       }
   }
]

Parameters

bus_ctx	The bus context (or connection)
object	Full object path, search path or parameter path
depth	relative depth, if not zero it indicates how many levels of child objects are returned
ret	will contain the objects and their parameters
timeout	in seconds

Returns

amxd_status_ok when successful, any other value indicates an error.

Definition at line 114 of file amxb_ba_op_get.c.

                          {
    return amxb_get_filtered(bus_ctx, search_path, NULL, depth, ret, timeout);
}

amxb_get_filtered()

int amxb_get_filtered	(	amxb_bus_ctx_t *const	bus_ctx,
		const char *	object,
		const char *	filter,
		int32_t	depth,
		amxc_var_t *	ret,
		int	timeout
	)

Fetches one or more objects and their parameters that are matching a filter.

Using this method, the parameter values of an object can be retrieved. This function works exactly the same as amxb_get, but can filter the parameters of an object on the meta-data.

For more details see amxb_get.

The meta-data of the parameters can be retrieved using amxb_describe. If a filter is provided, the filter will be evaluated on the meta-data of the parameters, only matching parameters will be available in the result data.

Example of parameter meta-data:

attributes = {
     counter = 1,
     instance = 0,
     key = 0,
     mutable = 0,
     persistent = 0,
     private = 0,
     protected = 0,
     read-only = 1,
     template = 0,
     unique = 0,
     volatile = 0
},
flags = [
],
name = "NumberOfHistoryEntries",
type_id = 8,
type_name = "uint32_t",
value = 1

Example of a filter:

"attributes.persistent==true || 'usersetting' in flags"

The above filter example will only return parameters that have the persistent attribute set or have the flag "usersetting", all other parameters will be filtered out.

If no filter (NULL or empty string) is provided, this function will return exactly the same as amxb_get.

Warning

It is possible that a bus/protocol backend doesn't have support for filtering parameters. When this functionality is not available by the used backend, the filter is ignored and this function will return exactly the same as amxb_get.

Parameters

bus_ctx	The bus context (or connection)
object	Full object path, search path or parameter path
filter	Logical filter expression, only matching parameters are returned.
depth	relative depth, if not zero it indicates how many levels of child objects are returned
ret	will contain the objects and their parameters
timeout	in seconds

Returns

amxd_status_ok when successful, any other value indicates an error.

Definition at line 122 of file amxb_ba_op_get.c.

                                   {
    int retval = amxd_status_unknown_error;
    const amxb_be_funcs_t* fns = NULL;
    amxd_path_t path;
    bool islocal = false;
    char* object = NULL;
    const char* param = NULL;
    amxc_string_t temp;
 
    amxc_string_init(&temp, 0);
    amxd_path_init(&path, search_path);
    when_null(bus_ctx, exit);
    when_null(bus_ctx->bus_ctx, exit);
 
    while(amxd_path_get_type(&path) == amxd_path_reference) {
        retval = amxb_follow_reference(bus_ctx, &path, timeout);
        when_failed(retval, exit);
    }
 
    object = amxd_path_get_fixed_part(&path, true);
    if((object == NULL) || (strcmp(object, ".") == 0)) {
        retval = amxd_status_object_not_found;
        goto exit;
    }
    search_path = amxd_path_get(&path, AMXD_OBJECT_TERMINATE);
    search_path = search_path == NULL ? "" : search_path;
    param = amxd_path_get_param(&path);
    islocal = amxb_is_local_object(bus_ctx, object);
    fns = bus_ctx->bus_fn;
 
    if(param != NULL) {
        amxc_string_setf(&temp, "%s%s", search_path, param);
        search_path = amxc_string_get(&temp, 0);
    }
 
    if(islocal ||
       (!amxb_is_valid_be_func(fns, get, fns->get) &&
        !amxb_is_valid_be_func(fns, get, fns->get_filtered))) {
        retval = amxb_invoke_get(bus_ctx, object, search_path, filter,
                                 depth, ret, timeout);
    } else {
        if(amxb_is_valid_be_func(fns, get, fns->get_filtered)) {
            retval = fns->get_filtered(bus_ctx->bus_ctx, object, search_path, filter,
                                       depth, bus_ctx->access, ret, timeout);
 
        } else if(amxb_is_valid_be_func(fns, get, fns->get)) {
            retval = fns->get(bus_ctx->bus_ctx, object, search_path,
                              depth, bus_ctx->access, ret, timeout);
        }
    }
 
    if(retval == amxd_status_invalid_path) {
        retval = amxd_status_object_not_found;
    }
 
exit:
    amxc_string_clean(&temp);
    free(object);
    amxd_path_clean(&path);
    return retval;
}

amxb_get_instances()

int amxb_get_instances	(	amxb_bus_ctx_t *const	bus_ctx,
		const char *	search_path,
		int32_t	depth,
		amxc_var_t *	ret,
		int	timeout
	)

Fetches the instances and the unique keys of a multi-instance object.

Using this method, the instances of a multi-instance object and their unique keys can be retrieved.

It is possible to get the instances and keys from child objects of the provided multi-instance object as well by specifying a depth larger than 0.

This function supports following paths:

• object path - must end with a "." and must point to a multi-instance object
• search path - can contain expressions or wildcard to filter out instances, but the expression must resolve to one or several multi-instance objects to get a non-empty result

In a search path a wildcard "*" or an expression can be put where an instance identifier (instance index) is in an object path.

Examples of valid search paths:

"Phonebook.Contact.*.PhoneNumber."
"Phonebook.Contact.[FirstName == 'Jane'].PhoneNumber."

The return value of a get instances is always an Ambiorix variant:

[
  {
    "Phonebook.Contact.1.E-Mail.1.": {
    },
    "Phonebook.Contact.1.": {
      "FirstName": "Jane"
    },
    "Phonebook.Contact.1.PhoneNumber.1.": {
    }
  }
]

In the above example, the FirstName parameter was a unique key parameter

Parameters

bus_ctx	The bus context (or connection)
object	Multi-instance object path or search path
depth	relative depth, if not zero it indicates for how many levels the child instances are returned
ret	will contain the objects and their keys
timeout	in seconds

Returns

amxd_status_ok when successful, any other value indicates an error.

Definition at line 121 of file amxb_ba_op_get_instances.c.

                                    {
    int retval = amxd_status_unknown_error;
    const amxb_be_funcs_t* fns = NULL;
    amxd_path_t path;
    bool islocal = false;
    char* object = NULL;
    const char* param = NULL;
    amxc_string_t temp;
 
    amxc_string_init(&temp, 0);
    amxd_path_init(&path, search_path);
    when_null(bus_ctx, exit);
    when_null(bus_ctx->bus_ctx, exit);
 
    object = amxd_path_get_fixed_part(&path, true);
    if((object == NULL) || (strcmp(object, ".") == 0)) {
        retval = amxd_status_object_not_found;
        goto exit;
    }
    search_path = amxd_path_get(&path, AMXD_OBJECT_TERMINATE);
    search_path = search_path == NULL ? "" : search_path;
    param = amxd_path_get_param(&path);
    islocal = amxb_is_local_object(bus_ctx, object);
    fns = bus_ctx->bus_fn;
 
    if(param != NULL) {
        amxc_string_setf(&temp, "%s%s", search_path, param);
        search_path = amxc_string_get(&temp, 0);
    }
 
    if(islocal || !amxb_is_valid_be_func(fns, get, fns->get_instances)) {
        retval = amxb_invoke_get_instances(bus_ctx, islocal, object, search_path,
                                           depth, ret, timeout);
    } else {
        retval = fns->get_instances(bus_ctx->bus_ctx, object, search_path,
                                    depth, bus_ctx->access, ret, timeout);
    }
 
exit:
    amxc_string_clean(&temp);
    free(object);
    amxd_path_clean(&path);
    return retval;
}

amxb_get_multiple()

int amxb_get_multiple	(	amxb_bus_ctx_t *const	bus_ctx,
		amxc_var_t *	req_paths,
		int32_t	depth,
		amxc_var_t *	ret,
		int	timeout
	)

Fetches one or more (root) objects or multiple parameters.

It is possible to get the parameters from multiple objects at once or to get one single parameter of one or more objects.

This function supports an amxc linked list with paths, each path must follow these rules:

• object path - must end with a "."
• search path - can contain expressions or wildcard to filter out instances. they can end with a parameter name, a "." or a "*"
• parameter path - must end with a parameter name (no "." at the end)

In a search path a wildcard "*" or an expression can be put where an instance identifier (instance index) is in an object path.

Examples of valid use case:

amxc_var_t paths;
amxc_var_init(&paths);
amxc_var_set_type(&paths, AMXC_VAR_ID_LIST);
amxc_var_add(cstring_t, &paths, "Phonebook.Contact.1.FirstName");
amxc_var_add(cstring_t, &paths, "Phonebook.Contact.2.");
amxc_var_add(cstring_t, &paths, "Phonebook.Contact.*");
amxc_var_add(cstring_t, &paths, "Phonebook.Contact.[FirstName == 'Jane'].");
amxc_var_add(cstring_t, &paths, "Device.IP.Interface.[Type=='Normal'].IPv4Address.[AddressingType=='Static'].IPAddress");
 
amxb_get_multiple(bus_ctx, &paths, 0, &ret, 5);

The return value of a get_multiple is always an Ambiorix htable variant containing the individual responses from amxb_get for each path:

{
 Device.IP.Interface.[Type=='Normal'].IPv4Address.[AddressingType=='Static'].IPAddress = {
     result = [
         {
         }
     ],
     status = 2
 },
 Phonebook.Contact.* = {
     result = [
         {
             Phonebook.Contact.1. = {
                 FirstName = "John"
                 LastName = "Doe",
             },
             Phonebook.Contact.2. = {
                 FirstName = "Pony"
                 LastName = "Goffin",
             }
         }
     ],
     status = 0
 }
 Phonebook.Contact.1.FirstName = {
     result = [
         {
             Phonebook.Contact.1. = {
                 FirstName = "John"
             }
         }
     ],
     status = 0
 },
 Phonebook.Contact.2. = {
     result = [
         {
             Phonebook.Contact.2. = {
                 FirstName = "Pony"
                 LastName = "Goffin",
             }
         }
     ],
     status = 0
 },
 Phonebook.Contact.[FirstName == 'Jane']. = {
     result = [
         {
         }
     ],
     status = 0
 },
}

Parameters

bus_ctx	The bus context (or connection)
req_paths	Amxc variant containing a list of all paths to search for.
depth	relative depth, if not zero it indicates how many levels of child objects are returned. This depth is the same for all paths.
ret	will contain an amxc variant containing a htable with the objects and their parameters
timeout	in seconds (for every individual amxb_get lookup)

Returns

amxd_status_ok when successful, any other value indicates an error.

Definition at line 78 of file amxb_ba_op_get_multiple.c.

                                   {
    int retval = amxd_status_ok;
    amxc_var_set_type(ret, AMXC_VAR_ID_HTABLE);
 
    when_false(amxc_var_type_of(req_paths) == AMXC_VAR_ID_LIST, exit);
 
    amxc_var_for_each(path, req_paths) {
        int rv = 0;
        amxc_var_t* sub_ret = NULL;
        amxc_var_t* sub_ret_result = NULL;
        const char* path_string = NULL;
 
        path_string = amxc_var_constcast(cstring_t, path);
        sub_ret = amxc_var_add_key(amxc_htable_t, ret, path_string, NULL);
        sub_ret_result = amxc_var_add_new_key(sub_ret, "result");
        rv = amxb_get(bus_ctx, path_string, depth, sub_ret_result, timeout);
        if(amxc_var_type_of(sub_ret_result) == AMXC_VAR_ID_NULL) {
            amxc_var_set_type(sub_ret_result, AMXC_VAR_ID_LIST);
            amxc_var_add(amxc_htable_t, sub_ret_result, NULL);
            rv = amxd_status_object_not_found;
        }
        amxc_var_add_key(uint32_t, sub_ret, "status", rv);
    }
 
    retval = amxd_status_ok;
 
exit:
    return retval;
 
}

amxb_get_supported()

int amxb_get_supported	(	amxb_bus_ctx_t *const	bus_ctx,
		const char *	object,
		uint32_t	flags,
		amxc_var_t *	ret,
		int	timeout
	)

Gets the supported data model.

This function is mainly used to have support for the USP "get supported dm" message.

Use this function for introspection purposes.

This function does not return any instance, it only indicates which objects are multi-instance objects. The place in the object path where normally an instance identifier (index) is set, the place holder "{i}" is used.

The object argument must be in this supported data model notation.

Example:

"Phonebook.Contact.{i}.PhoneNumber.{i}."

Using the flags argument, the requested information can be manipulated:

• AMXB_FLAG_FIRST_LVL - do not return child objects
• AMXB_FLAG_FUNCTIONS - include all RPC methods of the object
• AMXB_FLAG_PARAMETERS - include all parameters of the object
• AMXB_FLAG_EVENTS - include all events of the object

All other flags will be ignored.

The return value of this function is always an Ambiorix variant and will contain the requested information. The return data is stored in the ret argument.

Example of a return variant:

[
   {
       Phonebook.Contact.{i}.PhoneNumber.{i}. = {
           access = 1
           is_multi_instance = true,
           supported_commands = [
           ],
           supported_params = [
               {
                   access = 1
                   param_name = "Phone",
               }
           ],
       }
   }
]

Parameters

bus_ctx	The bus context (or connection)
object	The object path (in supported path notation)
flags	bitmap field of or'ed flags
ret	will contain the requested information
timeout	in seconds

Returns

amxd_status_ok when successful, any other value indicates an error.

Definition at line 113 of file amxb_ba_op_get_sup.c.

                                    {
    int retval = amxd_status_unknown_error;
    const amxb_be_funcs_t* fns = NULL;
    bool lobject = false;
    amxd_path_t path;
    char* fixed = NULL;
    const char* rel_path = NULL;
 
    amxd_path_init(&path, NULL);
    when_null(bus_ctx, exit);
    when_null(bus_ctx->bus_ctx, exit);
 
    amxd_path_setf(&path, true, "%s", object);
    fixed = amxd_path_get_fixed_part(&path, true);
    rel_path = amxd_path_get(&path, AMXD_OBJECT_TERMINATE);
 
    lobject = amxb_is_local_object(bus_ctx, fixed);
    fns = bus_ctx->bus_fn;
 
    if(lobject || !amxb_is_valid_be_func(fns, get_supported, fns->get_supported)) {
        retval = amxb_invoke_get_supported(bus_ctx, fixed, rel_path, flags,
                                           values, timeout);
    } else {
        if(bus_ctx->access == amxd_dm_access_protected) {
            flags |= AMXB_FLAG_PROTECTED;
        }
        retval = fns->get_supported(bus_ctx->bus_ctx, fixed, rel_path, flags,
                                    values, timeout);
    }
 
exit:
    free(fixed);
    amxd_path_clean(&path);
    return retval;
}

amxb_list()

int amxb_list	(	amxb_bus_ctx_t *const	bus_ctx,
		const char *	object,
		uint32_t	flags,
		amxb_be_cb_fn_t	fn,
		void *	priv
	)

List the service elements/nodes of an object.

This function is mainly used for data model introspection and provides list of the service elements/nodes that are part of the object

Use this function for introspection purposes.

Using the flags argument, the requested information can be manipulated:

• AMXB_FLAG_FUNCTIONS - include all RPC methods of the object
• AMXB_FLAG_PARAMETERS - include all parameters of the object
• AMXB_FLAG_OBJECTS - include the names of child objects
• AMXB_FLAG_INSTANCES - include index and name of instance objects

All other flags will be ignored.

Parameters

bus_ctx	The bus context (or connection)
object	The object path (in supported path notation)
flags	bitmap field of ored flags
fn	callback function
priv	private data that will be passed as is to the callback function

Returns

amxd_status_ok when successful, any other value indicates an error.

Definition at line 177 of file amxb_ba_op_list.c.

                          {
    int retval = amxd_status_unknown_error;
    const amxb_be_funcs_t* fns = NULL;
    amxd_path_t path;
    bool lobject = false;
 
    amxd_path_init(&path, NULL);
    when_null(bus_ctx, exit);
    when_null(bus_ctx->bus_ctx, exit);
    if((object != NULL) && ((*object) != 0)) {
        lobject = amxb_is_local_object(bus_ctx, object);
    }
    fns = bus_ctx->bus_fn;
 
    if((object != NULL) && (*object != 0)) {
        amxd_path_setf(&path, true, "%s", object);
        if(lobject || !amxb_is_valid_be_func(fns, list, fns->list)) {
            retval = amxb_invoke_list(bus_ctx, object, flags, fn, priv);
        } else {
            amxb_req_t* req = (amxb_req_t*) calloc(1, sizeof(amxb_req_t));
            when_null(req, exit);
            req->data.cb_fn = fn;
            req->data.priv = priv;
            amxc_llist_append(&bus_ctx->requests, &req->it);
            retval = fns->list(bus_ctx->bus_ctx, object, flags,
                               bus_ctx->access, &req->data);
        }
    } else {
        if(amxb_is_valid_be_func(fns, list, fns->list)) {
            amxb_req_t* req = (amxb_req_t*) calloc(1, sizeof(amxb_req_t));
            when_null(req, exit);
            req->data.cb_fn = fn;
            req->data.priv = priv;
            amxc_llist_append(&bus_ctx->requests, &req->it);
            retval = fns->list(bus_ctx->bus_ctx, object, flags,
                               bus_ctx->access, &req->data);
        } else {
            if(fn != NULL) {
                fn(bus_ctx, NULL, priv);
            }
            retval = AMXB_ERROR_NOT_SUPPORTED_OP;
        }
    }
 
exit:
    amxd_path_clean(&path);
    return retval;
}

amxb_set()

int amxb_set	(	amxb_bus_ctx_t *const	bus_ctx,
		const char *	object,
		amxc_var_t *	values,
		amxc_var_t *	ret,
		int	timeout
	)

Sets parameter values of one single object or of multiple instance objects.

Using this method, the parameter values of an object can be changed.

It is not possible to change read-only parameter values using this function.

This function supports following paths:

• object path - must end with a "."
• search path - can contain expressions or wildcard to filter out instances. and must end with a "." or "*"

In a search path a wildcard "*" or an expression can be put where an instance identifier (instance index) is in an object path.

Examples of valid search paths:

"Phonebook.Contact.*."
"Phonebook.Contact.*"
"Phonebook.Contact.[FirstName == 'Jane']."
"Device.IP.Interface.[Type=='Normal'].IPv4Address.[AddressingType=='Static']."
"Device.IP.Interface.[Type=='Normal' && Stats.ErrorsSent>0].IPv4Address.[AddressingType=='Static']."

The parameter values must be passed as a variant containing a hash-table where each key is a parameter name and the value is the new value for that parameter.

When using a search path and multiple instances match the search path, all the mentioned parameters are modified for all matching instances.

The return value of a set is always an Ambiorix variant and will contain all changed objects, and the changed parameters. Unchanged parameters are not provided in the return value.

Example: When changing all "LastNames" to "Ambiorix" of all contacts using search path "Phonebook.Contact.*" the return value could be

[
    Phonebook.Contact.1. = {
        LastName = "Ambiorix"
    },
    Phonebook.Contact.2. = {
        LastName = "Ambiorix"
    },
    Phonebook.Contact.3. = {
        LastName = "Ambiorix"
    }
]

Parameters

bus_ctx	The bus context (or connection)
object	Full object path, search path or parameter path
values	variant hash-table containing the new values
ret	will contain the objects and their changed parameters
timeout	in seconds

Returns

amxd_status_ok when successful, any other value indicates an error.

Definition at line 172 of file amxb_ba_op_set.c.

                          {
    return amxb_set_impl(bus_ctx, object, 0, values, NULL, ret, timeout);
}

amxb_set_multiple()

int amxb_set_multiple	(	amxb_bus_ctx_t *const	bus_ctx,
		uint32_t	flags,
		amxc_var_t *	req_paths,
		amxc_var_t *	ret,
		int	timeout
	)

Sets parameter values for multiple objects (request paths)

Using this method, the parameter values of an object can be changed.

It is not possible to change read-only parameter values using this function.

This function supports following paths:

• object path - must end with a "."
• search path - can contain expressions or wildcard to filter out instances. and must end with a "." or "*"

In a search path a wildcard "*" or an expression can be put where an instance identifier (instance index) is in an object path.

Examples of valid search paths:

"Phonebook.Contact.*."
"Phonebook.Contact.*"
"Phonebook.Contact.[FirstName == 'Jane']."
"Device.IP.Interface.[Type=='Normal'].IPv4Address.[AddressingType=='Static']."
"Device.IP.Interface.[Type=='Normal' && Stats.ErrorsSent>0].IPv4Address.[AddressingType=='Static']."

The parameter values must be passed as a variant containing a hash-table where each key is a parameter name and the value is the new value for that parameter.

When using a search path and multiple instances match the search path, all the mentioned parameters are modified for all matching instances.

The return value of a set is always an Ambiorix variant and will contain all changed objects, and the changed parameters. Unchanged parameters are not provided in the return value. For each request path a status is added as well.

When the status code is 0, the set for that request path was successful. All other status codes indicate an error and is always referring to one of the amxd_status_t enum.

When the flag AMXB_FLAG_PARTIAL is set, an error code is returned for each parameter that could not be set. The error code is one of the amxd_status_t codes.

When failed to set an optional parameter, an error code is returned for that parameter.

Example of a valid req_paths variant:

[
    {
        path = "Device.Ethernet.Interface.2.",
        parameters = {
            Status = "dummy-invalid"
        }
    },
    {
        path = "Device.Ethernet.Interface.[Status == 'Dormant'].",
        parameters = {
            Enable = false
        }
    },
    {
        path = "MQTT.Client.*.",
        parameters = {
            Enable = true
        },
        oparameters = {
            TransportProtocol = "TLS"
        }
    },
    {
        path = "MQTT.Client.1.",
        parameters = {
            Enable = true,
            TransportProtocol = "TLS"
        }
    }
]

The above req_paths variant will return in case AMXB_FLAG_PARTIAL is provided:

[
    {
        path = "Device.Ethernet.Interface.2.",
        result = {
            Device.Ethernet.Interface.2. = {
                Status = {
                    error_code = 10,
                    required = true
                }
            }
        },
        status = 10
    },
    {
        path = "Device.Ethernet.Interface.[Status == 'Dormant'].",
        result = {
            Device.Ethernet.Interface.1. = {
                Enable = false
            }
            Device.Ethernet.Interface.5. = {
                Enable = false
            },
        },
        status = 0
    },
    {
        path = "MQTT.Client.*.",
        result = {
            MQTT.Client.1. = {
                Enable = true,
                TransportProtocol = "TLS"
            },
            MQTT.Client.2. = {
                Enable = true,
                TransportProtocol = "TLS"
            }
        },
        status = 0
    },
    {
        path = "MQTT.Client.[Alias == 'cpe-mybroker'].",
        result = {
            MQTT.Client.1. = {
                Enable = true,
                TransportProtocol = "TLS"
            }
        },
        status = 0
    }
]

In case the AMXB_FLAG_PARTIAL is not provided only the first failing request path is returned and all others are not applied.

[
    {
        path = "Device.Ethernet.Interface.2.",
        result = {
            Device.Ethernet.Interface.2. = {
                Status = {
                    error_code = 10,
                    required = true
                }
            }
        },
        status = 10
    }
}

Parameters

bus_ctx	The bus context (or connection)
flags	Supported flags are AMXB_FLAG_PARTIAL.
req_paths	hash-table variant containing the request paths and parameters to be set
ret	will contain for each request path the result and status
timeout	in seconds

Returns

amxd_status_ok when successful, any other value indicates an error.

Definition at line 141 of file amxb_ba_op_set_multiple.c.

                                   {
    int retval = amxd_status_unknown_error;
    amxc_var_t sub_ret;
    amxc_var_t rollback;
    amxc_var_t current;
    int count = 0;
    bool allow_partial = ((flags & AMXB_FLAG_PARTIAL) != 0);
    amxc_var_init(&sub_ret);
    amxc_var_init(&rollback);
    amxc_var_init(&current);
    amxc_var_set_type(ret, AMXC_VAR_ID_LIST);
    amxc_var_set_type(&rollback, AMXC_VAR_ID_HTABLE);
 
    when_false(amxc_var_type_of(req_paths) == AMXC_VAR_ID_LIST, exit);
 
    count = amxc_llist_size(amxc_var_constcast(amxc_llist_t, req_paths));
 
    retval = amxd_status_ok;
 
    amxc_var_for_each(req_path, req_paths) {
        int rv = 0;
        const char* object = GET_CHAR(req_path, "path");
        amxc_var_t* params = GET_ARG(req_path, "parameters");
        amxc_var_t* oparams = GET_ARG(req_path, "oparameters");
        if(!allow_partial && (count > 1)) {
            amxc_var_clean(&current);
            amxb_get(bus_ctx, object, 0, &current, 5);
            amxb_filter_params(GETI_ARG(&current, 0), params, oparams);
        }
        rv = amxb_set_impl(bus_ctx, object, flags, params, oparams, &sub_ret, timeout);
 
        if((rv != 0) && !allow_partial) {
            // reset return variant, only keep failed set
            amxc_var_set_type(ret, AMXC_VAR_ID_LIST);
        }
 
        // add results
        amxb_set_result(object, ret, &sub_ret, rv);
 
        // what is next? continue or fail.
        if(rv != 0) {
            if(!allow_partial) {
                if(count > 1) {
                    amxb_set_rollback(bus_ctx, &rollback);
                }
                retval = rv;
                break;
            }
        } else {
            if(!allow_partial && (count > 1)) {
                amxb_add_rollback(GETI_ARG(&current, 0), &rollback);
            }
        }
 
        amxc_var_clean(&sub_ret);
    }
 
exit:
    amxc_var_clean(&current);
    amxc_var_clean(&rollback);
    amxc_var_clean(&sub_ret);
    return retval;
}