1 #ifndef PERSISTENCE_CLIENT_LIBRARY_CUSTOM_H
2 #define PERSISTENCE_CLIENT_LIBRARY_CUSTOM_H
4 /******************************************************************************
7 * Company XS Embedded GmbH
8 *****************************************************************************/
9 /******************************************************************************
10 * This Source Code Form is subject to the terms of the
11 * Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed
12 * with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
13 ******************************************************************************/
15 * @file persistence_client_custom.h
16 * @ingroup Persistence client library
17 * @author Ingo Huerner (XSe) / Guy Sagnes (Continental) / Ionut Ieremie (Continental)
18 * @brief Header of the persistence client library custom plugin.
19 * Library provides an plugin API to extend persistence client library
21 * Date Author Version Description
22 * - 2014.01.20 iieremie 1.6.0.0 multiple extensions:
24 * - asynchronous init/deinit
28 * - added explanations
29 * - 2013.06.26 ihuerner 1.5.0.0 added description of parameters
30 * - 2013.01.06 ihuerner 1.4.0.0 plugin_handle_open and plugin_set_data changed from char* to const char*
31 * - 2012.11.22 gsagnes 1.3.0.0 add the handle_get_size, correct the type to int
32 * - 2012.10.16 gsagnes 1.2.0.0 add get_size, create_backup, restore_backup
33 * - 2012.10.04 gsagnes 1.1.0.0 add deinitialisation functionality (call during shutdown)
34 * - 2012.07.14 ihuerner 1.0.0.0 Initial version of the interface
38 /** \ingroup GEN_PERS_CLIENTLIB_INTERFACE API document
42 /** \defgroup PCCL_INTERFACE_VERSION persistence_client_custom version
47 The lower significant byte is equal 0 for released version only
49 #define PERSIST_CUSTOMER_INTERFACE_VERSION (0x01060000U)
51 /** \} */ /* End of Errors */
54 * <b>Plugin interface:</b>
55 * All plugins in a specual location will be loaded, and according
56 * to the plugin name functions will created.
58 * function name: plugin_open
59 * Loaded plugin name: hwi
60 * Generated function: hwi_plugin_open
64 /** \defgroup PCCL_RETURNS persistence_client_custom Return Values
65 * ::PCCL_SUCCESS, ::PCCL_ERROR_CODE..::PCCL_FAILURE_INVALID_PARAMETER
67 * These defines are used to define the return values of the interface functions
68 * - ::PCCL_SUCCESS: the function call succeded
69 * - ::PCCL_ERROR_CODE..::PCCL_FAILURE: the function call failed
72 /* Error code return by the SW Package, related to SW_PackageID. */
73 #define PCCL_PACKAGEID 0x013 /*!< Software package identifier, use for return value base */
74 #define PCCL_BASERETURN_CODE (PCCL_PACKAGEID << 16) /*!< Basis of the return value containing SW PackageID */
76 #define PCCL_SUCCESS 0x00000000 /*!< the function call succeded */
78 #define PCCL_ERROR_CODE (-(PCCL_BASERETURN_CODE)) /*!< basis of the error (negative values) */
79 #define PCCL_FAILURE_NOT_INITIALIZED (PCCL_ERROR_CODE - 1) /*!< try to access functionality before initialization */
80 #define PCCL_FAILURE_INVALID_PARAMETER (PCCL_ERROR_CODE - 2) /*!< Invalid parameter in the API call */
81 #define PCCL_FAILURE_BUFFER_TOO_SMALL (PCCL_ERROR_CODE - 3) /*!< The provided buffer can not accommodate the available data size */
82 #define PCCL_FAILURE_OUT_OF_MEMORY (PCCL_ERROR_CODE - 4) /*!< not enough memory, malloc failed, no handler available */
83 #define PCCL_FAILURE_INVALID_FORMAT (PCCL_ERROR_CODE - 5) /*!< format of the path is not as expected */
84 #define PCCL_FAILURE_NOT_FOUND (PCCL_ERROR_CODE - 6) /*!< e.g. a folder/file is not found */
85 #define PCCL_FAILURE_NO_DATA (PCCL_ERROR_CODE - 7) /*!< no data available for the key */
86 #define PCCL_FAILURE_ACCESS_DENIED (PCCL_ERROR_CODE - 8) /*!< tried to access a file without having the right */
87 #define PCCL_FAILURE_OPERATION_NOT_SUPPORTED (PCCL_ERROR_CODE - 9) /*!< operation not (yet) supported */
89 #define PCCL_FAILURE (PCCL_ERROR_CODE - 0xFFFF) /*!< should be the max. value for error */
91 #define PCCL_WARNING_CODE (PCCL_BASERETURN_CODE) /*!< basis of the warning (positive values) */
93 /** \} */ /* End of Errors */
96 /** \defgroup PCCL_FUNCTIONS persistence_client_custom Functions
101 * @brief typdef of callback function prototype for asynchronous init/deinit
103 * @param errcode - pass \ref PCCL_SUCCESS or an error code (\ref PCCL_RETURNS)
105 typedef int (*plugin_callback_async_t) (int errcode);
108 * @brief initialize plugin (blocking)
110 * @return positive value: init success; negative value: error code (\ref PCCL_RETURNS)
113 * - This (or \ref plugin_init_async) is the first function to call from this interface
114 * - The call is blocking
119 * @brief initialize plugin (non blocking)
121 * @param pfInitCompletedCB the callback to be called when the initialization is complete
123 * @return positive value: init success; negative value: error code (\ref PCCL_RETURNS)
126 * - This (or \ref plugin_init) is the first function to call from this interface
127 * - The call returns immediatelly.
128 * - Later, pfInitCompletedCB will be called when the initialization is complete.
130 int plugin_init_async(plugin_callback_async_t pfInitCompletedCB);
133 * @brief deinitialize plugin (during shutdown)
135 * @return positive value: deinit success; negative value: error code (\ref PCCL_RETURNS)
138 * - This is the last function to call from this interface
139 * - The call is blocking.
147 * @param path the path to the data to delete
149 * @return positive value: delete success; negative value: error code (\ref PCCL_RETURNS)
151 int plugin_delete_data(const char* path);
155 * @brief gets the size of persistent data in bytes
157 * @param path the path to the data
159 * @return positive value: the size; negative value: error code (\ref PCCL_RETURNS)
161 int plugin_get_size(const char* path);
166 * @param path the path to the resource to get
167 * @param buffer the buffer to store data
168 * @param size the number of bytes to get data
170 * @return positive value: size data read in bytes; negative value: error code (\ref PCCL_RETURNS)
172 int plugin_get_data(const char* path, char* buffer, int size);
175 * @brief close the given handle
177 * @param handle the handle to close
179 * @return positive value: successfully closed; negative value: error code (\ref PCCL_RETURNS)
181 int plugin_handle_close(int handle);
186 * @param handle the handle returned from open
187 * @param buffer the buffer to store data
188 * @param size the number of bytes to get data
190 * @return positive value: size data read in bytes; negative value: error code (\ref PCCL_RETURNS)
192 int plugin_handle_get_data(int handle, char* buffer, int size);
195 * @brief open a resource
197 * @param path the path to the resource to open
198 * @param flag open flags
199 * @param mode the open mode
201 * @return positive value: handle; negative value: error code (\ref PCCL_RETURNS)
203 int plugin_handle_open(const char* path, int flag, int mode);
208 * @param handle the handle given by open
209 * @param buffer the data to write
210 * @param size the number of bytes to write
212 * @return positive size data set; negative value: error code (\ref PCCL_RETURNS)
214 int plugin_handle_set_data(int handle, char* buffer, int size);
217 * @brief create backup of the container's data
219 * @param backup_id backup destination's pathname (e.g. /tmp/bkup/mybackup.bk)
221 * @return positive value: backup success (size of backup, bytes); negative value: error code (\ref PCCL_RETURNS)
224 * - The path (e.g. /tmp/bkup/ for our example) has to exist and to be accessible
225 * - The format of backup file is in responsibility of the customer plugin
226 * - The backup shall be created using the data in persistent storage (obtained after last \ref plugin_sync)
227 * - To be used only by Persistence Administrator Service !
229 int plugin_create_backup(const char* backup_id);
232 * @brief get backup name
234 * @param backup_id Name of the backup / identifier
235 * @param size size of the buffer to return the identifier
237 * @return positive value: success, length of identifier; negative value: error code (\ref PCCL_RETURNS)
238 * TO DO: What is the idea ?
240 int plugin_get_backup(char* backup_id, int size);
243 * @brief restore backup
245 * @param backup_id backup source's pathname (e.g. /tmp/bkup/mybackup.bk)
247 * @return positive value: backup success (size of backup, bytes); negative value: error code (\ref PCCL_RETURNS)
250 * - The source has to be compatible (i.e. obtained with \ref plugin_create_backup)
251 * - The backup's data has first to be stored persistent and then reloaded in cache (if used)
252 * - To be used only by Persistence Administrator Service !
254 int plugin_restore_backup(const char* backup_id);
257 * @brief clear data (delete values for all the resources)
259 * @return positive value: success; negative value: error code (\ref PCCL_RETURNS)
262 * - the new (empty) data content is flushed to non-volatile storage
263 * - To be used only by Persistence Administrator Service !
265 int plugin_clear_all_data(void);
270 * @param path the path to the resource to set
271 * @param buffer the data to write
272 * @param size the number of bytes to write
274 * @return positive size data set; negative value: error code (\ref PCCL_RETURNS)
276 int plugin_set_data(const char* path, char* buffer, int size);
279 * @brief typdef of callback function prototype
281 * @param int pass a statusId to the function
282 * @param void* pass an argument to the function
284 typedef int (*plugin_callback_t) (int, void*);
287 * @brief registercallback for status notifications
289 * @param pFunct the callback
291 * @return positive value: register success; negative value error code (\ref PCCL_RETURNS)
293 int plugin_get_status_notification_clbk(plugin_callback_t pFunct);
298 * @param handle the handle given by open
300 * @return positive value: the size; negative value: error error code (\ref PCCL_RETURNS)
302 int plugin_handle_get_size(int handle);
305 * @brief flush the cache (if used) into the non-volatile storage
307 * @return positive value for success; negative value: error code (\ref PCCL_RETURNS)
310 * - To be used only by Persistence Administrator Service !
312 int plugin_sync(void);
315 * @brief information to be provided as status
317 typedef struct _plugin_info_s
319 long used_size ; /*!< The current total size in bytes of the data */
320 long available_size ; /*!< The current available size in bytes */
321 long number_of_items ; /*!< The current number of resources inside the plugin */
325 * @brief get the status information for the plugin's data
327 * @param pInfo_out the status information
329 * @return positive value for success; negative value: error code (\ref PCCL_RETURNS)
332 * - To be used only by Persistence Administrator Service !
334 int plugin_get_info(plugin_info_s* pInfo_out);
339 #endif /* PERSISTENCE_CLIENT_LIBRARY_CUSTOM_H */
340 /** \} */ /* End of INTERFACE */