le_cfgAdmin_interface.h

    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 //--------------------------------------------------------------------------------------------------
  170 void le_cfgAdmin_ConnectService
  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 //--------------------------------------------------------------------------------------------------
  195 le_result_t le_cfgAdmin_TryConnectService
  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 //--------------------------------------------------------------------------------------------------
  208 LE_FULL_API void le_cfgAdmin_SetServerDisconnectHandler
  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 //--------------------------------------------------------------------------------------------------
  226 void le_cfgAdmin_DisconnectService
  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 //--------------------------------------------------------------------------------------------------
  255 le_result_t le_cfgAdmin_ImportTree
  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 //--------------------------------------------------------------------------------------------------
  280 le_result_t le_cfgAdmin_ExportTree
  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 //--------------------------------------------------------------------------------------------------
  297 void le_cfgAdmin_DeleteTree
  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 //--------------------------------------------------------------------------------------------------
  309 le_cfgAdmin_IteratorRef_t le_cfgAdmin_CreateTreeIterator
  310 (
  311     void
  312 );
  313 
  314 //--------------------------------------------------------------------------------------------------
  315 /**
  316  * Release the iterator and free it's memory back to the system.
  317  */
  318 //--------------------------------------------------------------------------------------------------
  319 void le_cfgAdmin_ReleaseTreeIterator
  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 //--------------------------------------------------------------------------------------------------
  334 le_result_t le_cfgAdmin_GetTreeName
  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 //--------------------------------------------------------------------------------------------------
  353 le_result_t le_cfgAdmin_NextTree
  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_cfg_interface.h
le_result_t
le_result_t
Definition: le_basics.h:46
le_cfgAdmin_NextTree
le_result_t le_cfgAdmin_NextTree(le_cfgAdmin_IteratorRef_t iteratorRef)
le_cfgAdmin_IteratorRef_t
struct le_cfgAdmin_Iterator * le_cfgAdmin_IteratorRef_t
Definition: le_cfgAdmin_common.h:36
le_cfgAdmin_GetTreeName
le_result_t le_cfgAdmin_GetTreeName(le_cfgAdmin_IteratorRef_t iteratorRef, char *name, size_t nameSize)
le_cfgAdmin_TryConnectService
le_result_t le_cfgAdmin_TryConnectService(void)
le_cfgAdmin_ReleaseTreeIterator
void le_cfgAdmin_ReleaseTreeIterator(le_cfgAdmin_IteratorRef_t iteratorRef)
le_cfgAdmin_CreateTreeIterator
le_cfgAdmin_IteratorRef_t le_cfgAdmin_CreateTreeIterator(void)
le_cfgAdmin_ConnectService
void le_cfgAdmin_ConnectService(void)
LE_FULL_API
#define LE_FULL_API
Definition: le_apiFeatures.h:40
le_cfg_IteratorRef_t
struct le_cfg_Iterator * le_cfg_IteratorRef_t
Definition: le_cfg_common.h:68
le_cfgAdmin_common.h
le_cfgAdmin_ImportTree
le_result_t le_cfgAdmin_ImportTree(le_cfg_IteratorRef_t iteratorRef, const char *LE_NONNULL filePath, const char *LE_NONNULL nodePath)
legato.h
le_cfgAdmin_DeleteTree
void le_cfgAdmin_DeleteTree(const char *LE_NONNULL treeName)
le_cfgAdmin_DisconnectHandler_t
void(* le_cfgAdmin_DisconnectHandler_t)(void *)
Definition: le_cfgAdmin_interface.h:155
le_cfgAdmin_SetServerDisconnectHandler
LE_FULL_API void le_cfgAdmin_SetServerDisconnectHandler(le_cfgAdmin_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_cfgAdmin_DisconnectService
void le_cfgAdmin_DisconnectService(void)
le_cfgAdmin_ExportTree
le_result_t le_cfgAdmin_ExportTree(le_cfg_IteratorRef_t iteratorRef, const char *LE_NONNULL filePath, const char *LE_NONNULL nodePath)