le_cfg_interface.h

    1 
    2 
    3 /*
    4  * ====================== WARNING ======================
    5  *
    6  * THE CONTENTS OF THIS FILE HAVE BEEN AUTO-GENERATED.
    7  * DO NOT MODIFY IN ANY WAY.
    8  *
    9  * ====================== WARNING ======================
   10  */
   11 
   12 /**
   13  * @page c_config Config Tree API
   14  *
   15  * @ref le_cfg_interface.h "API Reference" <br>
   16  *
   17  * The Config Tree is a non-volatile noSQL database that stores configuration values for apps.
   18  * By default each app is given read access to a single tree that has the same name as the app.
   19  * Any other access permissions (read access for any other tree, or write access to any tree at all)
   20  * must be explicitly granted in the app's @ref defFilesAdef_requiresConfigTree ".adef file".
   21  *
   22  * Trees are created automatically the first time that they are accessed by an app or a component.
   23  * The apps tree will be named the same as the name of the app. It is possible for apps to be given
   24  * access to other apps tree's or for multiple apps to share one tree.
   25  *
   26  * @note If your app is running as root then the configuration will get added to the
   27  * System Tree by default. System utilities also use the Config Tree and store their
   28  * configurations in the @c system tree.
   29  *
   30  * Apps are able to search over the tree for data, although it's generally expected that the location
   31  * will be known to the app and that the app will point to the right node to retrieve the value.
   32  *
   33  * More on the @ref conceptsConfig "Config Strategy" for the Legato AF.
   34  *
   35  * @section cfg_Overview Overview
   36  *
   37  * The tree is broken down into stems and leaves.
   38  *
   39  * A stem is a node that has at least one child node. A leaf has no children and holds a value.
   40  *
   41  * @code
   42  *        +tree
   43  *            |
   44  *            +--stem
   45  *            |   |
   46  *            |   +--leaf (value)
   47  *            |
   48  *            +-stem
   49  *               |
   50  *               +--leaf (value)
   51  *               |
   52  *               +--leaf (value)
   53  * @endcode
   54  *
   55  * Paths in the tree are traditional Unix style paths and each node is separated by a /:
   56  *
   57  * @code /stem/stem/leaf @endcode
   58  *
   59  * If no app is specified as the root of the tree, then the app will search in it's own tree.
   60  * To get to another tree reference that tree followed by a colon.
   61  *
   62  * @verbatim
   63  /path/to/my/tree/value                   # references the default apps tree
   64  secondTree:/path/to/secondTree/value    # references the second tree
   65  @endverbatim
   66  *
   67  * @note It's recommended to store anything complex using stems and leaves, this enhances
   68  * readability and debugging. It also helps to sidestep nasty cross platform alignment issues.
   69  *
   70  * Apps must explicitly give permissions to other apps before they can access their Config Tree data.
   71  * This is done in the @ref defFilesAdef_requiresConfigTree ".adef file".
   72  * Each transaction is only able to iterate over one tree at a time, each tree that you want to read
   73  * or write to must be created as a separate transaction.
   74  *
   75  * The Config Tree supports storing the following types of data and each has their own get/set
   76  * function as well as a quick set/get function (see @ref cfg_quick):
   77  * -  string
   78  * -  binary (array of bytes)
   79  * -  signed integer
   80  * -  boolean
   81  * -  64bit floating point
   82  * -  empty values.
   83  *
   84  * Each transaction has a global timeout setting (default is 30s). The configuration is
   85  * located in the System Tree and may be configured with the @ref toolsTarget_config "config"
   86  * target tool.
   87  *
   88  * @verbatim
   89  config /configTree/transactionTimeout 10 int         #changes the timeout to 10s
   90  @endverbatim
   91  *
   92  * @section cfg_trans Transactions
   93  *
   94  * @subsection cfg_transConcepts Key Transaction Concepts
   95  *
   96  * -  All transactions are sent to a queue and processed in a sequence.
   97  * -  Only one write transaction may be active at a time and subsequent writes are queued
   98  *    until the first is finished processing.
   99  * -  Transactions may contain multiple read or write requests within a single transaction.
  100  * -  Multiple read transactions may be processed while a write transaction is active.
  101  * -  Quick(implicit) read/writes can be created and are also sequentially queued.
  102  *
  103  * @subsection cfg_createTrans Create Transactions
  104  *
  105  * To make a change to the tree, you must Create a write transaction, call one or more Set
  106  * functions, and Commit the transaction.  If a write transaction is canceled instead of committed,
  107  * then the changes will be discarded and the tree will remain unchanged.
  108  *
  109  * To read from a tree without making any changes, you should:
  110  * - create a read transaction,
  111  * - call the Get functions,
  112  * - cancel the transaction when finished.
  113  *
  114  * You could also:
  115  * - create a write transaction,
  116  * - perform only Get operations,
  117  * - cancel the transaction
  118  *
  119  * @note It's safer to use a read transaction when there is no intention to change the tree.
  120  *
  121  * Transactions must not be kept open for extended periods of time.  If a transaction is kept open
  122  * for longer than the transaction time limit (default is 30 seconds), then the Config Tree will
  123  * cancel the transaction and drop the connection to the offending client (most likely causing the
  124  * client process to terminate).
  125  *
  126  * | Function                  | Action                                                            |
  127  * | --------------------------| ------------------------------------------------------------------|
  128  * | @c le_cfg_CreateReadTxn() | Opens the transaction                                             |
  129  * | @c le_cfg_CancelTxn()     | Closes a read/write transaction and does not write it to the tree |
  130  * | @c le_cfg_CommitTxn()     | Closes a write transaction and queues it for commit               |
  131  *
  132  * @subsection cfg_transNavigate Navigating the Tree
  133  *
  134  * To move around within the Tree you can move directly to a specific node(leaf or stem) and then
  135  * do your read or write from that point.  Functions have been added to easily navigate through
  136  * Tree. All nodes can be referenced either by their absolute or relative paths.
  137  *
  138  * | Function                    | Action                                                                         |
  139  * | ----------------------------| -------------------------------------------------------------------------------|
  140  * | @c le_cfg_GoToNode()        | Moves to the location specified                                                |
  141  * | @c le_cfg_GoToParent()      | Moves to the parent of the current node (moves up the Tree)                    |
  142  * | @c le_cfg_GoToFirstChild()  | Moves to the first node from the current location (moves down the Tree)        |
  143  * | @c le_cfg_GoToNextSibling() | Moves to the next node on the same level as the current node (moves laterally) |
  144  *
  145  * @subsection cfg_transGetInfo Retrieving Node Information
  146  *
  147  * The Config tree also contains functions to help you identify your current location in the tree,
  148  * what node you are currently pointing at, and what type of data is contained in the current node.
  149  *
  150  * | Function                | Action                                                                          |
  151  * | ------------------------| ------------------------------------------------------------------------------- |
  152  * | @c le_cfg_GetPath()     | Gets the location of where you are in the Tree                                  |
  153  * | @c le_cfg_GetNodeType() | Gets the data type of the node where you are currently located                  |
  154  * | @c le_cfg_GetNodeName() | Gets the name of the node where you are in the Tree (does not include the path) |
  155  *
  156  * @subsection cfg_read Read Transactions
  157  *
  158  * Each data type has it's own get function to read a value from a node within the Tree.
  159  *
  160  * | Function                | Action                                   |
  161  * | ------------------------| -----------------------------------------|
  162  * | @c le_cfg_GetString()   | Reads the string's value                 |
  163  * | @c le_cfg_GetBinary()   | Reads the array of bytes                 |
  164  * | @c le_cfg_GetInt()      | Reads the integer's value                |
  165  * | @c le_cfg_GetFloat()    | Reads the floating point value           |
  166  * | @c le_cfg_GetBool()     | Reads the boolean value                  |
  167  *
  168  * To perform a read from a Tree, we need to open a transaction, move to the node that you want to
  169  * read from, read the node and then cancel the transaction.
  170  *
  171  * Sample read transaction (with error checking):
  172  *
  173  * @code
  174  * le_result_t GetIp4Static  //reads the IP address values from the Config Tree
  175  * (
  176  *     const char* interfaceNamePtr,
  177  *     char* ipAddrPtr,
  178  *     size_t ipAddrSize,
  179  *     char* netMaskPtr,
  180  *     size_t netMaskSize
  181  * )
  182  * {
  183  *     // Change current tree position to the base ip4 node.
  184  *     char nameBuffer[LE_CFG_STR_LEN_BYTES] = { 0 };
  185  *
  186  *     // Returns errors for out of bounds exceptions
  187  *     int r = snprintf(nameBuffer, sizeof(nameBuffer), "/system/%s/ip4", interfaceNamePtr);
  188  *     if (r < 0)
  189  *     {
  190  *         return LE_FAULT;
  191  *     }
  192  *     else if (r >= sizeof(nameBuffer))
  193  *     {
  194  *         return LE_OVERFLOW;
  195  *     }
  196  *
  197  *     // Open up a read transaction on the Config Tree.
  198  *     le_cfg_IteratorRef_t iteratorRef = le_cfg_CreateReadTxn(nameBuffer);
  199  *
  200  *     if (le_cfg_NodeExists(iteratorRef, "") == false)
  201  *     {
  202  *         LE_WARN("Configuration not found.");
  203  *         le_cfg_CancelTxn(iteratorRef);
  204  *         return LE_NOT_FOUND;
  205  *     }
  206  *
  207  *     // Returns the IP Address value stored in the Config Tree.
  208  *     le_result_t result = le_cfg_GetString(iteratorRef, "addr", ipAddrPtr, ipAddrSize, "");
  209  *     if (result != LE_OK)
  210  *     {
  211  *         le_cfg_CancelTxn(iteratorRef);
  212  *         return result;
  213  *     }
  214  *
  215  *     // Returns the NetMask value stored in the Config Tree.
  216  *     result = le_cfg_GetString(iteratorRef, "mask", netMaskPtr, netMaskSize, "");
  217  *     if (result != LE_OK)
  218  *     {
  219  *         le_cfg_CancelTxn(iteratorRef);
  220  *         return result;
  221  *     }
  222  *
  223  *     // Close the transaction and return success.
  224  *     le_cfg_CancelTxn(iteratorRef);
  225  *
  226  *     return LE_OK;
  227  * }
  228  * @endcode
  229  *
  230  * @note Any writes done will be discarded at the end of the read transaction.
  231  *
  232  * @subsection cfg_write Write Transactions
  233  *
  234  * Each data type has it's own set function, to write a value to a node within the Tree. Before you
  235  * are able to write to a tree, permissions must be set in the apps
  236  * @ref defFilesAdef_requiresConfigTree ".adef's requires section" or with the
  237  * @ref toolsTarget_config tool.
  238  *
  239  * | Function                | Action                                   |
  240  * | ------------------------| -----------------------------------------|
  241  * | @c le_cfg_SetString()   | Writes the string's value                |
  242  * | @c le_cfg_SetBinary()   | Writes the array of bytes                |
  243  * | @c le_cfg_SetInt()      | Writes the integer's value               |
  244  * | @c le_cfg_SetFloat()    | Writes the floating point value          |
  245  * | @c le_cfg_SetBool()     | Writes the boolean value                 |
  246  *
  247  * To perform a write to a Tree, we need to open a transaction, move to the node that you want to
  248  * write to, write to the node and then commit the transaction.
  249  *
  250  * Sample write transaction (with error checking):
  251  *
  252  * @code
  253  * // Store IPv4 address/mask in a string representation
  254  * void SetIp4Static
  255  * (
  256  *     const char* interfaceNamePtr,
  257  *     const char* ipAddrPtr,
  258  *     const char* netMaskPtr
  259  * )
  260  * {
  261  *     // Change current tree position to the base ip4 node.
  262  *     char nameBuffer[LE_CFG_STR_LEN_BYTES] = { 0 };
  263  *
  264  *     int r = snprintf(nameBuffer, sizeof(nameBuffer), "/system/%s/ip4", interfaceNamePtr);
  265  *     LE_ASSERT((r >= 0) && (r < sizeof(nameBuffer));
  266  *
  267  *     // Create a write transaction so that we can update the tree.
  268  *     le_cfg_IteratorRef_t iteratorRef = le_cfg_CreateWriteTxn(nameBuffer);
  269  *
  270  *     le_cfg_SetString(iteratorRef, "addr", ipAddrPtr);
  271  *     le_cfg_SetString(iteratorRef, "mask", netMaskPtr);
  272  *
  273  *     // Commit the transaction to make sure these new settings get written to the tree.
  274  *     le_cfg_CommitTxn(iteratorRef);
  275  * }
  276  *
  277  * // Store IPv4 address/mask in a binary representation (array of 4 bytes)
  278  * void SetIp4StaticAsBinary
  279  * (
  280  *     const char* interfaceNamePtr,
  281  *     const uint8_t* ipAddrPtr,
  282  *     const uint8_t* netMaskPtr
  283  * )
  284  * {
  285  *     // Change current tree position to the base ip4 node.
  286  *     char nameBuffer[LE_CFG_STR_LEN_BYTES] = { 0 };
  287  *
  288  *     int r = snprintf(nameBuffer, sizeof(nameBuffer), "/system/%s/ip4", interfaceNamePtr);
  289  *     LE_ASSERT((r >= 0) && (r < sizeof(nameBuffer));
  290  *
  291  *     // Create a write transaction so that we can update the tree.
  292  *     le_cfg_IteratorRef_t iteratorRef = le_cfg_CreateWriteTxn(nameBuffer);
  293  *
  294  *     le_cfg_SetBinary(iteratorRef, "addr", ipAddrPtr, 4);
  295  *     le_cfg_SetBinary(iteratorRef, "mask", netMaskPtr, 4);
  296  *
  297  *     // Commit the transaction to make sure these new settings get written to the tree.
  298  *     le_cfg_CommitTxn(iteratorRef);
  299  * }
  300  * @endcode
  301  *
  302  * @note Creating write transactions creates a temporary working copy of the tree for use within the
  303  * transaction. All read transactions running in the meantime see the committed state, without any
  304  * of the changes that have been made within the write transaction.
  305  *
  306  * @subsection cfg_transDelete Deleting a Node
  307  *
  308  * You can also delete a node from the tree.  A word of caution as deleting a node will
  309  * automatically delete all children nodes as well.
  310  *
  311  * | Function                 | Action                                   |
  312  * | -------------------------| -----------------------------------------|
  313  * | @c le_cfg_DeleteNode()   | Deletes the node and all children        |
  314  *
  315  * @section cfg_quick Quick Read/Writes
  316  *
  317  * Another option is to perform quick read/write which implicitly wraps functions with in an
  318  * internal transaction. This is ideal if all you need to do is read or write some simple values
  319  * to the default app tree.
  320  *
  321  * The quick reads and writes work almost identically to the transactional version except quick
  322  * reads don't explicitly take an iterator object. The quick functions internally use an
  323  * implicit transaction. This implicit transaction wraps one get or set, and does not protect
  324  * your code from other activity in the system.
  325  *
  326  * Because quick read/write functions don't get created within a transaction, there is no option to
  327  * traverse to a specific node.
  328  * All values that are read or written must be referenced from the root of the tree.
  329  *
  330  * Example of a quick read of the binary data:
  331  *
  332  * @code
  333  * #define IPV4_ADDR_LEN 4
  334  * le_result_t QuickReadIpAddressAsBinary
  335  * (
  336  *     const char* interfaceNamePtr,
  337  *     const uint8_t* ipAddrPtr,
  338  *     const uint8_t* netMaskPtr
  339  * )
  340  * {
  341  *     char pathBuffer[MAX_CFG_STRING] = { 0 };
  342  *     uint8_t defaultAddr[IPV4_ADDR_LEN] = { 0 };
  343  *     le_result_t result = LE_OK;
  344  *     size_t len = IPV4_ADDR_LEN;
  345  *
  346  *     // read the address
  347  *     snprintf(pathBuffer, sizeof(pathBuffer), "/system/%s/ip4/addr", interfaceNamePtr);
  348  *     result = le_cfg_QuickGetBinary(pathBuffer, ipAddrPtr, &len, defaultAddr, IPV4_ADDR_LEN);
  349  *     if (LE_OK != result)
  350  *     {
  351  *         return result;
  352  *     }
  353  *
  354  *     // read the mask
  355  *     snprintf(pathBuffer, sizeof(pathBuffer), "/system/%s/ip4/mask", interfaceNamePtr);
  356  *     len = IPV4_ADDR_LEN;
  357  *     result = le_cfg_QuickGetBinary(pathBuffer, netMaskPtr, &len, defaultAddr, IPV4_ADDR_LEN);
  358  *     if (LE_OK != result)
  359  *     {
  360  *         return result;
  361  *     }
  362  * }
  363  * @endcode
  364  *
  365  *
  366  * A quick delete example:
  367  *
  368  * @code
  369  * void ClearIpInfo
  370  * (
  371  *     const char* interfaceNamePtr
  372  * )
  373  * {
  374  *     char pathBuffer[MAX_CFG_STRING] = { 0 };
  375  *
  376  *     // Removes the node from the tree.
  377  *     snprintf(pathBuffer, sizeof(pathBuffer), "/system/%s/ip4/", interfaceNamePtr);
  378  *     le_cfg_QuickDeleteNode(pathBuffer);
  379  * }
  380  * @endcode
  381  *
  382  * @warning Because each quick function is independent, there's no guarantee of consistency between
  383  * them.  If another process changes one of the values while you read/write the other,
  384  * the two values could be read out of sync.
  385  *
  386  * Copyright (C) Sierra Wireless Inc.
  387  */
  388 /**
  389  * @file le_cfg_interface.h
  390  *
  391  * Legato @ref c_config include file.
  392  *
  393  * Copyright (C) Sierra Wireless Inc.
  394  */
  395 
  396 #ifndef LE_CFG_INTERFACE_H_INCLUDE_GUARD
  397 #define LE_CFG_INTERFACE_H_INCLUDE_GUARD
  398 
  399 
  400 #include "legato.h"
  401 
  402 
  403 //--------------------------------------------------------------------------------------------------
  404 /**
  405  * Type for handler called when a server disconnects.
  406  */
  407 //--------------------------------------------------------------------------------------------------
  408 typedef void (*le_cfg_DisconnectHandler_t)(void *);
  409 
  410 //--------------------------------------------------------------------------------------------------
  411 /**
  412  *
  413  * Connect the current client thread to the service providing this API. Block until the service is
  414  * available.
  415  *
  416  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  417  * called before any other functions in this API.  Normally, ConnectService is automatically called
  418  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  419  *
  420  * This function is created automatically.
  421  */
  422 //--------------------------------------------------------------------------------------------------
  423 void le_cfg_ConnectService
  424 (
  425     void
  426 );
  427 
  428 //--------------------------------------------------------------------------------------------------
  429 /**
  430  *
  431  * Try to connect the current client thread to the service providing this API. Return with an error
  432  * if the service is not available.
  433  *
  434  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  435  * called before any other functions in this API.  Normally, ConnectService is automatically called
  436  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  437  *
  438  * This function is created automatically.
  439  *
  440  * @return
  441  *  - LE_OK if the client connected successfully to the service.
  442  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
  443  *    bound.
  444  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  445  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  446  */
  447 //--------------------------------------------------------------------------------------------------
  448 le_result_t le_cfg_TryConnectService
  449 (
  450     void
  451 );
  452 
  453 //--------------------------------------------------------------------------------------------------
  454 /**
  455  * Set handler called when server disconnection is detected.
  456  *
  457  * When a server connection is lost, call this handler then exit with LE_FATAL.  If a program wants
  458  * to continue without exiting, it should call longjmp() from inside the handler.
  459  */
  460 //--------------------------------------------------------------------------------------------------
  461 void le_cfg_SetServerDisconnectHandler
  462 (
  463     le_cfg_DisconnectHandler_t disconnectHandler,
  464     void *contextPtr
  465 );
  466 
  467 //--------------------------------------------------------------------------------------------------
  468 /**
  469  *
  470  * Disconnect the current client thread from the service providing this API.
  471  *
  472  * Normally, this function doesn't need to be called. After this function is called, there's no
  473  * longer a connection to the service, and the functions in this API can't be used. For details, see
  474  * @ref apiFilesC_client.
  475  *
  476  * This function is created automatically.
  477  */
  478 //--------------------------------------------------------------------------------------------------
  479 void le_cfg_DisconnectService
  480 (
  481     void
  482 );
  483 
  484 
  485 //--------------------------------------------------------------------------------------------------
  486 /**
  487  * Length of the strings used by this API.
  488  */
  489 //--------------------------------------------------------------------------------------------------
  490 #define LE_CFG_STR_LEN 511
  491 
  492 //--------------------------------------------------------------------------------------------------
  493 /**
  494  * Length of the strings used by this API, including the trailing NULL.
  495  */
  496 //--------------------------------------------------------------------------------------------------
  497 #define LE_CFG_STR_LEN_BYTES 512
  498 
  499 //--------------------------------------------------------------------------------------------------
  500 /**
  501  * Length of the binary data used by this API.
  502  */
  503 //--------------------------------------------------------------------------------------------------
  504 #define LE_CFG_BINARY_LEN 8192
  505 
  506 //--------------------------------------------------------------------------------------------------
  507 /**
  508  * Allowed length of a node name.
  509  */
  510 //--------------------------------------------------------------------------------------------------
  511 #define LE_CFG_NAME_LEN 127
  512 
  513 //--------------------------------------------------------------------------------------------------
  514 /**
  515  * The node name length, including a trailing NULL.
  516  */
  517 //--------------------------------------------------------------------------------------------------
  518 #define LE_CFG_NAME_LEN_BYTES 128
  519 
  520 //--------------------------------------------------------------------------------------------------
  521 /**
  522  * Reference to a tree iterator object.
  523  */
  524 //--------------------------------------------------------------------------------------------------
  525 typedef struct le_cfg_Iterator* le_cfg_IteratorRef_t;
  526 
  527 
  528 //--------------------------------------------------------------------------------------------------
  529 /**
  530  * Identifies the data type of node.
  531  */
  532 //--------------------------------------------------------------------------------------------------
  533 typedef enum
  534 {
  535     LE_CFG_TYPE_EMPTY = 0,
  536         ///< A node with no value.
  537     LE_CFG_TYPE_STRING = 1,
  538         ///< A string encoded as utf8.
  539     LE_CFG_TYPE_BOOL = 2,
  540         ///< Boolean value.
  541     LE_CFG_TYPE_INT = 3,
  542         ///< Signed 32-bit.
  543     LE_CFG_TYPE_FLOAT = 4,
  544         ///< 64-bit floating point value.
  545     LE_CFG_TYPE_STEM = 5,
  546         ///< Non-leaf node, this node is the parent of other nodes.
  547     LE_CFG_TYPE_DOESNT_EXIST = 6
  548         ///< Node doesn't exist.
  549 }
  550 le_cfg_nodeType_t;
  551 
  552 
  553 //--------------------------------------------------------------------------------------------------
  554 /**
  555  * Reference type used by Add/Remove functions for EVENT 'le_cfg_Change'
  556  */
  557 //--------------------------------------------------------------------------------------------------
  558 typedef struct le_cfg_ChangeHandler* le_cfg_ChangeHandlerRef_t;
  559 
  560 
  561 //--------------------------------------------------------------------------------------------------
  562 /**
  563  * Handler for node change notifications.
  564  */
  565 //--------------------------------------------------------------------------------------------------
  566 typedef void (*le_cfg_ChangeHandlerFunc_t)
  567 (
  568     void* contextPtr
  569         ///<
  570 );
  571 
  572 //--------------------------------------------------------------------------------------------------
  573 /**
  574  * Create a read transaction and open a new iterator for traversing the config tree.
  575  *
  576  * This action creates a read lock on the given tree, which will start a read-timeout.
  577  * Once the read timeout expires, all active read iterators on that tree will be
  578  * expired and their clients will be killed.
  579  *
  580  * @note A tree transaction is global to that tree; a long-held read transaction will block other
  581  *        user's write transactions from being committed.
  582  *
  583  * @return This will return the newly created iterator reference.
  584  */
  585 //--------------------------------------------------------------------------------------------------
  586 le_cfg_IteratorRef_t le_cfg_CreateReadTxn
  587 (
  588     const char* LE_NONNULL basePath
  589         ///< [IN] Path to the location to create the new iterator.
  590 );
  591 
  592 //--------------------------------------------------------------------------------------------------
  593 /**
  594  * Create a write transaction and open a new iterator for both reading and writing.
  595  *
  596  * This action creates a write transaction. If the app holds the iterator for
  597  * longer than the configured write transaction timeout, the iterator will cancel the
  598  * transaction. Other reads will fail to return data, and all writes will be thrown away.
  599  *
  600  * @note A tree transaction is global to that tree; a long-held write transaction will block
  601  *       other user's write transactions from being started. Other trees in the system
  602  *       won't be affected.
  603  *
  604  * @return This will return a newly created iterator reference.
  605  */
  606 //--------------------------------------------------------------------------------------------------
  607 le_cfg_IteratorRef_t le_cfg_CreateWriteTxn
  608 (
  609     const char* LE_NONNULL basePath
  610         ///< [IN] Path to the location to create the new iterator.
  611 );
  612 
  613 //--------------------------------------------------------------------------------------------------
  614 /**
  615  * Closes the write iterator and commits the write transaction. This updates the config tree
  616  * with all of the writes that occurred within the iterator.
  617  *
  618  * @note This operation will also delete the iterator object.
  619  */
  620 //--------------------------------------------------------------------------------------------------
  621 void le_cfg_CommitTxn
  622 (
  623     le_cfg_IteratorRef_t iteratorRef
  624         ///< [IN] Iterator object to commit.
  625 );
  626 
  627 //--------------------------------------------------------------------------------------------------
  628 /**
  629  * Closes and frees the given iterator object. If the iterator is a write iterator, the transaction
  630  * will be canceled. If the iterator is a read iterator, the transaction will be closed. No data is
  631  * written to the tree
  632  *
  633  * @note This operation will also delete the iterator object.
  634  */
  635 //--------------------------------------------------------------------------------------------------
  636 void le_cfg_CancelTxn
  637 (
  638     le_cfg_IteratorRef_t iteratorRef
  639         ///< [IN] Iterator object to close.
  640 );
  641 
  642 //--------------------------------------------------------------------------------------------------
  643 /**
  644  * Changes the location of iterator. The path passed can be an absolute or a
  645  * relative path from the iterators current location.
  646  *
  647  * The target node does not need to exist. Writing a value to a non-existent node will
  648  * automatically create that node and any ancestor nodes (parent, parent's parent, etc.) that
  649  * also don't exist.
  650  */
  651 //--------------------------------------------------------------------------------------------------
  652 void le_cfg_GoToNode
  653 (
  654     le_cfg_IteratorRef_t iteratorRef,
  655         ///< [IN] Iterator to move.
  656     const char* LE_NONNULL newPath
  657         ///< [IN] Absolute or relative path from the current location.
  658 );
  659 
  660 //--------------------------------------------------------------------------------------------------
  661 /**
  662  * Move the iterator to the parent of the current node (moves up the tree).
  663  *
  664  * @return Return code will be one of the following values:
  665  *
  666  *         - LE_OK        - Commit was completed successfully.
  667  *         - LE_NOT_FOUND - Current node is the root node: has no parent.
  668  */
  669 //--------------------------------------------------------------------------------------------------
  670 le_result_t le_cfg_GoToParent
  671 (
  672     le_cfg_IteratorRef_t iteratorRef
  673         ///< [IN] Iterator to move.
  674 );
  675 
  676 //--------------------------------------------------------------------------------------------------
  677 /**
  678  * Moves the iterator to the the first child of the node from the current location.
  679  *
  680  * For read iterators without children, this function will fail. If the iterator is a write
  681  * iterator, then a new node is automatically created. If this node or newly created
  682  * children of this node are not written to, then this node will not persist even if the iterator is
  683  * committed.
  684  *
  685  * @return Return code will be one of the following values:
  686  *
  687  *         - LE_OK        - Move was completed successfully.
  688  *         - LE_NOT_FOUND - The given node has no children.
  689  */
  690 //--------------------------------------------------------------------------------------------------
  691 le_result_t le_cfg_GoToFirstChild
  692 (
  693     le_cfg_IteratorRef_t iteratorRef
  694         ///< [IN] Iterator object to move.
  695 );
  696 
  697 //--------------------------------------------------------------------------------------------------
  698 /**
  699  * Jumps the iterator to the next child node of the current node. Assuming the following tree:
  700  *
  701  * @code
  702  * baseNode
  703  *      |
  704  *      +childA
  705  *          |
  706  *          +valueA
  707  *          |
  708  *          +valueB
  709  * @endcode
  710  *
  711  * If the iterator is moved to the path, "/baseNode/childA/valueA". After the first
  712  * GoToNextSibling the iterator will be pointing at valueB. A second call to GoToNextSibling
  713  * will cause the function to return LE_NOT_FOUND.
  714  *
  715  * @return Returns one of the following values:
  716  *
  717  *         - LE_OK            - Commit was completed successfully.
  718  *         - LE_NOT_FOUND     - Iterator has reached the end of the current list of siblings.
  719  *                              Also returned if the the current node has no siblings.
  720  */
  721 //--------------------------------------------------------------------------------------------------
  722 le_result_t le_cfg_GoToNextSibling
  723 (
  724     le_cfg_IteratorRef_t iteratorRef
  725         ///< [IN] Iterator to iterate.
  726 );
  727 
  728 //--------------------------------------------------------------------------------------------------
  729 /**
  730  * Get path to the node where the iterator is currently pointed.
  731  *
  732  * Assuming the following tree:
  733  *
  734  * @code
  735  * baseNode
  736  *      |
  737  *      +childA
  738  *          |
  739  *          +valueA
  740  *          |
  741  *          +valueB
  742  * @endcode
  743  *
  744  * If the iterator was currently pointing at valueA, GetPath would return the following path:
  745  *
  746  * @code
  747  * /baseNode/childA/valueA
  748  * @endcode
  749  *
  750  * Optionally, a path to another node can be supplied to this function. So, if the iterator is
  751  * again on valueA and the relative path ".." is supplied then this function will return the
  752  * the path relative to the node given:
  753  *
  754  * @code
  755  * /baseNode/childA/
  756  * @endcode
  757  *
  758  * @return - LE_OK            - The write was completed successfully.
  759  *         - LE_OVERFLOW      - The supplied string buffer was not large enough to hold the value.
  760  */
  761 //--------------------------------------------------------------------------------------------------
  762 le_result_t le_cfg_GetPath
  763 (
  764     le_cfg_IteratorRef_t iteratorRef,
  765         ///< [IN] Iterator to move.
  766     const char* LE_NONNULL path,
  767         ///< [IN] Path to the target node. Can be an absolute path, or
  768         ///< a path relative from the iterator's current position.
  769     char* pathBuffer,
  770         ///< [OUT] Absolute path to the iterator's current node.
  771     size_t pathBufferSize
  772         ///< [IN]
  773 );
  774 
  775 //--------------------------------------------------------------------------------------------------
  776 /**
  777  * Get the data type of node where the iterator is currently pointing.
  778  *
  779  * @return le_cfg_nodeType_t value indicating the stored value.
  780  */
  781 //--------------------------------------------------------------------------------------------------
  782 le_cfg_nodeType_t le_cfg_GetNodeType
  783 (
  784     le_cfg_IteratorRef_t iteratorRef,
  785         ///< [IN] Iterator object to use to read from the tree.
  786     const char* LE_NONNULL path
  787         ///< [IN] Path to the target node. Can be an absolute path, or
  788         ///< a path relative from the iterator's current position.
  789 );
  790 
  791 //--------------------------------------------------------------------------------------------------
  792 /**
  793  * Get the name of the node where the iterator is currently pointing.
  794  *
  795  * @return - LE_OK       Read was completed successfully.
  796  *         - LE_OVERFLOW Supplied string buffer was not large enough to hold the value.
  797  */
  798 //--------------------------------------------------------------------------------------------------
  799 le_result_t le_cfg_GetNodeName
  800 (
  801     le_cfg_IteratorRef_t iteratorRef,
  802         ///< [IN] Iterator object to use to read from the tree.
  803     const char* LE_NONNULL path,
  804         ///< [IN] Path to the target node. Can be an absolute path, or
  805         ///< a path relative from the iterator's current position.
  806     char* name,
  807         ///< [OUT] Read the name of the node object.
  808     size_t nameSize
  809         ///< [IN]
  810 );
  811 
  812 //--------------------------------------------------------------------------------------------------
  813 /**
  814  * Add handler function for EVENT 'le_cfg_Change'
  815  *
  816  * This event provides information on changes to the given node object, or any of it's children,
  817  * where a change could be either a read, write, create or delete operation.
  818  */
  819 //--------------------------------------------------------------------------------------------------
  820 le_cfg_ChangeHandlerRef_t le_cfg_AddChangeHandler
  821 (
  822     const char* LE_NONNULL newPath,
  823         ///< [IN] Path to the object to watch.
  824     le_cfg_ChangeHandlerFunc_t handlerPtr,
  825         ///< [IN] Handler to receive change notification
  826     void* contextPtr
  827         ///< [IN]
  828 );
  829 
  830 //--------------------------------------------------------------------------------------------------
  831 /**
  832  * Remove handler function for EVENT 'le_cfg_Change'
  833  */
  834 //--------------------------------------------------------------------------------------------------
  835 void le_cfg_RemoveChangeHandler
  836 (
  837     le_cfg_ChangeHandlerRef_t handlerRef
  838         ///< [IN]
  839 );
  840 
  841 //--------------------------------------------------------------------------------------------------
  842 /**
  843  * Deletes the node specified by the path. If the node doesn't exist, nothing happens. All child
  844  * nodes are also deleted.
  845  *
  846  * If the path is empty, the iterator's current node is deleted.
  847  *
  848  * This function is only valid during a write transaction.
  849  */
  850 //--------------------------------------------------------------------------------------------------
  851 void le_cfg_DeleteNode
  852 (
  853     le_cfg_IteratorRef_t iteratorRef,
  854         ///< [IN] Iterator to use as a basis for the transaction.
  855     const char* LE_NONNULL path
  856         ///< [IN] Path to the target node. Can be an absolute path, or
  857         ///< a path relative from the iterator's current position.
  858 );
  859 
  860 //--------------------------------------------------------------------------------------------------
  861 /**
  862  * Check if the given node is empty. A node is also considered empty if it doesn't yet exist. A
  863  * node is also considered empty if it has no value or is a stem with no children.
  864  *
  865  * If the path is empty, the iterator's current node is queried for emptiness.
  866  *
  867  * Valid for both read and write transactions.
  868  *
  869  * @return A true if the node is considered empty, false if not.
  870  */
  871 //--------------------------------------------------------------------------------------------------
  872 bool le_cfg_IsEmpty
  873 (
  874     le_cfg_IteratorRef_t iteratorRef,
  875         ///< [IN] Iterator to use as a basis for the transaction.
  876     const char* LE_NONNULL path
  877         ///< [IN] Path to the target node. Can be an absolute path, or
  878         ///< a path relative from the iterator's current position.
  879 );
  880 
  881 //--------------------------------------------------------------------------------------------------
  882 /**
  883  * Clears out the node's value. If the node doesn't exist it will be created, and have no value.
  884  *
  885  * If the path is empty, the iterator's current node will be cleared. If the node is a stem
  886  * then all children will be removed from the tree.
  887  *
  888  * Only valid during a write transaction.
  889  */
  890 //--------------------------------------------------------------------------------------------------
  891 void le_cfg_SetEmpty
  892 (
  893     le_cfg_IteratorRef_t iteratorRef,
  894         ///< [IN] Iterator to use as a basis for the transaction.
  895     const char* LE_NONNULL path
  896         ///< [IN] Path to the target node. Can be an absolute path, or
  897         ///< a path relative from the iterator's current position.
  898 );
  899 
  900 //--------------------------------------------------------------------------------------------------
  901 /**
  902  * Checks to see if a given node in the config tree exists.
  903  *
  904  * @return True if the specified node exists in the tree. False if not.
  905  */
  906 //--------------------------------------------------------------------------------------------------
  907 bool le_cfg_NodeExists
  908 (
  909     le_cfg_IteratorRef_t iteratorRef,
  910         ///< [IN] Iterator to use as a basis for the transaction.
  911     const char* LE_NONNULL path
  912         ///< [IN] Path to the target node. Can be an absolute path, or
  913         ///< a path relative from the iterator's current position.
  914 );
  915 
  916 //--------------------------------------------------------------------------------------------------
  917 /**
  918  * Reads a string value from the config tree. If the value isn't a string, or if the node is
  919  * empty or doesn't exist, the default value will be returned.
  920  *
  921  * Valid for both read and write transactions.
  922  *
  923  * If the path is empty, the iterator's current node will be read.
  924  *
  925  * @return - LE_OK       - Read was completed successfully.
  926  *         - LE_OVERFLOW - Supplied string buffer was not large enough to hold the value.
  927  */
  928 //--------------------------------------------------------------------------------------------------
  929 le_result_t le_cfg_GetString
  930 (
  931     le_cfg_IteratorRef_t iteratorRef,
  932         ///< [IN] Iterator to use as a basis for the transaction.
  933     const char* LE_NONNULL path,
  934         ///< [IN] Path to the target node. Can be an absolute path,
  935         ///< or a path relative from the iterator's current
  936         ///< position.
  937     char* value,
  938         ///< [OUT] Buffer to write the value into.
  939     size_t valueSize,
  940         ///< [IN]
  941     const char* LE_NONNULL defaultValue
  942         ///< [IN] Default value to use if the original can't be
  943         ///<   read.
  944 );
  945 
  946 //--------------------------------------------------------------------------------------------------
  947 /**
  948  * Writes a string value to the config tree. Only valid during a write
  949  * transaction.
  950  *
  951  * If the path is empty, the iterator's current node will be set.
  952  */
  953 //--------------------------------------------------------------------------------------------------
  954 void le_cfg_SetString
  955 (
  956     le_cfg_IteratorRef_t iteratorRef,
  957         ///< [IN] Iterator to use as a basis for the transaction.
  958     const char* LE_NONNULL path,
  959         ///< [IN] Path to the target node. Can be an absolute path, or
  960         ///< a path relative from the iterator's current position.
  961     const char* LE_NONNULL value
  962         ///< [IN] Value to write.
  963 );
  964 
  965 //--------------------------------------------------------------------------------------------------
  966 /**
  967  *  Read a binary data from the config tree.  If the the node has a wrong type, is
  968  *  empty or doesn't exist, the default value will be returned.
  969  *
  970  *  Valid for both read and write transactions.
  971  *
  972  *  If the path is empty, the iterator's current node will be read.
  973  *
  974  *  \b Responds \b With:
  975  *
  976  *  This function will respond with one of the following values:
  977  *
  978  *          - LE_OK             - Read was completed successfully.
  979  *          - LE_FORMAT_ERROR   - if data can't be decoded.
  980  *          - LE_OVERFLOW       - Supplied buffer was not large enough to hold the value.
  981  */
  982 //--------------------------------------------------------------------------------------------------
  983 le_result_t le_cfg_GetBinary
  984 (
  985     le_cfg_IteratorRef_t iteratorRef,
  986         ///< [IN] Iterator to use as a basis for the transaction.
  987     const char* LE_NONNULL path,
  988         ///< [IN] Path to the target node. Can be an absolute path,
  989         ///< or a path relative from the iterator's current
  990         ///< position.
  991     uint8_t* valuePtr,
  992         ///< [OUT] Buffer to write the value into.
  993     size_t* valueSizePtr,
  994         ///< [INOUT]
  995     const uint8_t* defaultValuePtr,
  996         ///< [IN] Default value to use if the original can't be
  997         ///<   read.
  998     size_t defaultValueSize
  999         ///< [IN]
 1000 );
 1001 
 1002 //--------------------------------------------------------------------------------------------------
 1003 /**
 1004  *  Write a binary data to the config tree.  Only valid during a write
 1005  *  transaction.
 1006  *
 1007  *  If the path is empty, the iterator's current node will be set.
 1008  *
 1009  *  @note Binary data cannot be written to the 'system' tree.
 1010  */
 1011 //--------------------------------------------------------------------------------------------------
 1012 void le_cfg_SetBinary
 1013 (
 1014     le_cfg_IteratorRef_t iteratorRef,
 1015         ///< [IN] Iterator to use as a basis for the transaction.
 1016     const char* LE_NONNULL path,
 1017         ///< [IN] Path to the target node. Can be an absolute path, or
 1018         ///< a path relative from the iterator's current position.
 1019     const uint8_t* valuePtr,
 1020         ///< [IN] Value to write.
 1021     size_t valueSize
 1022         ///< [IN]
 1023 );
 1024 
 1025 //--------------------------------------------------------------------------------------------------
 1026 /**
 1027  * Reads a signed integer value from the config tree.
 1028  *
 1029  * If the underlying value is not an integer, the default value will be returned instead. The
 1030  * default value is also returned if the node does not exist or if it's empty.
 1031  *
 1032  * If the value is a floating point value, then it will be rounded and returned as an integer.
 1033  *
 1034  * Valid for both read and write transactions.
 1035  *
 1036  * If the path is empty, the iterator's current node will be read.
 1037  */
 1038 //--------------------------------------------------------------------------------------------------
 1039 int32_t le_cfg_GetInt
 1040 (
 1041     le_cfg_IteratorRef_t iteratorRef,
 1042         ///< [IN] Iterator to use as a basis for the transaction.
 1043     const char* LE_NONNULL path,
 1044         ///< [IN] Path to the target node. Can be an absolute path, or
 1045         ///< a path relative from the iterator's current position.
 1046     int32_t defaultValue
 1047         ///< [IN] Default value to use if the original can't be
 1048         ///<   read.
 1049 );
 1050 
 1051 //--------------------------------------------------------------------------------------------------
 1052 /**
 1053  * Writes a signed integer value to the config tree. Only valid during a
 1054  * write transaction.
 1055  *
 1056  * If the path is empty, the iterator's current node will be set.
 1057  */
 1058 //--------------------------------------------------------------------------------------------------
 1059 void le_cfg_SetInt
 1060 (
 1061     le_cfg_IteratorRef_t iteratorRef,
 1062         ///< [IN] Iterator to use as a basis for the transaction.
 1063     const char* LE_NONNULL path,
 1064         ///< [IN] Path to the target node. Can be an absolute path, or
 1065         ///< a path relative from the iterator's current position.
 1066     int32_t value
 1067         ///< [IN] Value to write.
 1068 );
 1069 
 1070 //--------------------------------------------------------------------------------------------------
 1071 /**
 1072  * Reads a 64-bit floating point value from the config tree.
 1073  *
 1074  * If the value is an integer then the value will be promoted to a float. Otherwise, if the
 1075  * underlying value is not a float or integer, the default value will be returned.
 1076  *
 1077  * If the path is empty, the iterator's current node will be read.
 1078  *
 1079  * @note Floating point values will only be stored up to 6 digits of precision.
 1080  */
 1081 //--------------------------------------------------------------------------------------------------
 1082 double le_cfg_GetFloat
 1083 (
 1084     le_cfg_IteratorRef_t iteratorRef,
 1085         ///< [IN] Iterator to use as a basis for the transaction.
 1086     const char* LE_NONNULL path,
 1087         ///< [IN] Path to the target node. Can be an absolute path, or
 1088         ///< a path relative from the iterator's current position.
 1089     double defaultValue
 1090         ///< [IN] Default value to use if the original can't be
 1091         ///<   read.
 1092 );
 1093 
 1094 //--------------------------------------------------------------------------------------------------
 1095 /**
 1096  * Writes a 64-bit floating point value to the config tree. Only valid
 1097  * during a write transaction.
 1098  *
 1099  * If the path is empty, the iterator's current node will be set.
 1100  *
 1101  * @note Floating point values will only be stored up to 6 digits of precision.
 1102  */
 1103 //--------------------------------------------------------------------------------------------------
 1104 void le_cfg_SetFloat
 1105 (
 1106     le_cfg_IteratorRef_t iteratorRef,
 1107         ///< [IN] Iterator to use as a basis for the transaction.
 1108     const char* LE_NONNULL path,
 1109         ///< [IN] Path to the target node. Can be an absolute path, or
 1110         ///< a path relative from the iterator's current position.
 1111     double value
 1112         ///< [IN] Value to write.
 1113 );
 1114 
 1115 //--------------------------------------------------------------------------------------------------
 1116 /**
 1117  * Reads a value from the tree as a boolean. If the node is empty or doesn't exist, the default
 1118  * value is returned. Default value is also returned if the node is a different type than
 1119  * expected.
 1120  *
 1121  * Valid for both read and write transactions.
 1122  *
 1123  * If the path is empty, the iterator's current node will be read.
 1124  */
 1125 //--------------------------------------------------------------------------------------------------
 1126 bool le_cfg_GetBool
 1127 (
 1128     le_cfg_IteratorRef_t iteratorRef,
 1129         ///< [IN] Iterator to use as a basis for the transaction.
 1130     const char* LE_NONNULL path,
 1131         ///< [IN] Path to the target node. Can be an absolute path, or
 1132         ///< a path relative from the iterator's current position.
 1133     bool defaultValue
 1134         ///< [IN] Default value to use if the original can't be
 1135         ///<   read.
 1136 );
 1137 
 1138 //--------------------------------------------------------------------------------------------------
 1139 /**
 1140  * Writes a boolean value to the config tree. Only valid during a write
 1141  * transaction.
 1142  *
 1143  * If the path is empty, the iterator's current node will be set.
 1144  */
 1145 //--------------------------------------------------------------------------------------------------
 1146 void le_cfg_SetBool
 1147 (
 1148     le_cfg_IteratorRef_t iteratorRef,
 1149         ///< [IN] Iterator to use as a basis for the transaction.
 1150     const char* LE_NONNULL path,
 1151         ///< [IN] Path to the target node. Can be an absolute path, or
 1152         ///< a path relative from the iterator's current position.
 1153     bool value
 1154         ///< [IN] Value to write.
 1155 );
 1156 
 1157 //--------------------------------------------------------------------------------------------------
 1158 /**
 1159  * Deletes the node specified by the path. If the node doesn't exist, nothing happens. All child
 1160  * nodes are also deleted.
 1161  */
 1162 //--------------------------------------------------------------------------------------------------
 1163 void le_cfg_QuickDeleteNode
 1164 (
 1165     const char* LE_NONNULL path
 1166         ///< [IN] Path to the node to delete.
 1167 );
 1168 
 1169 //--------------------------------------------------------------------------------------------------
 1170 /**
 1171  * Clears the current value of a node. If the node doesn't currently exist then it is created as a
 1172  * new empty node.
 1173  */
 1174 //--------------------------------------------------------------------------------------------------
 1175 void le_cfg_QuickSetEmpty
 1176 (
 1177     const char* LE_NONNULL path
 1178         ///< [IN] Absolute or relative path to read from.
 1179 );
 1180 
 1181 //--------------------------------------------------------------------------------------------------
 1182 /**
 1183  * Reads a string value from the config tree. If the value isn't a string, or if the node is
 1184  * empty or doesn't exist, the default value will be returned.
 1185  *
 1186  * @return - LE_OK       - Commit was completed successfully.
 1187  *         - LE_OVERFLOW - Supplied string buffer was not large enough to hold the value.
 1188  */
 1189 //--------------------------------------------------------------------------------------------------
 1190 le_result_t le_cfg_QuickGetString
 1191 (
 1192     const char* LE_NONNULL path,
 1193         ///< [IN] Path to read from.
 1194     char* value,
 1195         ///< [OUT] Value read from the requested node.
 1196     size_t valueSize,
 1197         ///< [IN]
 1198     const char* LE_NONNULL defaultValue
 1199         ///< [IN] Default value to use if the original can't be read.
 1200 );
 1201 
 1202 //--------------------------------------------------------------------------------------------------
 1203 /**
 1204  * Writes a string value to the config tree.
 1205  */
 1206 //--------------------------------------------------------------------------------------------------
 1207 void le_cfg_QuickSetString
 1208 (
 1209     const char* LE_NONNULL path,
 1210         ///< [IN] Path to the value to write.
 1211     const char* LE_NONNULL value
 1212         ///< [IN] Value to write.
 1213 );
 1214 
 1215 //--------------------------------------------------------------------------------------------------
 1216 /**
 1217  * Reads a binary data from the config tree. If the node type is different, or if the node is
 1218  * empty or doesn't exist, the default value will be returned.
 1219  *
 1220  * @return - LE_OK              - Commit was completed successfully.
 1221  *         - LE_FORMAT_ERROR    - if data can't be decoded.
 1222  *         - LE_OVERFLOW        - Supplied buffer was not large enough to hold the value.
 1223  */
 1224 //--------------------------------------------------------------------------------------------------
 1225 le_result_t le_cfg_QuickGetBinary
 1226 (
 1227     const char* LE_NONNULL path,
 1228         ///< [IN] Path to the target node.
 1229     uint8_t* valuePtr,
 1230         ///< [OUT] Buffer to write the value into.
 1231     size_t* valueSizePtr,
 1232         ///< [INOUT]
 1233     const uint8_t* defaultValuePtr,
 1234         ///< [IN] Default value to use if the original can't be
 1235         ///<   read.
 1236     size_t defaultValueSize
 1237         ///< [IN]
 1238 );
 1239 
 1240 //--------------------------------------------------------------------------------------------------
 1241 /**
 1242  * Writes a binary data to the config tree.
 1243  */
 1244 //--------------------------------------------------------------------------------------------------
 1245 void le_cfg_QuickSetBinary
 1246 (
 1247     const char* LE_NONNULL path,
 1248         ///< [IN] Path to the target node.
 1249     const uint8_t* valuePtr,
 1250         ///< [IN] Value to write.
 1251     size_t valueSize
 1252         ///< [IN]
 1253 );
 1254 
 1255 //--------------------------------------------------------------------------------------------------
 1256 /**
 1257  * Reads a signed integer value from the config tree. If the value is a floating point
 1258  * value, then it will be rounded and returned as an integer. Otherwise If the underlying value is
 1259  * not an integer or a float, the default value will be returned instead.
 1260  *
 1261  * If the value is empty or the node doesn't exist, the default value is returned instead.
 1262  */
 1263 //--------------------------------------------------------------------------------------------------
 1264 int32_t le_cfg_QuickGetInt
 1265 (
 1266     const char* LE_NONNULL path,
 1267         ///< [IN] Path to the value to write.
 1268     int32_t defaultValue
 1269         ///< [IN] Default value to use if the original can't be read.
 1270 );
 1271 
 1272 //--------------------------------------------------------------------------------------------------
 1273 /**
 1274  * Writes a signed integer value to the config tree.
 1275  */
 1276 //--------------------------------------------------------------------------------------------------
 1277 void le_cfg_QuickSetInt
 1278 (
 1279     const char* LE_NONNULL path,
 1280         ///< [IN] Path to the value to write.
 1281     int32_t value
 1282         ///< [IN] Value to write.
 1283 );
 1284 
 1285 //--------------------------------------------------------------------------------------------------
 1286 /**
 1287  * Reads a 64-bit floating point value from the config tree. If the value is an integer,
 1288  * then it is promoted to a float. Otherwise, if the underlying value is not a float, or an
 1289  * integer the default value will be returned.
 1290  *
 1291  * If the value is empty or the node doesn't exist, the default value is returned.
 1292  *
 1293  * @note Floating point values will only be stored up to 6 digits of precision.
 1294  */
 1295 //--------------------------------------------------------------------------------------------------
 1296 double le_cfg_QuickGetFloat
 1297 (
 1298     const char* LE_NONNULL path,
 1299         ///< [IN] Path to the value to write.
 1300     double defaultValue
 1301         ///< [IN] Default value to use if the original can't be read.
 1302 );
 1303 
 1304 //--------------------------------------------------------------------------------------------------
 1305 /**
 1306  * Writes a 64-bit floating point value to the config tree.
 1307  *
 1308  * @note Floating point values will only be stored up to 6 digits of precision.
 1309  */
 1310 //--------------------------------------------------------------------------------------------------
 1311 void le_cfg_QuickSetFloat
 1312 (
 1313     const char* LE_NONNULL path,
 1314         ///< [IN] Path to the value to write.
 1315     double value
 1316         ///< [IN] Value to write.
 1317 );
 1318 
 1319 //--------------------------------------------------------------------------------------------------
 1320 /**
 1321  * Reads a value from the tree as a boolean. If the node is empty or doesn't exist, the default
 1322  * value is returned. This is also true if the node is a different type than expected.
 1323  *
 1324  * If the value is empty or the node doesn't exist, the default value is returned instead.
 1325  */
 1326 //--------------------------------------------------------------------------------------------------
 1327 bool le_cfg_QuickGetBool
 1328 (
 1329     const char* LE_NONNULL path,
 1330         ///< [IN] Path to the value to write.
 1331     bool defaultValue
 1332         ///< [IN] Default value to use if the original can't be read.
 1333 );
 1334 
 1335 //--------------------------------------------------------------------------------------------------
 1336 /**
 1337  * Writes a boolean value to the config tree.
 1338  */
 1339 //--------------------------------------------------------------------------------------------------
 1340 void le_cfg_QuickSetBool
 1341 (
 1342     const char* LE_NONNULL path,
 1343         ///< [IN] Path to the value to write.
 1344     bool value
 1345         ///< [IN] Value to write.
 1346 );
 1347 
 1348 #endif // LE_CFG_INTERFACE_H_INCLUDE_GUARD
