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