le_cfgAdmin_interface.h

    1 /*
    2  * ====================== WARNING ======================
    3  *
    4  * THE CONTENTS OF THIS FILE HAVE BEEN AUTO-GENERATED.
    5  * DO NOT MODIFY IN ANY WAY.
    6  *
    7  * ====================== WARNING ======================
    8  */
    9 
   10 /**
   11  * @page c_configAdmin Config Tree Admin API
   12  *
   13  * @ref le_cfgAdmin_interface.h "API Reference"
   14  *
   15  * This API includes functions for importing and exporting subsections of the config tree to and
   16  * from a file.
   17  *
   18  * This API also includes an iterator object that can be used to iterate over the list of trees
   19  * currently known by the system.
   20  *
   21  * An example of printing the list of trees in a system:
   22  *
   23  * @code
   24  * le_cfgAdmin_IteratorRef_t iteratorRef = le_cfgAdmin_CreateTreeIterator();
   25  *
   26  * while (le_cfgAdmin_NextTree(iteratorRef) == LE_OK)
   27  * {
   28  *    char treeName[MAX_TREE_NAME] = { 0 };
   29  *
   30  *    if (le_cfgAdmin_GetTreeName(iteratorRef, treeName, sizeof(treeName)) == LE_OK)
   31  *    {
   32  *        printf("Tree: \"%s\"\n", treeName);
   33  *    }
   34  *    else
   35  *    {
   36  *        printf("Tree: \"%s\", truncated.\n", treeName);
   37  *    }
   38  * }
   39  *
   40  * le_cfgAdmin_ReleaseTreeIterator(iteratorRef);
   41  * @endcode
   42  *
   43  * <HR>
   44  *
   45  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
   46  */
   47 /**
   48  * @file le_cfgAdmin_interface.h
   49  *
   50  * Legato @ref c_configAdmin include file.
   51  *
   52  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
   53  */
   54 
   55 #ifndef LE_CFGADMIN_INTERFACE_H_INCLUDE_GUARD
   56 #define LE_CFGADMIN_INTERFACE_H_INCLUDE_GUARD
   57 
   58 
   59 #include "legato.h"
   60 
   61 // Interface specific includes
   62 #include "le_cfg_interface.h"
   63 
   64 
   65 //--------------------------------------------------------------------------------------------------
   66 /**
   67  *
   68  * Connect the current client thread to the service providing this API. Block until the service is
   69  * available.
   70  *
   71  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
   72  * called before any other functions in this API.  Normally, ConnectService is automatically called
   73  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
   74  *
   75  * This function is created automatically.
   76  */
   77 //--------------------------------------------------------------------------------------------------
   78 void le_cfgAdmin_ConnectService
   79 (
   80     void
   81 );
   82 
   83 //--------------------------------------------------------------------------------------------------
   84 /**
   85  *
   86  * Try to connect the current client thread to the service providing this API. Return with an error
   87  * if the service is not available.
   88  *
   89  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
   90  * called before any other functions in this API.  Normally, ConnectService is automatically called
   91  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
   92  *
   93  * This function is created automatically.
   94  *
   95  * @return
   96  *  - LE_OK if the client connected successfully to the service.
   97  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is bound.
   98  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
   99  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  100  */
  101 //--------------------------------------------------------------------------------------------------
  102 le_result_t le_cfgAdmin_TryConnectService
  103 (
  104     void
  105 );
  106 
  107 //--------------------------------------------------------------------------------------------------
  108 /**
  109  *
  110  * Disconnect the current client thread from the service providing this API.
  111  *
  112  * Normally, this function doesn't need to be called. After this function is called, there's no
  113  * longer a connection to the service, and the functions in this API can't be used. For details, see
  114  * @ref apiFilesC_client.
  115  *
  116  * This function is created automatically.
  117  */
  118 //--------------------------------------------------------------------------------------------------
  119 void le_cfgAdmin_DisconnectService
  120 (
  121     void
  122 );
  123 
  124 
  125 //--------------------------------------------------------------------------------------------------
  126 /**
  127  * Reference to an iterator object that can be used to iterate over the list of trees.
  128  */
  129 //--------------------------------------------------------------------------------------------------
  130 typedef struct le_cfgAdmin_Iterator* le_cfgAdmin_IteratorRef_t;
  131 
  132 //--------------------------------------------------------------------------------------------------
  133 /**
  134  * Read a subset of the configuration tree from the given filePath.  The tree then overwrites the
  135  * node at the given nodePath.
  136  *
  137  * This function will import a sub-tree as part of the iterator's current transaction.  This allows
  138  * you to create an iterator on a given node.  Import a sub-tree, and then examine the contents of
  139  * the import before deciding to commit the new data.
  140  *
  141  * @return This function will return one of the following values:
  142  *
  143  *         - LE_OK            - The commit was completed successfuly.
  144  *         - LE_FAULT         - An I/O error occured while reading the data.
  145  *         - LE_FORMAT_ERROR  - The configuration data being imported appears corrupted.
  146  */
  147 //--------------------------------------------------------------------------------------------------
  148 le_result_t le_cfgAdmin_ImportTree
  149 (
  150     le_cfg_IteratorRef_t iteratorRef,
  151         ///< [IN] Write iterator that is being used for the import.
  152 
  153     const char* filePath,
  154         ///< [IN] Import the tree data from the this file.
  155 
  156     const char* nodePath
  157         ///< [IN] Where in the tree should this import happen?  Leave
  158         ///<        as an empty string to use the iterator's current
  159         ///<        node.
  160 );
  161 
  162 //--------------------------------------------------------------------------------------------------
  163 /**
  164  * Take a node given from nodePath and stream it and it's children to the file given by filePath.
  165  *
  166  * This funciton uses the iterator's read transaction, and takes a snapshot of the current state of
  167  * the tree.  The data write happens immediately.
  168  *
  169  * @return This function will return one of the following values:
  170  *
  171  *         - LE_OK     - The commit was completed successfuly.
  172  *         - LE_FAULT  - An I/O error occured while writing the data.
  173  */
  174 //--------------------------------------------------------------------------------------------------
  175 le_result_t le_cfgAdmin_ExportTree
  176 (
  177     le_cfg_IteratorRef_t iteratorRef,
  178         ///< [IN] Write iterator that is being used for the export.
  179 
  180     const char* filePath,
  181         ///< [IN] Import the tree data from the this file.
  182 
  183     const char* nodePath
  184         ///< [IN] Where in the tree should this export happen?  Leave
  185         ///<        as an empty string to use the iterator's current
  186         ///<        node.
  187 );
  188 
  189 //--------------------------------------------------------------------------------------------------
  190 /**
  191  * Delete a tree from the system, both from the filesystem and from memory.
  192  */
  193 //--------------------------------------------------------------------------------------------------
  194 void le_cfgAdmin_DeleteTree
  195 (
  196     const char* treeName
  197         ///< [IN] Name of the tree to delete.
  198 );
  199 
  200 //--------------------------------------------------------------------------------------------------
  201 /**
  202  * Create a new iterator object for iterating over the list of trees currently managed by the
  203  * config tree daemon.
  204  */
  205 //--------------------------------------------------------------------------------------------------
  206 le_cfgAdmin_IteratorRef_t le_cfgAdmin_CreateTreeIterator
  207 (
  208     void
  209 );
  210 
  211 //--------------------------------------------------------------------------------------------------
  212 /**
  213  * Release the iterator and free it's memory back to the system.
  214  */
  215 //--------------------------------------------------------------------------------------------------
  216 void le_cfgAdmin_ReleaseTreeIterator
  217 (
  218     le_cfgAdmin_IteratorRef_t iteratorRef
  219         ///< [IN] Iterator object to release.
  220 );
  221 
  222 //--------------------------------------------------------------------------------------------------
  223 /**
  224  * Read the name of the tree currently pointed at by the iterator.
  225  *
  226  * @return LE_OK if there is enough room to copy the name into the supplied buffer.  LE_OVERFLOW if
  227  *         not.  LE_NOT_FOUND is returned if the list is empty or if the iterator hasn't been moved
  228  *         onto the first item yet.
  229  */
  230 //--------------------------------------------------------------------------------------------------
  231 le_result_t le_cfgAdmin_GetTreeName
  232 (
  233     le_cfgAdmin_IteratorRef_t iteratorRef,
  234         ///< [IN] Iterator object to read.
  235 
  236     char* name,
  237         ///< [OUT] Name of the currently referenced tree is
  238         ///<         passed in this out parameter.
  239 
  240     size_t nameNumElements
  241         ///< [IN]
  242 );
  243 
  244 //--------------------------------------------------------------------------------------------------
  245 /**
  246  * Move onto the next tree in the list.  If there are no more trees this function returns false,
  247  * otherwise true is returned.
  248  *
  249  * @return LE_OK if there are more trees to iterate through.  LE_NOT_FOUND if not.
  250  */
  251 //--------------------------------------------------------------------------------------------------
  252 le_result_t le_cfgAdmin_NextTree
  253 (
  254     le_cfgAdmin_IteratorRef_t iteratorRef
  255         ///< [IN] Iterator to iterate.
  256 );
  257 
  258 
  259 #endif // LE_CFGADMIN_INTERFACE_H_INCLUDE_GUARD
  260 
