le_cfg_interface.h

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