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


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_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_cfgAdmin_DisconnectHandler_t
void(* le_cfgAdmin_DisconnectHandler_t)(void *)
Definition: le_cfgAdmin_interface.h:72


le_cfg_IteratorRef_t
struct le_cfg_Iterator * le_cfg_IteratorRef_t
Definition: le_cfg_interface.h:399


le_cfgAdmin_CreateTreeIterator
le_cfgAdmin_IteratorRef_t le_cfgAdmin_CreateTreeIterator(void)


le_cfgAdmin_SetServerDisconnectHandler
void le_cfgAdmin_SetServerDisconnectHandler(le_cfgAdmin_DisconnectHandler_t disconnectHandler, void *contextPtr)


le_cfgAdmin_ConnectService
void le_cfgAdmin_ConnectService(void)



le_cfgAdmin_TryConnectService
le_result_t le_cfgAdmin_TryConnectService(void)


le_cfgAdmin_DeleteTree
void le_cfgAdmin_DeleteTree(const char *treeName)


le_cfgAdmin_GetTreeName
le_result_t le_cfgAdmin_GetTreeName(le_cfgAdmin_IteratorRef_t iteratorRef, char *name, size_t nameSize)