#include <stdlib.h>
#include <stdbool.h>
#include "returncodes.h"
#include "swi_dset.h"
Typedefs | |
| typedef void(* | swi_dt_NotifyCB_t )(swi_dset_Iterator_t *data) |
| Variable change notification callback. | |
| typedef void * | swi_dt_regId_t |
| Registration identifier. | |
Functions | |
| rc_ReturnCode_t | swi_dt_Init () |
| Initializes the module. | |
| rc_ReturnCode_t | swi_dt_Destroy () |
| Destroys the DeviceTree library. | |
| rc_ReturnCode_t | swi_dt_Get (const char *pathPtr, swi_dset_Iterator_t **data, bool *isLeaf) |
| Retrieves a variable's value from the device tree. | |
| rc_ReturnCode_t | swi_dt_MultipleGet (size_t numVars, const char **pathPtr, swi_dset_Iterator_t **data) |
| Retrieves several variable values from the device tree. | |
| rc_ReturnCode_t | swi_dt_SetInteger (const char *pathPtr, int value) |
| Sets an integer variable value into the variable tree. | |
| rc_ReturnCode_t | swi_dt_SetFloat (const char *pathPtr, double value) |
| Sets a float variable value into the variable tree. | |
| rc_ReturnCode_t | swi_dt_SetString (const char *pathPtr, const char *valuePtr) |
| Sets a string variable value into the variable tree. | |
| rc_ReturnCode_t | swi_dt_SetNull (const char *pathPtr) |
| Sets a NULL variable value into the variable tree. | |
| rc_ReturnCode_t | swi_dt_SetBool (const char *pathPtr, bool value) |
| Sets a boolean variable value into the variable tree. | |
| rc_ReturnCode_t | swi_dt_Register (size_t numRegVars, const char **regVarsPtr, swi_dt_NotifyCB_t cb, size_t numPassiveVars, const char **passiveVarsPtr, swi_dt_regId_t *regIdPtr) |
| Registers to receive a notification when one or several variables change. | |
| rc_ReturnCode_t | swi_dt_Unregister (swi_dt_regId_t regId) |
| Cancels registration to receive a notification when a variable changes. | |
This module provides read/write access to system parameters and settings, as well as the ability to receive notifications when they change. System parameters and settings are addressed based on a predefined tree (the "Device Tree") that organizes them based on functionality. This tree will continue to be developed and expanded as the Application Framework evolves.
| typedef void(* swi_dt_NotifyCB_t)(swi_dset_Iterator_t *data) |
Variable change notification callback.
It will be called when a watched variable has changed.
| data | [IN] data iterator containing the variable values. The data iterator will be allocated by DeviceTree library, and automatically released when the callback returns. |
| typedef void* swi_dt_regId_t |
Registration identifier.
Used to identify an registration so that it can be unregistered afterwards.
| rc_ReturnCode_t swi_dt_Destroy | ( | ) |
Destroys the DeviceTree library.
| rc_ReturnCode_t swi_dt_Get | ( | const char * | pathPtr, | |
| swi_dset_Iterator_t ** | data, | |||
| bool * | isLeaf | |||
| ) |
Retrieves a variable's value from the device tree.
There are 2 cases: either the requested path is a node or it is a value.
Leaf case: When retrieving a leaf, the result will be put as the single element in a swi_dset_Iterator_t object, and the `isLeaf` parameter will be set to `true`.
Internal Node case: The retrieval is not recursive: asking for a path prefix (i.e. a node) will not return every key/value pairs sharing this prefix. Instead, the `isLeaf` parameter will be set to `false` and the result will be a list of element put in a swi_dset_Iterator_t object, the list provides the absolute and relatives paths to the prefix's direct children. Each iterator element will give the name of one sub-element of the requested node.
For instance, if the branch foo.bar contains { x=1, y={z1=2, z2=3}}, a get("foo.bar") will return { "foo.bar.x"="x", "foo.bar.y"="y" }. No children value is returned, and the children of y, which are the grand-children of foo.bar, are not iterated.
RC_NOT_FOUND when requested path was not found
| pathPtr | [IN] the path to retrieve, can be a leaf or a node. |
| data | [OUT] the data iterator containing the results of the Get operation. The DeviceTree library will allocate data iterator resources. The user is responsible to release the data iterator resources using swi_dset_Destroy function. |
| isLeaf | [OUT] Optional output boolean parameter to indicate that the request was on a leaf node (`true` is returned) or on an internal node (`false` is returned) |
| rc_ReturnCode_t swi_dt_Init | ( | ) |
Initializes the module.
A call to init is mandatory to enable DeviceTree library APIs.
| rc_ReturnCode_t swi_dt_MultipleGet | ( | size_t | numVars, | |
| const char ** | pathPtr, | |||
| swi_dset_Iterator_t ** | data | |||
| ) |
Retrieves several variable values from the device tree.
Only leaf paths will be retrieved, any node path will be silently discarded. Each leaf value will be put as an element in the swi_dset_Iterator_t object. Each element's name will be the full path of the variable.
RC_NOT_FOUND when one of the requested path was not found, then the whole request will fail and no value is returned.
| numVars | [IN] the number of variables to retrieve. |
| pathPtr | [IN] pointer to an array of strings (with numVars entries), contains the path of each variable to retrieve. |
| data | [OUT] the data iterator containing the results of the Get operation. The DeviceTree library will allocate data iterator resources. The user is responsible to release the data iterator resources using swi_dset_Destroy function. |
| rc_ReturnCode_t swi_dt_Register | ( | size_t | numRegVars, | |
| const char ** | regVarsPtr, | |||
| swi_dt_NotifyCB_t | cb, | |||
| size_t | numPassiveVars, | |||
| const char ** | passiveVarsPtr, | |||
| swi_dt_regId_t * | regIdPtr | |||
| ) |
Registers to receive a notification when one or several variables change.
The callback will be called in a new pthread.
The callback is triggered every time one or some of the variables listed in regvars changes. It receives as parameter a swi_dset_Iterator_t with variable-name / variable-value pairs; these variables are all the variables listed in regvars which have changed, plus every variables listed in passivevars, whether their values changed or not.
Please note that the callback can be called with swi_dset_Iterator_t param containing swi_dset_Type_t SWI_DSET_NIL type to indicate variable(s) deletion. Variables listed in regvars and passivevars can be either fully qualified variable names, or a path which denotes every individual variable below this path.
| numRegVars | [IN] the number of variables to register to. |
| regVarsPtr | [IN] pointer to an array of strings (with numRegVars entries), the variables which must be monitored for change. |
| cb | [IN] the function triggered every time a regvars variable changes. The callback is called with a swi_dset_Iterator_t containing all the changes, paths as element names and values as values. |
| numPassiveVars | [IN] the number of passive variables to receive. |
| passiveVarsPtr | [IN] pointer to an array of strings (with numPassiveVars entries), optional variables to always pass to callback, whether they changed or not. |
| regIdPtr | [OUT] identifier of the registration, to be used to cancel it afterward using swi_dt_Unregister function. |
| rc_ReturnCode_t swi_dt_SetBool | ( | const char * | pathPtr, | |
| bool | value | |||
| ) |
Sets a boolean variable value into the variable tree.
RC_NOT_PERMITTED when requesting non-leaf value
RC_NOT_FOUND when requested path was not found
| pathPtr | [IN] pathPtr the path to variable to set in device tree. |
| value | [IN] boolean value to set |
| rc_ReturnCode_t swi_dt_SetFloat | ( | const char * | pathPtr, | |
| double | value | |||
| ) |
Sets a float variable value into the variable tree.
RC_NOT_PERMITTED when requesting non-leaf value
RC_NOT_FOUND when requested path was not found
| pathPtr | [IN] the path to variable to set in device tree. |
| value | [IN] float value to set |
| rc_ReturnCode_t swi_dt_SetInteger | ( | const char * | pathPtr, | |
| int | value | |||
| ) |
Sets an integer variable value into the variable tree.
RC_NOT_PERMITTED when requesting non-leaf value
RC_NOT_FOUND when requested path was not found
| pathPtr | [IN] the path to variable to set in device tree. |
| value | [IN] integer value to set |
| rc_ReturnCode_t swi_dt_SetNull | ( | const char * | pathPtr | ) |
Sets a NULL variable value into the variable tree.
RC_NOT_PERMITTED when requesting non-leaf value
RC_NOT_FOUND when requested path was not found
| pathPtr | [IN] pathPtr the path to variable to set in device tree. |
| rc_ReturnCode_t swi_dt_SetString | ( | const char * | pathPtr, | |
| const char * | valuePtr | |||
| ) |
Sets a string variable value into the variable tree.
RC_NOT_PERMITTED when requesting non-leaf value
RC_NOT_FOUND when requested path was not found
| pathPtr | [IN] pathPtr the path to variable to set in device tree. |
| valuePtr | [IN] string value to set |
| rc_ReturnCode_t swi_dt_Unregister | ( | swi_dt_regId_t | regId | ) |
Cancels registration to receive a notification when a variable changes.
| regId | [IN] identifier of the registration to cancel, the id returned by previous swi_dt_Register call. |
1.5.6