le_cfg_interface.h

Go to the documentation of this file.
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 {
357  ///< A node with no value.
358 
360  ///< A string encoded as utf8.
361 
363  ///< Boolean value.
364 
366  ///< Signed 32-bit.
367 
369  ///< 64-bit floating point value.
370 
372  ///< Non-leaf node, this node is the parent of other nodes.
373 
375  ///< Node doesn't exist.
376 }
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 
void le_cfg_QuickSetInt(const char *path, int32_t value)
void le_cfg_QuickSetFloat(const char *path, double value)
void le_cfg_RemoveChangeHandler(le_cfg_ChangeHandlerRef_t addHandlerRef)
void le_cfg_DisconnectService(void)
le_result_t
Definition: le_basics.h:35
void le_cfg_SetBool(le_cfg_IteratorRef_t iteratorRef, const char *path, bool value)
void le_cfg_SetString(le_cfg_IteratorRef_t iteratorRef, const char *path, const char *value)
bool le_cfg_QuickGetBool(const char *path, bool defaultValue)
64-bit floating point value.
Definition: le_cfg_interface.h:368
le_cfg_ChangeHandlerRef_t le_cfg_AddChangeHandler(const char *newPath, le_cfg_ChangeHandlerFunc_t handlerPtr, void *contextPtr)
struct le_cfg_ChangeHandler * le_cfg_ChangeHandlerRef_t
Definition: le_cfg_interface.h:417
le_result_t le_cfg_GoToNextSibling(le_cfg_IteratorRef_t iteratorRef)
void le_cfg_SetFloat(le_cfg_IteratorRef_t iteratorRef, const char *path, double value)
le_cfg_IteratorRef_t le_cfg_CreateReadTxn(const char *basePath)
struct le_cfg_Iterator * le_cfg_IteratorRef_t
Definition: le_cfg_interface.h:346
int32_t le_cfg_GetInt(le_cfg_IteratorRef_t iteratorRef, const char *path, int32_t defaultValue)
A node with no value.
Definition: le_cfg_interface.h:356
double le_cfg_QuickGetFloat(const char *path, double defaultValue)
void le_cfg_ConnectService(void)
A string encoded as utf8.
Definition: le_cfg_interface.h:359
void le_cfg_GoToNode(le_cfg_IteratorRef_t iteratorRef, const char *newPath)
void le_cfg_QuickDeleteNode(const char *path)
Boolean value.
Definition: le_cfg_interface.h:362
void le_cfg_QuickSetString(const char *path, const char *value)
void le_cfg_CommitTxn(le_cfg_IteratorRef_t iteratorRef)
le_cfg_nodeType_t
Definition: le_cfg_interface.h:354
Node doesn&#39;t exist.
Definition: le_cfg_interface.h:374
le_result_t le_cfg_GetPath(le_cfg_IteratorRef_t iteratorRef, const char *path, char *pathBuffer, size_t pathBufferNumElements)
double le_cfg_GetFloat(le_cfg_IteratorRef_t iteratorRef, const char *path, double defaultValue)
void le_cfg_DeleteNode(le_cfg_IteratorRef_t iteratorRef, const char *path)
void le_cfg_QuickSetEmpty(const char *path)
le_result_t le_cfg_TryConnectService(void)
le_cfg_nodeType_t le_cfg_GetNodeType(le_cfg_IteratorRef_t iteratorRef, const char *path)
void(* le_cfg_ChangeHandlerFunc_t)(void *contextPtr)
Definition: le_cfg_interface.h:428
bool le_cfg_NodeExists(le_cfg_IteratorRef_t iteratorRef, const char *path)
le_cfg_IteratorRef_t le_cfg_CreateWriteTxn(const char *basePath)
void le_cfg_SetInt(le_cfg_IteratorRef_t iteratorRef, const char *path, int32_t value)
void le_cfg_CancelTxn(le_cfg_IteratorRef_t iteratorRef)
bool le_cfg_IsEmpty(le_cfg_IteratorRef_t iteratorRef, const char *path)
int32_t le_cfg_QuickGetInt(const char *path, int32_t defaultValue)
le_result_t le_cfg_QuickGetString(const char *path, char *value, size_t valueNumElements, const char *defaultValue)
le_result_t le_cfg_GetString(le_cfg_IteratorRef_t iteratorRef, const char *path, char *value, size_t valueNumElements, const char *defaultValue)
Signed 32-bit.
Definition: le_cfg_interface.h:365
le_result_t le_cfg_GoToFirstChild(le_cfg_IteratorRef_t iteratorRef)
void le_cfg_SetEmpty(le_cfg_IteratorRef_t iteratorRef, const char *path)
void le_cfg_QuickSetBool(const char *path, bool value)
bool le_cfg_GetBool(le_cfg_IteratorRef_t iteratorRef, const char *path, bool defaultValue)
le_result_t le_cfg_GetNodeName(le_cfg_IteratorRef_t iteratorRef, const char *path, char *name, size_t nameNumElements)
le_result_t le_cfg_GoToParent(le_cfg_IteratorRef_t iteratorRef)
Non-leaf node, this node is the parent of other nodes.
Definition: le_cfg_interface.h:371