le_cfgAdmin_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_configAdmin Config Tree Admin API
14  *
15  * @ref le_cfgAdmin_interface.h "API Reference"
16  *
17  * The Config Tree Admin API is intended to provide tools help with administration of Trees. These
18  * administration functions are provided as a separate API for security reasons. The Admin API needs
19  * to be explicitly included to use these admin functions keeping access separate from the main app
20  * permissions.
21  *
22  * The API includes the following functions:
23  * - an iterator function to walk the current list of trees.
24  * - an import function to bulk load the data (full or partial) into a tree.
25  * - an export function to save the contents of a tree.
26  * - a delete function to remove a tree and all its objects.
27  *
28  * Example of @b Iterating the List of Trees:
29  *
30  * @code
31  * void ListTrees(void)
32  * {
33  * // Open a tree iterator. Note that this isn't the same iterator that you would be using for
34  * // read and write transactions.
35  * le_cfgAdmin_IteratorRef_t iteratorRef = le_cfgAdmin_CreateTreeIterator();
36  *
37  * LE_INFO("Listing configuration Trees in the current system...");
38  *
39  * // The iteratorRef starts at item -1, so we need to start with calling NextTree in our loop.
40  * while (le_cfgAdmin_NextTree(iteratorRef) == LE_OK)
41  * {
42  * // Simply extract the name of the tree and dump it to the device log.
43  * char treeName[MAX_TREE_NAME_BYTES] = "";
44  *
45  * if (le_cfgAdmin_GetTreeName(iteratorRef, treeName, sizeof(treeName)) == LE_OK)
46  * {
47  * LE_INFO("Tree: '%s'", treeName);
48  * }
49  * }
50  *
51  * // Again, this isn't a regular config node iterator, so you need to use the cfgAdmin
52  * // release on the tree iterator.
53  * le_cfgAdmin_ReleaseTreeIterator(iteratorRef);
54  * }
55  * @endcode
56  *
57  * Example of @b Importing a Tree:
58  *
59  * @code
60  * void ImportMyTree(const char* filePath)
61  * {
62  * static char resolvedPath[PATH_MAX] = "";
63  *
64  * // Because the configTree is a seperate process, we need to make sure that the path we
65  * // received is an absolute path.
66  * LE_FATAL_IF(realpath(filePath, resolvedPath) == NULL, "Could not resolve filePath: error %d",
67  * errno);
68  *
69  * // Open a write transaction on /myData, as we will be writing to the configTree.
70  * le_cfg_IteratorRef_t iteratorRef = le_cfg_CreateReadTxn("/myData");
71  *
72  * // Our iterator is currently on /myData, so everything under that node is replaced. If we
73  * // want to replace the whole tree we could supply a "/" here instead of using the iterator's
74  * // current location. Alternativly, we could have opened or moved the iterator to "/" in the
75  * // first place.
76  * LE_FATAL_IF(le_cfgAdmin_ExportTree(iteratorRef, resolvedPath, "") != LE_OK,
77  * "Error occured while writing config data.");
78  *
79  * // Close up the iterator,free it's resources, and commit the new data to the configTree.
80  * le_cfg_CommitTxn(iteratorRef);
81  * }
82  *
83  * // To import the config data back from ./myData.cfg:
84  * ImportMyData("./myData.cfg");
85  * @endcode
86  *
87  * Example of @b Exporting a Tree
88  *
89  * @code
90  * void ExportMyData(const char* filePath)
91  * {
92  * static char resolvedPath[PATH_MAX] = "";
93  *
94  * // Because the configTree is a seperate process, we need to make sure that the path we
95  * // received is an absolute path.
96  * LE_FATAL_IF(realpath(filePath, resolvedPath) == NULL, "Could not resolve filePath: error %d",
97  * errno);
98  *
99  * // Open a read transaction on /myData.
100  * le_cfg_IteratorRef_t iteratorRef = le_cfg_CreateReadTxn("/myData");
101  *
102  * // Our iterator is currently on /myData, so everything under that node is exported. If we
103  * // want to export the whole tree we could supply a "/" here instead of using the iterator's
104  * // current location. Alternativly, we could have opened or moved the iterator to "/" in the
105  * // first place.
106  * LE_FATAL_IF(le_cfgAdmin_ExportTree(iteratorRef, resolvedPath, "") != LE_OK,
107  * "Error occured while writing config data.");
108  *
109  * // Close up the iterator and free it's resources.
110  * le_cfg_CancelTxn(iteratorRef);
111  * }
112  *
113  * // To export the config tree to ./myData.cfg:
114  * ExportMyData("./myData.cfg");
115  * @endcode
116  *
117  * Example of @b Deleting a Tree
118  *
119  * @code
120  * // To delete a tree simply call le_cfgAdmin_DeleteTree. For example to delete the tree foo,
121  * // call as follows:
122  * le_cfgAdmin_DeleteTree("foo");
123  * @endcode
124  *
125  * Copyright (C) Sierra Wireless Inc.
126  */
127 /**
128  * @file le_cfgAdmin_interface.h
129  *
130  * Legato @ref c_configAdmin include file.
131  *
132  * Copyright (C) Sierra Wireless Inc.
133  */
134 
135 #ifndef LE_CFGADMIN_INTERFACE_H_INCLUDE_GUARD
136 #define LE_CFGADMIN_INTERFACE_H_INCLUDE_GUARD
137 
138 
139 #include "legato.h"
140 
141 // Interface specific includes
142 #include "le_cfg_interface.h"
143 
144 // Internal includes for this interface
145 #include "le_cfgAdmin_common.h"
146 /** @addtogroup le_cfgAdmin le_cfgAdmin API Reference
147  * @{
148  * @file le_cfgAdmin_common.h
149  * @file le_cfgAdmin_interface.h **/
150 //--------------------------------------------------------------------------------------------------
151 /**
152  * Type for handler called when a server disconnects.
153  */
154 //--------------------------------------------------------------------------------------------------
155 typedef void (*le_cfgAdmin_DisconnectHandler_t)(void *);
156 
157 //--------------------------------------------------------------------------------------------------
158 /**
159  *
160  * Connect the current client thread to the service providing this API. Block until the service is
161  * available.
162  *
163  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
164  * called before any other functions in this API. Normally, ConnectService is automatically called
165  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
166  *
167  * This function is created automatically.
168  */
169 //--------------------------------------------------------------------------------------------------
171 (
172  void
173 );
174 
175 //--------------------------------------------------------------------------------------------------
176 /**
177  *
178  * Try to connect the current client thread to the service providing this API. Return with an error
179  * if the service is not available.
180  *
181  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
182  * called before any other functions in this API. Normally, ConnectService is automatically called
183  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
184  *
185  * This function is created automatically.
186  *
187  * @return
188  * - LE_OK if the client connected successfully to the service.
189  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
190  * bound.
191  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
192  * - LE_COMM_ERROR if the Service Directory cannot be reached.
193  */
194 //--------------------------------------------------------------------------------------------------
196 (
197  void
198 );
199 
200 //--------------------------------------------------------------------------------------------------
201 /**
202  * Set handler called when server disconnection is detected.
203  *
204  * When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants
205  * to continue without exiting, it should call longjmp() from inside the handler.
206  */
207 //--------------------------------------------------------------------------------------------------
209 (
210  le_cfgAdmin_DisconnectHandler_t disconnectHandler,
211  void *contextPtr
212 );
213 
214 //--------------------------------------------------------------------------------------------------
215 /**
216  *
217  * Disconnect the current client thread from the service providing this API.
218  *
219  * Normally, this function doesn't need to be called. After this function is called, there's no
220  * longer a connection to the service, and the functions in this API can't be used. For details, see
221  * @ref apiFilesC_client.
222  *
223  * This function is created automatically.
224  */
225 //--------------------------------------------------------------------------------------------------
227 (
228  void
229 );
230 
231 
232 //--------------------------------------------------------------------------------------------------
233 /**
234  * Reference to an iterator object that can be used to iterate over the list of trees.
235  */
236 //--------------------------------------------------------------------------------------------------
237 
238 
239 //--------------------------------------------------------------------------------------------------
240 /**
241  * Read a subset of the configuration tree from the given filePath. The tree then overwrites the
242  * node at the given nodePath.
243  *
244  * This function will import a sub-tree as part of the iterator's current transaction. This allows
245  * you to create an iterator on a given node. Import a sub-tree, and then examine the contents of
246  * the import before deciding to commit the new data.
247  *
248  * @return This function will return one of the following values:
249  *
250  * - LE_OK - The commit was completed successfuly.
251  * - LE_FAULT - An I/O error occured while reading the data.
252  * - LE_FORMAT_ERROR - The configuration data being imported appears corrupted.
253  */
254 //--------------------------------------------------------------------------------------------------
256 (
257  le_cfg_IteratorRef_t iteratorRef,
258  ///< [IN] Write iterator that is being used for the import.
259  const char* LE_NONNULL filePath,
260  ///< [IN] Import the tree data from the this file.
261  const char* LE_NONNULL nodePath
262  ///< [IN] Where in the tree should this import happen? Leave
263  ///< as an empty string to use the iterator's current
264  ///< node.
265 );
266 
267 //--------------------------------------------------------------------------------------------------
268 /**
269  * Take a node given from nodePath and stream it and it's children to the file given by filePath.
270  *
271  * This funciton uses the iterator's read transaction, and takes a snapshot of the current state of
272  * the tree. The data write happens immediately.
273  *
274  * @return This function will return one of the following values:
275  *
276  * - LE_OK - The commit was completed successfuly.
277  * - LE_FAULT - An I/O error occured while writing the data.
278  */
279 //--------------------------------------------------------------------------------------------------
281 (
282  le_cfg_IteratorRef_t iteratorRef,
283  ///< [IN] Write iterator that is being used for the export.
284  const char* LE_NONNULL filePath,
285  ///< [IN] Import the tree data from the this file.
286  const char* LE_NONNULL nodePath
287  ///< [IN] Where in the tree should this export happen? Leave
288  ///< as an empty string to use the iterator's current
289  ///< node.
290 );
291 
292 //--------------------------------------------------------------------------------------------------
293 /**
294  * Delete a tree from the system, both from the filesystem and from memory.
295  */
296 //--------------------------------------------------------------------------------------------------
298 (
299  const char* LE_NONNULL treeName
300  ///< [IN] Name of the tree to delete.
301 );
302 
303 //--------------------------------------------------------------------------------------------------
304 /**
305  * Create a new iterator object for iterating over the list of trees currently managed by the
306  * config tree daemon.
307  */
308 //--------------------------------------------------------------------------------------------------
310 (
311  void
312 );
313 
314 //--------------------------------------------------------------------------------------------------
315 /**
316  * Release the iterator and free it's memory back to the system.
317  */
318 //--------------------------------------------------------------------------------------------------
320 (
321  le_cfgAdmin_IteratorRef_t iteratorRef
322  ///< [IN] Iterator object to release.
323 );
324 
325 //--------------------------------------------------------------------------------------------------
326 /**
327  * Read the name of the tree currently pointed at by the iterator.
328  *
329  * @return LE_OK if there is enough room to copy the name into the supplied buffer. LE_OVERFLOW if
330  * not. LE_NOT_FOUND is returned if the list is empty or if the iterator hasn't been moved
331  * onto the first item yet.
332  */
333 //--------------------------------------------------------------------------------------------------
335 (
336  le_cfgAdmin_IteratorRef_t iteratorRef,
337  ///< [IN] Iterator object to read.
338  char* name,
339  ///< [OUT] Name of the currently referenced tree is
340  ///< passed in this out parameter.
341  size_t nameSize
342  ///< [IN]
343 );
344 
345 //--------------------------------------------------------------------------------------------------
346 /**
347  * Move onto the next tree in the list. If there are no more trees this function returns false,
348  * otherwise true is returned.
349  *
350  * @return LE_OK if there are more trees to iterate through. LE_NOT_FOUND if not.
351  */
352 //--------------------------------------------------------------------------------------------------
354 (
355  le_cfgAdmin_IteratorRef_t iteratorRef
356  ///< [IN] Iterator to iterate.
357 );
358 
359 /** @} **/
360 
361 #endif // LE_CFGADMIN_INTERFACE_H_INCLUDE_GUARD
le_result_t
Definition: le_basics.h:46
le_result_t le_cfgAdmin_NextTree(le_cfgAdmin_IteratorRef_t iteratorRef)
struct le_cfgAdmin_Iterator * le_cfgAdmin_IteratorRef_t
Definition: le_cfgAdmin_common.h:36
le_result_t le_cfgAdmin_GetTreeName(le_cfgAdmin_IteratorRef_t iteratorRef, char *name, size_t nameSize)
le_result_t le_cfgAdmin_TryConnectService(void)
void le_cfgAdmin_ReleaseTreeIterator(le_cfgAdmin_IteratorRef_t iteratorRef)
le_cfgAdmin_IteratorRef_t le_cfgAdmin_CreateTreeIterator(void)
void le_cfgAdmin_ConnectService(void)
#define LE_FULL_API
Definition: le_apiFeatures.h:40
struct le_cfg_Iterator * le_cfg_IteratorRef_t
Definition: le_cfg_common.h:68
le_result_t le_cfgAdmin_ImportTree(le_cfg_IteratorRef_t iteratorRef, const char *LE_NONNULL filePath, const char *LE_NONNULL nodePath)
void le_cfgAdmin_DeleteTree(const char *LE_NONNULL treeName)
void(* le_cfgAdmin_DisconnectHandler_t)(void *)
Definition: le_cfgAdmin_interface.h:155
LE_FULL_API void le_cfgAdmin_SetServerDisconnectHandler(le_cfgAdmin_DisconnectHandler_t disconnectHandler, void *contextPtr)
void le_cfgAdmin_DisconnectService(void)
le_result_t le_cfgAdmin_ExportTree(le_cfg_IteratorRef_t iteratorRef, const char *LE_NONNULL filePath, const char *LE_NONNULL nodePath)