Snapdragon® Telematics Application Framework (TelAF) Interface Specification
|
The Config Tree is a non-volatile noSQL database that stores configuration values for apps. By default each app is given read access to a single tree that has the same name as the app. Any other access permissions (read access for any other tree, or write access to any tree at all) must be explicitly granted in the app's .adef file.
Trees are created automatically the first time that they are accessed by an app or a component. The apps tree will be named the same as the name of the app. It is possible for apps to be given access to other apps tree's or for multiple apps to share one tree.
system
tree.Apps are able to search over the tree for data, although it's generally expected that the location will be known to the app and that the app will point to the right node to retrieve the value.
More on the Config Strategy for the Legato AF.
The tree is broken down into stems and leaves.
A stem is a node that has at least one child node. A leaf has no children and holds a value.
Paths in the tree are traditional Unix style paths and each node is separated by a /:
If no app is specified as the root of the tree, then the app will search in it's own tree. To get to another tree reference that tree followed by a colon.
/path/to/my/tree/value # references the default apps tree secondTree:/path/to/secondTree/value # references the second tree
Apps must explicitly give permissions to other apps before they can access their Config Tree data. This is done in the .adef file. Each transaction is only able to iterate over one tree at a time, each tree that you want to read or write to must be created as a separate transaction.
The Config Tree supports storing the following types of data and each has their own get/set function as well as a quick set/get function (see Quick Read/Writes):
Each transaction has a global timeout setting (default is 30s). The configuration is located in the System Tree and may be configured with the config target tool.
config /configTree/transactionTimeout 10 int #changes the timeout to 10s
To make a change to the tree, you must Create a write transaction, call one or more Set functions, and Commit the transaction. If a write transaction is canceled instead of committed, then the changes will be discarded and the tree will remain unchanged.
To read from a tree without making any changes, you should:
You could also:
Transactions must not be kept open for extended periods of time. If a transaction is kept open for longer than the transaction time limit (default is 30 seconds), then the Config Tree will cancel the transaction and drop the connection to the offending client (most likely causing the client process to terminate).
Function | Action |
---|---|
le_cfg_CreateReadTxn() | Opens the transaction |
le_cfg_CancelTxn() | Closes a read/write transaction and does not write it to the tree |
le_cfg_CommitTxn() | Closes a write transaction and queues it for commit |
To move around within the Tree you can move directly to a specific node(leaf or stem) and then do your read or write from that point. Functions have been added to easily navigate through Tree. All nodes can be referenced either by their absolute or relative paths.
Function | Action |
---|---|
le_cfg_GoToNode() | Moves to the location specified |
le_cfg_GoToParent() | Moves to the parent of the current node (moves up the Tree) |
le_cfg_GoToFirstChild() | Moves to the first node from the current location (moves down the Tree) |
le_cfg_GoToNextSibling() | Moves to the next node on the same level as the current node (moves laterally) |
The Config tree also contains functions to help you identify your current location in the tree, what node you are currently pointing at, and what type of data is contained in the current node.
Function | Action |
---|---|
le_cfg_GetPath() | Gets the location of where you are in the Tree |
le_cfg_GetNodeType() | Gets the data type of the node where you are currently located |
le_cfg_GetNodeName() | Gets the name of the node where you are in the Tree (does not include the path) |
Each data type has it's own get function to read a value from a node within the Tree.
Function | Action |
---|---|
le_cfg_GetString() | Reads the string's value |
le_cfg_GetBinary() | Reads the array of bytes |
le_cfg_GetInt() | Reads the integer's value |
le_cfg_GetFloat() | Reads the floating point value |
le_cfg_GetBool() | Reads the boolean value |
To perform a read from a Tree, we need to open a transaction, move to the node that you want to read from, read the node and then cancel the transaction.
Sample read transaction (with error checking):
Each data type has it's own set function, to write a value to a node within the Tree. Before you are able to write to a tree, permissions must be set in the apps .adef's requires section or with the toolsTarget_config tool.
Function | Action |
---|---|
le_cfg_SetString() | Writes the string's value |
le_cfg_SetBinary() | Writes the array of bytes |
le_cfg_SetInt() | Writes the integer's value |
le_cfg_SetFloat() | Writes the floating point value |
le_cfg_SetBool() | Writes the boolean value |
To perform a write to a Tree, we need to open a transaction, move to the node that you want to write to, write to the node and then commit the transaction.
Sample write transaction (with error checking):
You can also delete a node from the tree. A word of caution as deleting a node will automatically delete all children nodes as well.
Function | Action |
---|---|
le_cfg_DeleteNode() | Deletes the node and all children |
Another option is to perform quick read/write which implicitly wraps functions with in an internal transaction. This is ideal if all you need to do is read or write some simple values to the default app tree.
The quick reads and writes work almost identically to the transactional version except quick reads don't explicitly take an iterator object. The quick functions internally use an implicit transaction. This implicit transaction wraps one get or set, and does not protect your code from other activity in the system.
Because quick read/write functions don't get created within a transaction, there is no option to traverse to a specific node. All values that are read or written must be referenced from the root of the tree.
Example of a quick read of the binary data:
A quick delete example:
Copyright (C) Sierra Wireless Inc.