le_cfg_interface.h

    1 /*
    2  * ====================== WARNING ======================
    3  *
    4  * THE CONTENTS OF THIS FILE HAVE BEEN AUTO-GENERATED.
    5  * DO NOT MODIFY IN ANY WAY.
    6  *
    7  * ====================== WARNING ======================
    8  */
    9 
   10 /**
   11  * @page c_config Config Tree API
   12  *
   13  * @ref le_cfg_interface.h "API Reference"
   14  *
   15  * <HR>
   16  *
   17  * The Config Tree API is used by apps to read and write their specific configurations.
   18  * Each app is given an isolated tree. The system utilities
   19  * store their configuration in the @c root tree.
   20  *
   21  * Paths in the tree look like traditional Unix style paths like this:
   22  *
   23  * @code /path/to/my/value @endcode
   24  *
   25  * The path root is the root of the tree where the app has been given access. If the
   26  * app has permission to access another tree, the path can also include the name
   27  * of the other tree, followed by a colon.
   28  *
   29  * @code secondTree:/path/to/my/value @endcode
   30  *
   31  * In this case, a value named @c value is read from the tree named @c secondTree
   32  *
   33  * The tree is broken down into stems and leaves.
   34  *
   35  * A stem is a node that has at least one child
   36  * node. A leaf has no children, but can hold a value.
   37  *
   38  * The config tree supports string, signed integer, boolean, floating point, and empty
   39  * values. It's recommended to store anything more complex using stems and leaves, which enhances
   40  * readablity and debugging. It also sidesteps nasty cross platform alignment issues.
   41  *
   42  * @todo Talk about the treeConfig, user limits, tree name, tree access. Global timeouts.
   43  *
   44  * @section cfg_transaction Read and Write Transactions
   45  *
   46  * The config tree uses simple transactions to work with its data. Both read
   47  * and write transactions are supported. Use read transactions to ensure you can
   48  * atomically read multiple values from your configuration while keeping consistency
   49  * with third parties trying to write data.
   50  *
   51  * To prevent a single client from locking out other clients, read and
   52  * write transactions have their own configurable timeout.
   53  *
   54  * During a write transaction, both reading and writing are allowed. If you
   55  * write a value during a transaction and read from that value again, you will get the same value
   56  * you wrote. Third party clients will continue to see the old value. It's not until you commit
   57  * your transaction that third parties will begin to see your updated value.
   58  *
   59  * During read transactions, writes are not permitted and are thrown away.
   60  *
   61  * Transactions are started by creating an iterator. Either a read or write iterator can be
   62  * created. To end the transaction, you can  delete the iterator, cancelling the
   63  * transaction. Or,for write transactions, you can commit the iterator.
   64  *
   65  * You can have multiple read transactions against the tree. They won't
   66  * block other transactions from being creating. A read transaction won't block creating a write
   67  * transaction either. A read transaction only blocks a write transaction from being
   68  * comitted to the tree.
   69  *
   70  * A write transaction in progress will also block creating another write transaction.
   71  * If a write transaction is in progress when the request for another write transaction comes in,
   72  * the secondary request will be blocked. This secondary request will remain blocked until the
   73  * first transaction has been comitted or has timed out. The transaction timeout default is 30
   74  * seconds. You can extend the timeout by setting a value (in seconds) in
   75  * @c configTree/transactionTimeout.
   76  *
   77  * @section cfg_iteration Iterating the Tree
   78  *
   79  * This code sample shows how to iterate a specified node and print its contents:
   80  *
   81  * @code
   82  * static void PrintNode(le_cfg_IteratorRef_t iteratorRef)
   83  * {
   84  *     do
   85  *     {
   86  *         char stringBuffer[MAX_CFG_STRING] = { 0 };
   87  *
   88  *         le_cfg_GetNodeName(iteratorRef, "", stringBuffer, sizeof(stringBuffer));
   89  *
   90  *         switch (le_cfg_GetNodeType(iteratorRef, ""))
   91  *         {
   92  *             case LE_CFG_TYPE_STEM:
   93  *                 {
   94  *                     printf("%s/\n", stringBuffer);
   95  *
   96  *                     if (le_cfg_GoToFirstChild(iteratorRef) == LE_OK)
   97  *                     {
   98  *                         PrintNode(iteratorRef);
   99  *                         le_cfg_GoToNode(iteratorRef, "..");
  100  *                     }
  101  *                 }
  102  *                 break;
  103  *
  104  *             case LE_CFG_TYPE_EMPTY:
  105  *                 printf("%s = *empty*\n", stringBuffer);
  106  *                 break;
  107  *
  108  *             case LE_CFG_TYPE_BOOL:
  109  *                 printf("%s = %s\n",
  110  *                        stringBuffer,
  111  *                        (le_cfg_GetBool(iteratorRef, "", false) ? "true" : "false"));
  112  *                 break;
  113  *
  114  *             case LE_CFG_TYPE_INT:
  115  *                 printf("%s = %d\n", stringBuffer, le_cfg_GetInt(iteratorRef, "", 0));
  116  *                 break;
  117  *
  118  *             case LE_CFG_TYPE_FLOAT:
  119  *                 printf("%s = %f\n", stringBuffer, le_cfg_GetFloat(iteratorRef, "", 0.0));
  120  *                 break;
  121  *
  122  *             case LE_CFG_TYPE_STRING:
  123  *                 printf("%s = ", stringBuffer);
  124  *                 LE_ASSERT(le_cfg_GetString(iteratorRef,
  125  *                                            "",
  126  *                                            stringBuffer,
  127  *                                            sizeof(stringBuffer),
  128  *                                            "") == LE_OK);
  129  *                 printf("%s\n", stringBuffer);
  130  *                 break;
  131  *
  132  *             case LE_CFG_TYPE_DOESNT_EXIST:
  133  *                 printf("%s = ** DENIED **\n", stringBuffer);
  134  *                 break;
  135  *         }
  136  *     }
  137  *     while (le_cfg_GoToNextSibling(iteratorRef) == LE_OK);
  138  * }
  139  *
  140  *
  141  * le_cfg_IteratorRef_t iteratorRef = le_cfg_CreateReadTxn("/path/to/my/location");
  142  *
  143  * PrintNode(iteratorRef);
  144  * le_cfg_CancelTxn(iteratorRef);
  145  *
  146  *
  147  * @endcode
  148  *
  149  *
  150  * @section cfg_transactWrite Writing Configuration Data
  151  *
  152  * This code sample uses a write transaction to update a target's IP address
  153  * so the data is written atomically.
  154  *
  155  * @code
  156  * void SetIp4Static
  157  * (
  158  *     le_cfg_IteratorRef_t iteratorRef,
  159  *     const char* interfaceNamePtr,
  160  *     const char* ipAddrPtr,
  161  *     const char* netMaskPtr
  162  * )
  163  * {
  164  *     // Change current tree position to the base ip4 node.
  165  *     char nameBuffer[MAX_CFG_STRING] = { 0 };
  166  *
  167  *     sprintf(nameBuffer, "/system/%s/ip4", interfaceNamePtr);
  168  *
  169  *     le_cfg_GoToNode(iteratorRef, nameBuffer);
  170  *
  171  *     le_cfg_SetString(iteratorRef, "addr", ipAddrPtr);
  172  *     le_cfg_SetString(iteratorRef, "mask", netMaskPtr);
  173  *
  174  *     le_cfg_CommitTxn(iteratorRef);
  175  * }
  176  * @endcode
  177  *
  178  *
  179  * @section cfg_transactRead Reading Configuration Data
  180  *
  181  * This is a code sample of a read transaction.
  182  *
  183  * @code
  184  * le_result_t GetIp4Static
  185  * (
  186  *     le_cfg_IteratorRef_t iteratorRef,
  187  *     const char* interfaceNamePtr,
  188  *     char* ipAddrPtr,
  189  *     size_t ipAddrSize,
  190  *     char* netMaskPtr,
  191  *     size_t netMaskSize
  192  * )
  193  * {
  194  *     // Change current tree position to the base ip4 node.
  195  *     char nameBuffer[MAX_CFG_STRING] = { 0 };
  196  *
  197  *     sprintf(nameBuffer, "/system/%s/ip4", interfaceNamePtr);
  198  *
  199  *     if (le_cfg_NodeExists(iteratorRef, nameBuffer) == false)
  200  *     {
  201  *         LE_WARN("Configuration not found.");
  202  *         return LE_NOT_FOUND;
  203  *     }
  204  *
  205  *     le_cfg_GoToNode(iteratorRef, nameBuffer);
  206  *
  207  *     le_cfg_GetString(iteratorRef, "addr", ipAddrPtr, ipAddrSize, "");
  208  *     le_cfg_GetString(iteratorRef, "mask", netMaskPtr, netMaskSize, "");
  209  *
  210  *     return LE_OK;
  211  * }
  212  * @endcode
  213  *
  214  *
  215  * @section cfg_quick Working without Transactions
  216  *
  217  * It's possible to ignore iterators and transactions entirely (e.g., if all you need to do
  218  * is read or write some simple values in the tree).
  219  *
  220  * The non-transactional reads and writes work almost identically to the transactional versions.
  221  * They just don't explictly take an iterator object. The "quick" functions internally use an
  222  * implicit transaction. This implicit transaction wraps one get or set, and does not protect
  223  * your code from other activity in the system.
  224  *
  225  * Because these functions don't take an explicit transaction, they can't work with relative
  226  * paths. If a relative path is given, the path will be considered relative to the tree's root.
  227  *
  228  * Translating this to a "quick" (non-transactional) example looks like this:
  229  *
  230  * @code
  231  * void ClearIpInfo
  232  * (
  233  *     const char* interfaceNamePtr
  234  * )
  235  * {
  236  *     char pathBuffer[MAX_CFG_STRING] = { 0 };
  237  *
  238  *     sprintf(pathBuffer, "/system/%s/ip4/", interfaceNamePtr);
  239  *     le_cfg_QuickDeleteNode(pathBuffer);
  240  * }
  241  * @endcode
  242  *
  243  * @note Because each read is independant, there's no guarantee of
  244  * consistency between them. If another process changes one of the values while you
  245  * read/write the other, the two values could be read out of sync.
  246  *
  247  * <HR>
  248  *
  249  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
  250  */
  251 /**
  252  * @file le_cfg_interface.h
  253  *
  254  * Legato @ref c_config include file.
  255  *
  256  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
  257  */
  258 
  259 #ifndef LE_CFG_INTERFACE_H_INCLUDE_GUARD
  260 #define LE_CFG_INTERFACE_H_INCLUDE_GUARD
  261 
  262 
  263 #include "legato.h"
  264 
  265 //--------------------------------------------------------------------------------------------------
  266 /**
  267  *
  268  * Connect the current client thread to the service providing this API. Block until the service is
  269  * available.
  270  *
  271  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  272  * called before any other functions in this API.  Normally, ConnectService is automatically called
  273  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  274  *
  275  * This function is created automatically.
  276  */
  277 //--------------------------------------------------------------------------------------------------
  278 void le_cfg_ConnectService
  279 (
  280     void
  281 );
  282 
  283 //--------------------------------------------------------------------------------------------------
  284 /**
  285  *
  286  * Try to connect the current client thread to the service providing this API. Return with an error
  287  * if the service is not available.
  288  *
  289  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  290  * called before any other functions in this API.  Normally, ConnectService is automatically called
  291  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  292  *
  293  * This function is created automatically.
  294  *
  295  * @return
  296  *  - LE_OK if the client connected successfully to the service.
  297  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is bound.
  298  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  299  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  300  */
  301 //--------------------------------------------------------------------------------------------------
  302 le_result_t le_cfg_TryConnectService
  303 (
  304     void
  305 );
  306 
  307 //--------------------------------------------------------------------------------------------------
  308 /**
  309  *
  310  * Disconnect the current client thread from the service providing this API.
  311  *
  312  * Normally, this function doesn't need to be called. After this function is called, there's no
  313  * longer a connection to the service, and the functions in this API can't be used. For details, see
  314  * @ref apiFilesC_client.
  315  *
  316  * This function is created automatically.
  317  */
  318 //--------------------------------------------------------------------------------------------------
  319 void le_cfg_DisconnectService
  320 (
  321     void
  322 );
  323 
  324 
  325 //--------------------------------------------------------------------------------------------------
  326 /**
  327  * Reference to a tree iterator object.
  328  */
  329 //--------------------------------------------------------------------------------------------------
  330 typedef struct le_cfg_Iterator* le_cfg_IteratorRef_t;
  331 
  332 
  333 //--------------------------------------------------------------------------------------------------
  334 /**
  335  * Identifies the type of node.
  336  */
  337 //--------------------------------------------------------------------------------------------------
  338 typedef enum
  339 {
  340     LE_CFG_TYPE_EMPTY = 0,
  341         ///< A node with no value.
  342 
  343     LE_CFG_TYPE_STRING = 1,
  344         ///< A string encoded as utf8.
  345 
  346     LE_CFG_TYPE_BOOL = 2,
  347         ///< Boolean value.
  348 
  349     LE_CFG_TYPE_INT = 3,
  350         ///< Signed 32-bit.
  351 
  352     LE_CFG_TYPE_FLOAT = 4,
  353         ///< 64-bit floating point value.
  354 
  355     LE_CFG_TYPE_STEM = 5,
  356         ///< Non-leaf node, this node is the parent of other nodes.
  357 
  358     LE_CFG_TYPE_DOESNT_EXIST = 6
  359         ///< Node doesn't exist.
  360 }
  361 le_cfg_nodeType_t;
  362 
  363 
  364 //--------------------------------------------------------------------------------------------------
  365 /**
  366  * Length of the strings used by this API.
  367  */
  368 //--------------------------------------------------------------------------------------------------
  369 #define LE_CFG_STR_LEN 511
  370 
  371 
  372 //--------------------------------------------------------------------------------------------------
  373 /**
  374  * Length of the strings used by this API, including the trailing NULL.
  375  */
  376 //--------------------------------------------------------------------------------------------------
  377 #define LE_CFG_STR_LEN_BYTES 512
  378 
  379 
  380 //--------------------------------------------------------------------------------------------------
  381 /**
  382  * Allowed length of a node name.
  383  */
  384 //--------------------------------------------------------------------------------------------------
  385 #define LE_CFG_NAME_LEN 63
  386 
  387 
  388 //--------------------------------------------------------------------------------------------------
  389 /**
  390  * The node name length, including a trailing NULL.
  391  */
  392 //--------------------------------------------------------------------------------------------------
  393 #define LE_CFG_NAME_LEN_BYTES 64
  394 
  395 
  396 //--------------------------------------------------------------------------------------------------
  397 /**
  398  * Reference type used by Add/Remove functions for EVENT 'le_cfg_Change'
  399  */
  400 //--------------------------------------------------------------------------------------------------
  401 typedef struct le_cfg_ChangeHandler* le_cfg_ChangeHandlerRef_t;
  402 
  403 
  404 //--------------------------------------------------------------------------------------------------
  405 /**
  406  * Handler for node change notifications.
  407  *
  408  * @param contextPtr
  409  */
  410 //--------------------------------------------------------------------------------------------------
  411 typedef void (*le_cfg_ChangeHandlerFunc_t)
  412 (
  413     void* contextPtr
  414 );
  415 
  416 //--------------------------------------------------------------------------------------------------
  417 /**
  418  * Create a read transaction and open a new iterator for traversing the config tree.
  419  *
  420  * @note This action creates a read lock on the given tree, which will start a read-timeout.
  421  *        Once the read timeout expires, all active read iterators on that tree will be
  422  *        expired and the clients will be killed.
  423  *
  424  * @note A tree transaction is global to that tree; a long-held read transaction will block other
  425  *        user's write transactions from being comitted.
  426  *
  427  * @return This will return a newly created iterator reference.
  428  */
  429 //--------------------------------------------------------------------------------------------------
  430 le_cfg_IteratorRef_t le_cfg_CreateReadTxn
  431 (
  432     const char* basePath
  433         ///< [IN] Path to the location to create the new iterator.
  434 );
  435 
  436 //--------------------------------------------------------------------------------------------------
  437 /**
  438  * Create a write transaction and open a new iterator for both reading and writing.
  439  *
  440  * @note This action creates a write transaction. If the app holds the iterator for
  441  *        longer than the configured write transaction timeout, the iterator will cancel the
  442  *        transaction. Other reads will fail to return data, and all writes will be thrown
  443  *        away.
  444  *
  445  * @note A tree transaction is global to that tree; a long-held write transaction will block
  446  *       other user's write transactions from being started. Other trees in the system
  447  *       won't be affected.
  448  *
  449  * @return This will return a newly created iterator reference.
  450  */
  451 //--------------------------------------------------------------------------------------------------
  452 le_cfg_IteratorRef_t le_cfg_CreateWriteTxn
  453 (
  454     const char* basePath
  455         ///< [IN] Path to the location to create the new iterator.
  456 );
  457 
  458 //--------------------------------------------------------------------------------------------------
  459 /**
  460  * Close the write iterator and commit the write transaction. This updates the config tree
  461  * with all of the writes that occured using the iterator.
  462  *
  463  * @note This operation will also delete the iterator object.
  464  */
  465 //--------------------------------------------------------------------------------------------------
  466 void le_cfg_CommitTxn
  467 (
  468     le_cfg_IteratorRef_t iteratorRef
  469         ///< [IN] Iterator object to commit.
  470 );
  471 
  472 //--------------------------------------------------------------------------------------------------
  473 /**
  474  * Close and free the given iterator object. If the iterator is a write iterator, the transaction
  475  * will be canceled. If the iterator is a read iterator, the transaction will be closed.
  476  *
  477  * @note This operation will also delete the iterator object.
  478  */
  479 //--------------------------------------------------------------------------------------------------
  480 void le_cfg_CancelTxn
  481 (
  482     le_cfg_IteratorRef_t iteratorRef
  483         ///< [IN] Iterator object to close.
  484 );
  485 
  486 //--------------------------------------------------------------------------------------------------
  487 /**
  488  * Change the node where the iterator is pointing. The path passed can be an absolute or a
  489  * relative path from the iterators current location.
  490  *
  491  * The target node does not need to exist. Writing a value to a non-existant node will
  492  * automatically create that node and any ancestor nodes (parent, parent's parent, etc.) that
  493  * also don't exist.
  494  */
  495 //--------------------------------------------------------------------------------------------------
  496 void le_cfg_GoToNode
  497 (
  498     le_cfg_IteratorRef_t iteratorRef,
  499         ///< [IN] Iterator to move.
  500 
  501     const char* newPath
  502         ///< [IN] Absolute or relative path from the current location.
  503 );
  504 
  505 //--------------------------------------------------------------------------------------------------
  506 /**
  507  * Move the iterator to the parent of the node.
  508  *
  509  * @return Return code will be one of the following values:
  510  *
  511  *         - LE_OK        - Commit was completed successfully.
  512  *         - LE_NOT_FOUND - Current node is the root node: has no parent.
  513  */
  514 //--------------------------------------------------------------------------------------------------
  515 le_result_t le_cfg_GoToParent
  516 (
  517     le_cfg_IteratorRef_t iteratorRef
  518         ///< [IN] Iterator to move.
  519 );
  520 
  521 //--------------------------------------------------------------------------------------------------
  522 /**
  523  * Move the iterator to the the first child of the node where the iterator is currently pointed.
  524  *
  525  * For read iterators without children, this function will fail. If the iterator is a write
  526  * iterator, then a new node is automatically created. If this node or newly created
  527  * children of this node are not written to, then this node will not persist even if the iterator is
  528  * comitted.
  529  *
  530  * @return Return code will be one of the following values:
  531  *
  532  *         - LE_OK        - Move was completed successfully.
  533  *         - LE_NOT_FOUND - The given node has no children.
  534  */
  535 //--------------------------------------------------------------------------------------------------
  536 le_result_t le_cfg_GoToFirstChild
  537 (
  538     le_cfg_IteratorRef_t iteratorRef
  539         ///< [IN] Iterator object to move.
  540 );
  541 
  542 //--------------------------------------------------------------------------------------------------
  543 /**
  544  * Jump the iterator to the next child node of the current node. Assuming the following tree:
  545  *
  546  * @code
  547  * baseNode/
  548  *   childA/
  549  *     valueA
  550  *     valueB
  551  * @endcode
  552  *
  553  * If the iterator is moved to the path, "/baseNode/childA/valueA". After the first
  554  * GoToNextSibling the iterator will be pointing at valueB. A second call to GoToNextSibling
  555  * will cause the function to return LE_NOT_FOUND.
  556  *
  557  * @return Returns one of the following values:
  558  *
  559  *         - LE_OK            - Commit was completed successfully.
  560  *         - LE_NOT_FOUND     - Iterator has reached the end of the current list of siblings.
  561  *                              Also returned if the the current node has no siblings.
  562  */
  563 //--------------------------------------------------------------------------------------------------
  564 le_result_t le_cfg_GoToNextSibling
  565 (
  566     le_cfg_IteratorRef_t iteratorRef
  567         ///< [IN] Iterator to iterate.
  568 );
  569 
  570 //--------------------------------------------------------------------------------------------------
  571 /**
  572  * Get path to the node where the iterator is currently pointed.
  573  *
  574  * Assuming the following tree:
  575  *
  576  * @code
  577  * baseNode/
  578  *   childA/
  579  *     valueA
  580  *     valueB
  581  * @endcode
  582  *
  583  * If the iterator was currently pointing at valueA, GetPath would return the following path:
  584  *
  585  * @code
  586  * /baseNode/childA/valueA
  587  * @endcode
  588  *
  589  * Optionally, a path to another node can be supplied to this function. So, if the iterator is
  590  * again on valueA and the relative path ".." is supplied then this function will return the
  591  * following path:
  592  *
  593  * @code
  594  * /baseNode/childA/
  595  * @endcode
  596  *
  597  * @return - LE_OK            - The write was completed successfully.
  598  *         - LE_OVERFLOW      - The supplied string buffer was not large enough to hold the value.
  599  */
  600 //--------------------------------------------------------------------------------------------------
  601 le_result_t le_cfg_GetPath
  602 (
  603     le_cfg_IteratorRef_t iteratorRef,
  604         ///< [IN] Iterator to move.
  605 
  606     const char* path,
  607         ///< [IN] Path to the target node. Can be an absolute path, or
  608         ///<      a path relative from the iterator's current position.
  609 
  610     char* pathBuffer,
  611         ///< [OUT] Absolute path to the iterator's current node.
  612 
  613     size_t pathBufferNumElements
  614         ///< [IN]
  615 );
  616 
  617 //--------------------------------------------------------------------------------------------------
  618 /**
  619  * Get the type of node where the iterator is currently pointing.
  620  *
  621  * @return le_cfg_nodeType_t value indicating the stored value.
  622  */
  623 //--------------------------------------------------------------------------------------------------
  624 le_cfg_nodeType_t le_cfg_GetNodeType
  625 (
  626     le_cfg_IteratorRef_t iteratorRef,
  627         ///< [IN] Iterator object to use to read from the tree.
  628 
  629     const char* path
  630         ///< [IN] Path to the target node. Can be an absolute path, or
  631         ///<      a path relative from the iterator's current position.
  632 );
  633 
  634 //--------------------------------------------------------------------------------------------------
  635 /**
  636  * Get the name of the node where the iterator is currently pointing.
  637  *
  638  * @return - LE_OK       Read was completed successfully.
  639  *         - LE_OVERFLOW Supplied string buffer was not large enough to hold the value.
  640  */
  641 //--------------------------------------------------------------------------------------------------
  642 le_result_t le_cfg_GetNodeName
  643 (
  644     le_cfg_IteratorRef_t iteratorRef,
  645         ///< [IN] Iterator object to use to read from the tree.
  646 
  647     const char* path,
  648         ///< [IN] Path to the target node. Can be an absolute path, or
  649         ///<      a path relative from the iterator's current position.
  650 
  651     char* name,
  652         ///< [OUT] Read the name of the node object.
  653 
  654     size_t nameNumElements
  655         ///< [IN]
  656 );
  657 
  658 //--------------------------------------------------------------------------------------------------
  659 /**
  660  * Add handler function for EVENT 'le_cfg_Change'
  661  *
  662  * This event provides information on changes to the given node object, or any of it's children,
  663  * where a change could be either a read, write, create or delete operation.
  664  */
  665 //--------------------------------------------------------------------------------------------------
  666 le_cfg_ChangeHandlerRef_t le_cfg_AddChangeHandler
  667 (
  668     const char* newPath,
  669         ///< [IN] Path to the object to watch.
  670 
  671     le_cfg_ChangeHandlerFunc_t handlerPtr,
  672         ///< [IN]
  673 
  674     void* contextPtr
  675         ///< [IN]
  676 );
  677 
  678 //--------------------------------------------------------------------------------------------------
  679 /**
  680  * Remove handler function for EVENT 'le_cfg_Change'
  681  */
  682 //--------------------------------------------------------------------------------------------------
  683 void le_cfg_RemoveChangeHandler
  684 (
  685     le_cfg_ChangeHandlerRef_t addHandlerRef
  686         ///< [IN]
  687 );
  688 
  689 //--------------------------------------------------------------------------------------------------
  690 /**
  691  * Delete the node specified by the path. If the node doesn't exist, nothing happens. All child
  692  * nodes are also deleted.
  693  *
  694  * If the path is empty, the iterator's current node is deleted.
  695  *
  696  * Only valid during a write transaction.
  697  */
  698 //--------------------------------------------------------------------------------------------------
  699 void le_cfg_DeleteNode
  700 (
  701     le_cfg_IteratorRef_t iteratorRef,
  702         ///< [IN] Iterator to use as a basis for the transaction.
  703 
  704     const char* path
  705         ///< [IN] Path to the target node. Can be an absolute path, or
  706         ///<      a path relative from the iterator's current position.
  707 );
  708 
  709 //--------------------------------------------------------------------------------------------------
  710 /**
  711  * Check if the given node is empty. A node is also considered empty if it doesn't yet exist. A
  712  * node is also considered empty if it has no value or is a stem with no children.
  713  *
  714  * If the path is empty, the iterator's current node is queried for emptiness.
  715  *
  716  * Valid for both read and write transactions.
  717  *
  718  * @return A true if the node is considered empty, false if not.
  719  */
  720 //--------------------------------------------------------------------------------------------------
  721 bool le_cfg_IsEmpty
  722 (
  723     le_cfg_IteratorRef_t iteratorRef,
  724         ///< [IN] Iterator to use as a basis for the transaction.
  725 
  726     const char* path
  727         ///< [IN] Path to the target node. Can be an absolute path, or
  728         ///<      a path relative from the iterator's current position.
  729 );
  730 
  731 //--------------------------------------------------------------------------------------------------
  732 /**
  733  * Clear out the nodes's value. If it doesn't exist it will be created, but have no value.
  734  *
  735  * If the path is empty, the iterator's current node will be cleared. If the node is a stem
  736  * then all children will be removed from the tree.
  737  *
  738  * Only valid during a write transaction.
  739  */
  740 //--------------------------------------------------------------------------------------------------
  741 void le_cfg_SetEmpty
  742 (
  743     le_cfg_IteratorRef_t iteratorRef,
  744         ///< [IN] Iterator to use as a basis for the transaction.
  745 
  746     const char* path
  747         ///< [IN] Path to the target node. Can be an absolute path, or
  748         ///<      a path relative from the iterator's current position.
  749 );
  750 
  751 //--------------------------------------------------------------------------------------------------
  752 /**
  753  * Check to see if a given node in the config tree exists.
  754  *
  755  * @return True if the specified node exists in the tree. False if not.
  756  */
  757 //--------------------------------------------------------------------------------------------------
  758 bool le_cfg_NodeExists
  759 (
  760     le_cfg_IteratorRef_t iteratorRef,
  761         ///< [IN] Iterator to use as a basis for the transaction.
  762 
  763     const char* path
  764         ///< [IN] Path to the target node. Can be an absolute path, or
  765         ///<      a path relative from the iterator's current position.
  766 );
  767 
  768 //--------------------------------------------------------------------------------------------------
  769 /**
  770  * Read a string value from the config tree. If the value isn't a string, or if the node is
  771  * empty or doesn't exist, the default value will be returned.
  772  *
  773  * Valid for both read and write transactions.
  774  *
  775  * If the path is empty, the iterator's current node will be read.
  776  *
  777  * @return - LE_OK       - Read was completed successfully.
  778  *         - LE_OVERFLOW - Supplied string buffer was not large enough to hold the value.
  779  */
  780 //--------------------------------------------------------------------------------------------------
  781 le_result_t le_cfg_GetString
  782 (
  783     le_cfg_IteratorRef_t iteratorRef,
  784         ///< [IN] Iterator to use as a basis for the transaction.
  785 
  786     const char* path,
  787         ///< [IN] Path to the target node. Can be an absolute path,
  788         ///<      or a path relative from the iterator's current
  789         ///<      position.
  790 
  791     char* value,
  792         ///< [OUT] Buffer to write the value into.
  793 
  794     size_t valueNumElements,
  795         ///< [IN]
  796 
  797     const char* defaultValue
  798         ///< [IN] Default value to use if the original can't be
  799         ///<        read.
  800 );
  801 
  802 //--------------------------------------------------------------------------------------------------
  803 /**
  804  * Write a string value to the config tree. Only valid during a write
  805  * transaction.
  806  *
  807  * If the path is empty, the iterator's current node will be set.
  808  */
  809 //--------------------------------------------------------------------------------------------------
  810 void le_cfg_SetString
  811 (
  812     le_cfg_IteratorRef_t iteratorRef,
  813         ///< [IN] Iterator to use as a basis for the transaction.
  814 
  815     const char* path,
  816         ///< [IN] Path to the target node. Can be an absolute path, or
  817         ///<      a path relative from the iterator's current position.
  818 
  819     const char* value
  820         ///< [IN] Value to write.
  821 );
  822 
  823 //--------------------------------------------------------------------------------------------------
  824 /**
  825  * Read a signed integer value from the config tree.
  826  *
  827  * If the underlying value is not an integer, the default value will be returned instead. The
  828  * default value is also returned if the node does not exist or if it's empty.
  829  *
  830  * If the value is a floating point value, then it will be rounded and returned as an integer.
  831  *
  832  * Valid for both read and write transactions.
  833  *
  834  * If the path is empty, the iterator's current node will be read.
  835  */
  836 //--------------------------------------------------------------------------------------------------
  837 int32_t le_cfg_GetInt
  838 (
  839     le_cfg_IteratorRef_t iteratorRef,
  840         ///< [IN] Iterator to use as a basis for the transaction.
  841 
  842     const char* path,
  843         ///< [IN] Path to the target node. Can be an absolute path, or
  844         ///<      a path relative from the iterator's current position.
  845 
  846     int32_t defaultValue
  847         ///< [IN] Default value to use if the original can't be
  848         ///<        read.
  849 );
  850 
  851 //--------------------------------------------------------------------------------------------------
  852 /**
  853  * Write a signed integer value to the config tree. Only valid during a
  854  * write transaction.
  855  *
  856  * If the path is empty, the iterator's current node will be set.
  857  */
  858 //--------------------------------------------------------------------------------------------------
  859 void le_cfg_SetInt
  860 (
  861     le_cfg_IteratorRef_t iteratorRef,
  862         ///< [IN] Iterator to use as a basis for the transaction.
  863 
  864     const char* path,
  865         ///< [IN] Path to the target node. Can be an absolute path, or
  866         ///<      a path relative from the iterator's current position.
  867 
  868     int32_t value
  869         ///< [IN] Value to write.
  870 );
  871 
  872 //--------------------------------------------------------------------------------------------------
  873 /**
  874  * Read a 64-bit floating point value from the config tree.
  875  *
  876  * If the value is an integer then the value will be promoted to a float. Otherwise, if the
  877  * underlying value is not a float or integer, the default value will be returned.
  878  *
  879  * If the path is empty, the iterator's current node will be read.
  880  *
  881  * @note Floating point values will only be stored up to 6 digits of precision.
  882  */
  883 //--------------------------------------------------------------------------------------------------
  884 double le_cfg_GetFloat
  885 (
  886     le_cfg_IteratorRef_t iteratorRef,
  887         ///< [IN] Iterator to use as a basis for the transaction.
  888 
  889     const char* path,
  890         ///< [IN] Path to the target node. Can be an absolute path, or
  891         ///<      a path relative from the iterator's current position.
  892 
  893     double defaultValue
  894         ///< [IN] Default value to use if the original can't be
  895         ///<        read.
  896 );
  897 
  898 //--------------------------------------------------------------------------------------------------
  899 /**
  900  * Write a 64-bit floating point value to the config tree. Only valid
  901  * during a write transaction.
  902  *
  903  * If the path is empty, the iterator's current node will be set.
  904  *
  905  * @note Floating point values will only be stored up to 6 digits of precision.
  906  */
  907 //--------------------------------------------------------------------------------------------------
  908 void le_cfg_SetFloat
  909 (
  910     le_cfg_IteratorRef_t iteratorRef,
  911         ///< [IN] Iterator to use as a basis for the transaction.
  912 
  913     const char* path,
  914         ///< [IN] Path to the target node. Can be an absolute path, or
  915         ///<      a path relative from the iterator's current position.
  916 
  917     double value
  918         ///< [IN] Value to write.
  919 );
  920 
  921 //--------------------------------------------------------------------------------------------------
  922 /**
  923  * Read a value from the tree as a boolean. If the node is empty or doesn't exist, the default
  924  * value is returned. Default value is also returned if the node is a different type than
  925  * expected.
  926  *
  927  * Valid for both read and write transactions.
  928  *
  929  * If the path is empty, the iterator's current node will be read.
  930  */
  931 //--------------------------------------------------------------------------------------------------
  932 bool le_cfg_GetBool
  933 (
  934     le_cfg_IteratorRef_t iteratorRef,
  935         ///< [IN] Iterator to use as a basis for the transaction.
  936 
  937     const char* path,
  938         ///< [IN] Path to the target node. Can be an absolute path, or
  939         ///<      a path relative from the iterator's current position.
  940 
  941     bool defaultValue
  942         ///< [IN] Default value to use if the original can't be
  943         ///<        read.
  944 );
  945 
  946 //--------------------------------------------------------------------------------------------------
  947 /**
  948  * Write a boolean 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_SetBool
  955 (
  956     le_cfg_IteratorRef_t iteratorRef,
  957         ///< [IN] Iterator to use as a basis for the transaction.
  958 
  959     const char* path,
  960         ///< [IN] Path to the target node. Can be an absolute path, or
  961         ///<      a path relative from the iterator's current position.
  962 
  963     bool value
  964         ///< [IN] Value to write.
  965 );
  966 
  967 //--------------------------------------------------------------------------------------------------
  968 /**
  969  * Delete the node specified by the path. If the node doesn't exist, nothing happens. All child
  970  * nodes are also deleted.
  971  */
  972 //--------------------------------------------------------------------------------------------------
  973 void le_cfg_QuickDeleteNode
  974 (
  975     const char* path
  976         ///< [IN] Path to the node to delete.
  977 );
  978 
  979 //--------------------------------------------------------------------------------------------------
  980 /**
  981  * Make a given node empty. If the node doesn't currently exist then it is created as a new empty
  982  * node.
  983  */
  984 //--------------------------------------------------------------------------------------------------
  985 void le_cfg_QuickSetEmpty
  986 (
  987     const char* path
  988         ///< [IN] Absolute or relative path to read from.
  989 );
  990 
  991 //--------------------------------------------------------------------------------------------------
  992 /**
  993  * Read a string value from the config tree. If the value isn't a string, or if the node is
  994  * empty or doesn't exist, the default value will be returned.
  995  *
  996  * @return - LE_OK       - Commit was completed successfully.
  997  *         - LE_OVERFLOW - Supplied string buffer was not large enough to hold the value.
  998  */
  999 //--------------------------------------------------------------------------------------------------
 1000 le_result_t le_cfg_QuickGetString
 1001 (
 1002     const char* path,
 1003         ///< [IN] Path to read from.
 1004 
 1005     char* value,
 1006         ///< [OUT] Value read from the requested node.
 1007 
 1008     size_t valueNumElements,
 1009         ///< [IN]
 1010 
 1011     const char* defaultValue
 1012         ///< [IN] Default value to use if the original can't be read.
 1013 );
 1014 
 1015 //--------------------------------------------------------------------------------------------------
 1016 /**
 1017  * Write a string value to the config tree.
 1018  */
 1019 //--------------------------------------------------------------------------------------------------
 1020 void le_cfg_QuickSetString
 1021 (
 1022     const char* path,
 1023         ///< [IN] Path to the value to write.
 1024 
 1025     const char* value
 1026         ///< [IN] Value to write.
 1027 );
 1028 
 1029 //--------------------------------------------------------------------------------------------------
 1030 /**
 1031  * Read a signed integer value from the config tree. If the value is a floating point
 1032  * value, then it will be rounded and returned as an integer. Otherwise If the underlying value is
 1033  * not an integer or a float, the default value will be returned instead.
 1034  *
 1035  * If the value is empty or the node doesn't exist, the default value is returned instead.
 1036  */
 1037 //--------------------------------------------------------------------------------------------------
 1038 int32_t le_cfg_QuickGetInt
 1039 (
 1040     const char* path,
 1041         ///< [IN] Path to the value to write.
 1042 
 1043     int32_t defaultValue
 1044         ///< [IN] Default value to use if the original can't be read.
 1045 );
 1046 
 1047 //--------------------------------------------------------------------------------------------------
 1048 /**
 1049  * Write a signed integer value to the config tree.
 1050  */
 1051 //--------------------------------------------------------------------------------------------------
 1052 void le_cfg_QuickSetInt
 1053 (
 1054     const char* path,
 1055         ///< [IN] Path to the value to write.
 1056 
 1057     int32_t value
 1058         ///< [IN] Value to write.
 1059 );
 1060 
 1061 //--------------------------------------------------------------------------------------------------
 1062 /**
 1063  * Read a 64-bit floating point value from the config tree. If the value is an integer,
 1064  * then it is promoted to a float. Otherwise, if the underlying value is not a float, or an
 1065  * integer the default value will be returned.
 1066  *
 1067  * If the value is empty or the node doesn't exist, the default value is returned.
 1068  *
 1069  * @note Floating point values will only be stored up to 6 digits of precision.
 1070  */
 1071 //--------------------------------------------------------------------------------------------------
 1072 double le_cfg_QuickGetFloat
 1073 (
 1074     const char* path,
 1075         ///< [IN] Path to the value to write.
 1076 
 1077     double defaultValue
 1078         ///< [IN] Default value to use if the original can't be read.
 1079 );
 1080 
 1081 //--------------------------------------------------------------------------------------------------
 1082 /**
 1083  * Write a 64-bit floating point value to the config tree.
 1084  *
 1085  * @note Floating point values will only be stored up to 6 digits of precision.
 1086  */
 1087 //--------------------------------------------------------------------------------------------------
 1088 void le_cfg_QuickSetFloat
 1089 (
 1090     const char* path,
 1091         ///< [IN] Path to the value to write.
 1092 
 1093     double value
 1094         ///< [IN] Value to write.
 1095 );
 1096 
 1097 //--------------------------------------------------------------------------------------------------
 1098 /**
 1099  * Read a value from the tree as a boolean. If the node is empty or doesn't exist, the default
 1100  * value is returned. This is also true if the node is a different type than expected.
 1101  *
 1102  * If the value is empty or the node doesn't exist, the default value is returned instead.
 1103  */
 1104 //--------------------------------------------------------------------------------------------------
 1105 bool le_cfg_QuickGetBool
 1106 (
 1107     const char* path,
 1108         ///< [IN] Path to the value to write.
 1109 
 1110     bool defaultValue
 1111         ///< [IN] Default value to use if the original can't be read.
 1112 );
 1113 
 1114 //--------------------------------------------------------------------------------------------------
 1115 /**
 1116  * Write a boolean value to the config tree.
 1117  */
 1118 //--------------------------------------------------------------------------------------------------
 1119 void le_cfg_QuickSetBool
 1120 (
 1121     const char* path,
 1122         ///< [IN] Path to the value to write.
 1123 
 1124     bool value
 1125         ///< [IN] Value to write.
 1126 );
 1127 
 1128 
 1129 #endif // LE_CFG_INTERFACE_H_INCLUDE_GUARD
 1130 