le_cfgAdmin_IteratorRef_t
struct le_cfgAdmin_Iterator * le_cfgAdmin_IteratorRef_t
Definition: le_cfgAdmin_interface.h:130
le_cfgAdmin_ReleaseTreeIterator
void le_cfgAdmin_ReleaseTreeIterator(le_cfgAdmin_IteratorRef_t iteratorRef)
le_cfg_interface.h
le_result_t
le_result_t
Definition: le_basics.h:35
le_cfgAdmin_GetTreeName
le_result_t le_cfgAdmin_GetTreeName(le_cfgAdmin_IteratorRef_t iteratorRef, char *name, size_t nameNumElements)
le_cfgAdmin_NextTree
le_result_t le_cfgAdmin_NextTree(le_cfgAdmin_IteratorRef_t iteratorRef)
le_cfgAdmin_ExportTree
le_result_t le_cfgAdmin_ExportTree(le_cfg_IteratorRef_t iteratorRef, const char *filePath, const char *nodePath)
le_cfgAdmin_ImportTree
le_result_t le_cfgAdmin_ImportTree(le_cfg_IteratorRef_t iteratorRef, const char *filePath, const char *nodePath)
le_cfgAdmin_DisconnectService
void le_cfgAdmin_DisconnectService(void)
le_cfg_IteratorRef_t
struct le_cfg_Iterator * le_cfg_IteratorRef_t
Definition: le_cfg_interface.h:346
le_cfgAdmin_CreateTreeIterator
le_cfgAdmin_IteratorRef_t le_cfgAdmin_CreateTreeIterator(void)
le_cfgAdmin_ConnectService
void le_cfgAdmin_ConnectService(void)
legato.h
le_cfgAdmin_TryConnectService
le_result_t le_cfgAdmin_TryConnectService(void)
le_cfgAdmin_DeleteTree
void le_cfgAdmin_DeleteTree(const char *treeName)