le_cfg_DisconnectService
void le_cfg_DisconnectService(void)
le_cfg_QuickGetFloat
double le_cfg_QuickGetFloat(const char *LE_NONNULL path, double defaultValue)
le_result_t
le_result_t
Definition: le_basics.h:35
le_cfg_GetString
le_result_t le_cfg_GetString(le_cfg_IteratorRef_t iteratorRef, const char *LE_NONNULL path, char *value, size_t valueSize, const char *LE_NONNULL defaultValue)
LE_CFG_TYPE_FLOAT
64-bit floating point value. 
Definition: le_cfg_interface.h:543
le_cfg_CreateWriteTxn
le_cfg_IteratorRef_t le_cfg_CreateWriteTxn(const char *LE_NONNULL basePath)
le_cfg_QuickSetBinary
void le_cfg_QuickSetBinary(const char *LE_NONNULL path, const uint8_t *valuePtr, size_t valueSize)
le_cfg_ChangeHandlerRef_t
struct le_cfg_ChangeHandler * le_cfg_ChangeHandlerRef_t
Definition: le_cfg_interface.h:558
le_cfg_GoToNextSibling
le_result_t le_cfg_GoToNextSibling(le_cfg_IteratorRef_t iteratorRef)
le_cfg_GetNodeType
le_cfg_nodeType_t le_cfg_GetNodeType(le_cfg_IteratorRef_t iteratorRef, const char *LE_NONNULL path)
le_cfg_GetNodeName
le_result_t le_cfg_GetNodeName(le_cfg_IteratorRef_t iteratorRef, const char *LE_NONNULL path, char *name, size_t nameSize)
le_cfg_DisconnectHandler_t
void(* le_cfg_DisconnectHandler_t)(void *)
Definition: le_cfg_interface.h:408
le_cfg_QuickSetInt
void le_cfg_QuickSetInt(const char *LE_NONNULL path, int32_t value)
le_cfg_IteratorRef_t
struct le_cfg_Iterator * le_cfg_IteratorRef_t
Definition: le_cfg_interface.h:525
le_cfg_GoToNode
void le_cfg_GoToNode(le_cfg_IteratorRef_t iteratorRef, const char *LE_NONNULL newPath)
le_cfg_QuickGetBinary
le_result_t le_cfg_QuickGetBinary(const char *LE_NONNULL path, uint8_t *valuePtr, size_t *valueSizePtr, const uint8_t *defaultValuePtr, size_t defaultValueSize)
le_cfg_QuickSetBool
void le_cfg_QuickSetBool(const char *LE_NONNULL path, bool value)
LE_CFG_TYPE_EMPTY
A node with no value. 
Definition: le_cfg_interface.h:535
le_cfg_ConnectService
void le_cfg_ConnectService(void)
LE_CFG_TYPE_STRING
A string encoded as utf8. 
Definition: le_cfg_interface.h:537
le_cfg_QuickGetString
le_result_t le_cfg_QuickGetString(const char *LE_NONNULL path, char *value, size_t valueSize, const char *LE_NONNULL defaultValue)
le_cfg_QuickSetEmpty
void le_cfg_QuickSetEmpty(const char *LE_NONNULL path)
le_cfg_QuickGetBool
bool le_cfg_QuickGetBool(const char *LE_NONNULL path, bool defaultValue)
le_cfg_GetFloat
double le_cfg_GetFloat(le_cfg_IteratorRef_t iteratorRef, const char *LE_NONNULL path, double defaultValue)
LE_CFG_TYPE_BOOL
Boolean value. 
Definition: le_cfg_interface.h:539
le_cfg_SetBinary
void le_cfg_SetBinary(le_cfg_IteratorRef_t iteratorRef, const char *LE_NONNULL path, const uint8_t *valuePtr, size_t valueSize)
le_cfg_SetEmpty
void le_cfg_SetEmpty(le_cfg_IteratorRef_t iteratorRef, const char *LE_NONNULL path)
le_cfg_CommitTxn
void le_cfg_CommitTxn(le_cfg_IteratorRef_t iteratorRef)
le_cfg_nodeType_t
le_cfg_nodeType_t
Definition: le_cfg_interface.h:533
le_cfg_NodeExists
bool le_cfg_NodeExists(le_cfg_IteratorRef_t iteratorRef, const char *LE_NONNULL path)
LE_CFG_TYPE_DOESNT_EXIST
Node doesn&#39;t exist. 
Definition: le_cfg_interface.h:547
le_cfg_GetBinary
le_result_t le_cfg_GetBinary(le_cfg_IteratorRef_t iteratorRef, const char *LE_NONNULL path, uint8_t *valuePtr, size_t *valueSizePtr, const uint8_t *defaultValuePtr, size_t defaultValueSize)
le_cfg_TryConnectService
le_result_t le_cfg_TryConnectService(void)
le_cfg_ChangeHandlerFunc_t
void(* le_cfg_ChangeHandlerFunc_t)(void *contextPtr)
Definition: le_cfg_interface.h:567
legato.h
le_cfg_AddChangeHandler
le_cfg_ChangeHandlerRef_t le_cfg_AddChangeHandler(const char *LE_NONNULL newPath, le_cfg_ChangeHandlerFunc_t handlerPtr, void *contextPtr)
le_cfg_SetServerDisconnectHandler
void le_cfg_SetServerDisconnectHandler(le_cfg_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_cfg_SetInt
void le_cfg_SetInt(le_cfg_IteratorRef_t iteratorRef, const char *LE_NONNULL path, int32_t value)
le_cfg_QuickSetFloat
void le_cfg_QuickSetFloat(const char *LE_NONNULL path, double value)
le_cfg_CancelTxn
void le_cfg_CancelTxn(le_cfg_IteratorRef_t iteratorRef)
le_cfg_SetFloat
void le_cfg_SetFloat(le_cfg_IteratorRef_t iteratorRef, const char *LE_NONNULL path, double value)
LE_CFG_TYPE_INT
Signed 32-bit. 
Definition: le_cfg_interface.h:541
le_cfg_IsEmpty
bool le_cfg_IsEmpty(le_cfg_IteratorRef_t iteratorRef, const char *LE_NONNULL path)
le_cfg_DeleteNode
void le_cfg_DeleteNode(le_cfg_IteratorRef_t iteratorRef, const char *LE_NONNULL path)
le_cfg_GoToFirstChild
le_result_t le_cfg_GoToFirstChild(le_cfg_IteratorRef_t iteratorRef)
le_cfg_CreateReadTxn
le_cfg_IteratorRef_t le_cfg_CreateReadTxn(const char *LE_NONNULL basePath)
le_cfg_QuickDeleteNode
void le_cfg_QuickDeleteNode(const char *LE_NONNULL path)
le_cfg_QuickSetString
void le_cfg_QuickSetString(const char *LE_NONNULL path, const char *LE_NONNULL value)
le_cfg_SetString
void le_cfg_SetString(le_cfg_IteratorRef_t iteratorRef, const char *LE_NONNULL path, const char *LE_NONNULL value)
le_cfg_GetPath
le_result_t le_cfg_GetPath(le_cfg_IteratorRef_t iteratorRef, const char *LE_NONNULL path, char *pathBuffer, size_t pathBufferSize)
le_cfg_RemoveChangeHandler
void le_cfg_RemoveChangeHandler(le_cfg_ChangeHandlerRef_t handlerRef)
le_cfg_GetBool
bool le_cfg_GetBool(le_cfg_IteratorRef_t iteratorRef, const char *LE_NONNULL path, bool defaultValue)
le_cfg_GoToParent
le_result_t le_cfg_GoToParent(le_cfg_IteratorRef_t iteratorRef)
le_cfg_GetInt
int32_t le_cfg_GetInt(le_cfg_IteratorRef_t iteratorRef, const char *LE_NONNULL path, int32_t defaultValue)
le_cfg_SetBool
void le_cfg_SetBool(le_cfg_IteratorRef_t iteratorRef, const char *LE_NONNULL path, bool value)
LE_CFG_TYPE_STEM
Non-leaf node, this node is the parent of other nodes. 
Definition: le_cfg_interface.h:545
le_cfg_QuickGetInt
int32_t le_cfg_QuickGetInt(const char *LE_NONNULL path, int32_t defaultValue)