le_cfg_QuickSetInt
void le_cfg_QuickSetInt(const char *path, int32_t value)
le_cfg_QuickSetFloat
void le_cfg_QuickSetFloat(const char *path, double value)
le_cfg_RemoveChangeHandler
void le_cfg_RemoveChangeHandler(le_cfg_ChangeHandlerRef_t addHandlerRef)
le_cfg_DisconnectService
void le_cfg_DisconnectService(void)
le_result_t
le_result_t
Definition: le_basics.h:35
le_cfg_SetBool
void le_cfg_SetBool(le_cfg_IteratorRef_t iteratorRef, const char *path, bool value)
le_cfg_SetString
void le_cfg_SetString(le_cfg_IteratorRef_t iteratorRef, const char *path, const char *value)
le_cfg_QuickGetBool
bool le_cfg_QuickGetBool(const char *path, bool defaultValue)
LE_CFG_TYPE_FLOAT
64-bit floating point value. 
Definition: le_cfg_interface.h:352
le_cfg_AddChangeHandler
le_cfg_ChangeHandlerRef_t le_cfg_AddChangeHandler(const char *newPath, le_cfg_ChangeHandlerFunc_t handlerPtr, void *contextPtr)
le_cfg_ChangeHandlerRef_t
struct le_cfg_ChangeHandler * le_cfg_ChangeHandlerRef_t
Definition: le_cfg_interface.h:401
le_cfg_GoToNextSibling
le_result_t le_cfg_GoToNextSibling(le_cfg_IteratorRef_t iteratorRef)
le_cfg_SetFloat
void le_cfg_SetFloat(le_cfg_IteratorRef_t iteratorRef, const char *path, double value)
le_cfg_CreateReadTxn
le_cfg_IteratorRef_t le_cfg_CreateReadTxn(const char *basePath)
le_cfg_IteratorRef_t
struct le_cfg_Iterator * le_cfg_IteratorRef_t
Definition: le_cfg_interface.h:330
le_cfg_GetInt
int32_t le_cfg_GetInt(le_cfg_IteratorRef_t iteratorRef, const char *path, int32_t defaultValue)
LE_CFG_TYPE_EMPTY
A node with no value. 
Definition: le_cfg_interface.h:340
le_cfg_QuickGetFloat
double le_cfg_QuickGetFloat(const char *path, double defaultValue)
le_cfg_ConnectService
void le_cfg_ConnectService(void)
LE_CFG_TYPE_STRING
A string encoded as utf8. 
Definition: le_cfg_interface.h:343
le_cfg_GoToNode
void le_cfg_GoToNode(le_cfg_IteratorRef_t iteratorRef, const char *newPath)
le_cfg_QuickDeleteNode
void le_cfg_QuickDeleteNode(const char *path)
LE_CFG_TYPE_BOOL
Boolean value. 
Definition: le_cfg_interface.h:346
le_cfg_QuickSetString
void le_cfg_QuickSetString(const char *path, const char *value)
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:338
LE_CFG_TYPE_DOESNT_EXIST
Node doesn&#39;t exist. 
Definition: le_cfg_interface.h:358
le_cfg_GetPath
le_result_t le_cfg_GetPath(le_cfg_IteratorRef_t iteratorRef, const char *path, char *pathBuffer, size_t pathBufferNumElements)
le_cfg_GetFloat
double le_cfg_GetFloat(le_cfg_IteratorRef_t iteratorRef, const char *path, double defaultValue)
le_cfg_DeleteNode
void le_cfg_DeleteNode(le_cfg_IteratorRef_t iteratorRef, const char *path)
le_cfg_QuickSetEmpty
void le_cfg_QuickSetEmpty(const char *path)
le_cfg_TryConnectService
le_result_t le_cfg_TryConnectService(void)
le_cfg_GetNodeType
le_cfg_nodeType_t le_cfg_GetNodeType(le_cfg_IteratorRef_t iteratorRef, const char *path)
le_cfg_ChangeHandlerFunc_t
void(* le_cfg_ChangeHandlerFunc_t)(void *contextPtr)
Definition: le_cfg_interface.h:412
legato.h
le_cfg_NodeExists
bool le_cfg_NodeExists(le_cfg_IteratorRef_t iteratorRef, const char *path)
le_cfg_CreateWriteTxn
le_cfg_IteratorRef_t le_cfg_CreateWriteTxn(const char *basePath)
le_cfg_SetInt
void le_cfg_SetInt(le_cfg_IteratorRef_t iteratorRef, const char *path, int32_t value)
le_cfg_CancelTxn
void le_cfg_CancelTxn(le_cfg_IteratorRef_t iteratorRef)
le_cfg_IsEmpty
bool le_cfg_IsEmpty(le_cfg_IteratorRef_t iteratorRef, const char *path)
le_cfg_QuickGetInt
int32_t le_cfg_QuickGetInt(const char *path, int32_t defaultValue)
le_cfg_QuickGetString
le_result_t le_cfg_QuickGetString(const char *path, char *value, size_t valueNumElements, const char *defaultValue)
le_cfg_GetString
le_result_t le_cfg_GetString(le_cfg_IteratorRef_t iteratorRef, const char *path, char *value, size_t valueNumElements, const char *defaultValue)
LE_CFG_TYPE_INT
Signed 32-bit. 
Definition: le_cfg_interface.h:349
le_cfg_GoToFirstChild
le_result_t le_cfg_GoToFirstChild(le_cfg_IteratorRef_t iteratorRef)
le_cfg_SetEmpty
void le_cfg_SetEmpty(le_cfg_IteratorRef_t iteratorRef, const char *path)
le_cfg_QuickSetBool
void le_cfg_QuickSetBool(const char *path, bool value)
le_cfg_GetBool
bool le_cfg_GetBool(le_cfg_IteratorRef_t iteratorRef, const char *path, bool defaultValue)
le_cfg_GetNodeName
le_result_t le_cfg_GetNodeName(le_cfg_IteratorRef_t iteratorRef, const char *path, char *name, size_t nameNumElements)
le_cfg_GoToParent
le_result_t le_cfg_GoToParent(le_cfg_IteratorRef_t iteratorRef)
LE_CFG_TYPE_STEM
Non-leaf node, this node is the parent of other nodes. 
Definition: le_cfg_interface.h:355