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