include/persistence_client_custom.h

   1 #ifndef PERSISTENCE_CLIENT_LIBRARY_CUSTOM_H
   2 #define PERSISTENCE_CLIENT_LIBRARY_CUSTOM_H
   3
   4 /******************************************************************************
   5  * Project         Persistency
   6  * (c) copyright   2012
   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 ******************************************************************************/
  14  /**
  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
  20  * @par change history
  21  *    Date       Author    Version  Description
  22  *  - 2014.01.20 iieremie  1.6.0.0  multiple extensions:
  23  *                                  - error codes
  24  *                                  - asynchronous init/deinit
  25  *                                  - sync(flush) data
  26  *                                  - clear all data
  27  *                                  - get info
  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
  35  */
  36
  37
  38 /** \ingroup GEN_PERS_CLIENTLIB_INTERFACE API document
  39  *  \{
  40  */
  41
  42 /** \defgroup PCCL_INTERFACE_VERSION persistence_client_custom version
  43  *  \{
  44  */
  45
  46 /** Module version
  47 The lower significant byte is equal 0 for released version only
  48 */
  49 #define     PERSIST_CUSTOMER_INTERFACE_VERSION            (0x01060000U)
  50
  51 /** \} */ /* End of Errors */
  52
  53 /**
  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.
  57  * Example:
  58  * function name: plugin_open
  59  * Loaded plugin name: hwi
  60  * Generated function: hwi_plugin_open
  61  */
  62
  63
  64 /** \defgroup PCCL_RETURNS persistence_client_custom Return Values
  65  * ::PCCL_SUCCESS, ::PCCL_ERROR_CODE..::PCCL_FAILURE_INVALID_PARAMETER
  66
  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
  70  *  \{
  71  */
  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 */
  75
  76 #define PCCL_SUCCESS                             0x00000000                  /*!< the function call succeded */
  77
  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 */
  88
  89 #define PCCL_FAILURE                            (PCCL_ERROR_CODE - 0xFFFF)   /*!< should be the max. value for error */
  90
  91 #define PCCL_WARNING_CODE                       (PCCL_BASERETURN_CODE)       /*!< basis of the warning (positive values) */
  92
  93 /** \} */ /* End of Errors */
  94
  95
  96 /** \defgroup PCCL_FUNCTIONS persistence_client_custom Functions
  97  *  \{
  98  */
  99
 100 /**
 101  * @brief typdef of callback function prototype for asynchronous init/deinit
 102  *
 103  * @param errcode - pass \ref PCCL_SUCCESS or an error code (\ref PCCL_RETURNS)
 104  */
 105 typedef int (*plugin_callback_async_t) (int errcode);
 106
 107 /**
 108  * @brief initialize plugin (blocking)
 109  *
 110  * @return positive value: init success; negative value: error code (\ref PCCL_RETURNS)
 111  *
 112  * @note
 113  *       - This (or \ref plugin_init_async) is the first function to call from this interface
 114  *       - The call is blocking
 115  */
 116 int plugin_init();
 117
 118 /**
 119  * @brief initialize plugin (non blocking)
 120  *
 121  * @param pfInitCompletedCB the callback to be called when the initialization is complete
 122  *
 123  * @return positive value: init success; negative value: error code (\ref PCCL_RETURNS)
 124  *
 125  * @note
 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.
 129  */
 130 int plugin_init_async(plugin_callback_async_t pfInitCompletedCB);
 131
 132  /**
 133  * @brief deinitialize plugin (during shutdown)
 134  *
 135  * @return positive value: deinit success; negative value: error code (\ref PCCL_RETURNS)
 136  *
 137  * @note
 138  *       - This is the last function to call from this interface
 139  *       - The call is blocking.
 140  */
 141 int plugin_deinit();
 142
 143
 144 /**
 145  * @brief delete data
 146  *
 147  * @param path the path to the data to delete
 148  *
 149  * @return positive value: delete success; negative value: error code (\ref PCCL_RETURNS)
 150  */
 151 int plugin_delete_data(const char* path);
 152
 153
 154 /**
 155  * @brief gets the size of persistent data in bytes
 156  *
 157  * @param path the path to the data
 158  *
 159  * @return positive value: the size; negative value: error code (\ref PCCL_RETURNS)
 160  */
 161 int plugin_get_size(const char* path);
 162
 163 /**
 164  * @brief get data
 165  *
 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
 169  *
 170  * @return positive value: size data read in bytes; negative value: error code (\ref PCCL_RETURNS)
 171  */
 172 int plugin_get_data(const char* path, char* buffer, int size);
 173
 174 /**
 175  * @brief close the given handle
 176  *
 177  * @param handle the handle to close
 178  *
 179  * @return positive value: successfully closed; negative value: error code (\ref PCCL_RETURNS)
 180  */
 181 int plugin_handle_close(int handle);
 182
 183 /**
 184  * @brief get data
 185  *
 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
 189  *
 190  * @return positive value: size data read in bytes; negative value: error code (\ref PCCL_RETURNS)
 191  */
 192 int plugin_handle_get_data(int handle, char* buffer, int size);
 193
 194 /**
 195  * @brief open a resource
 196  *
 197  * @param path the path to the resource to open
 198  * @param flag open flags
 199  * @param mode the open mode
 200  *
 201  * @return positive value: handle; negative value: error code (\ref PCCL_RETURNS)
 202  */
 203 int plugin_handle_open(const char* path, int flag, int mode);
 204
 205 /**
 206  * @brief set data
 207  *
 208  * @param handle the handle given by open
 209  * @param buffer the data to write
 210  * @param size the number of bytes to write
 211  *
 212  * @return positive size data set; negative value: error code (\ref PCCL_RETURNS)
 213  */
 214 int plugin_handle_set_data(int handle, char* buffer, int size);
 215
 216 /**
 217  * @brief create backup of the container's data
 218  *
 219  * @param backup_id backup destination's pathname (e.g. /tmp/bkup/mybackup.bk)
 220  *
 221  * @return positive value: backup success (size of backup, bytes); negative value: error code (\ref PCCL_RETURNS)
 222  *
 223  * @note
 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 !
 228  */
 229 int plugin_create_backup(const char* backup_id);
 230
 231 /**
 232  * @brief get backup name
 233  *
 234  * @param backup_id Name of the backup / identifier
 235  * @param size size of the buffer to return the identifier
 236  *
 237  * @return positive value: success, length of identifier; negative value: error code (\ref PCCL_RETURNS)
 238  * TO DO: What is the idea ?
 239  */
 240 int plugin_get_backup(char* backup_id, int size);
 241
 242 /**
 243  * @brief restore backup
 244  *
 245  * @param backup_id backup source's pathname (e.g. /tmp/bkup/mybackup.bk)
 246  *
 247  * @return positive value: backup success (size of backup, bytes); negative value: error code (\ref PCCL_RETURNS)
 248  *
 249  * @note
 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 !
 253  */
 254 int plugin_restore_backup(const char* backup_id);
 255
 256 /**
 257  * @brief clear data (delete values for all the resources)
 258  *
 259  * @return positive value: success; negative value: error code (\ref PCCL_RETURNS)
 260  *
 261  * @note
 262  *       - the new (empty) data content is flushed to non-volatile storage
 263  *       - To be used only by Persistence Administrator Service !
 264  */
 265 int plugin_clear_all_data(void);
 266
 267 /**
 268  * @brief set data
 269  *
 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
 273  *
 274  * @return positive size data set; negative value: error code (\ref PCCL_RETURNS)
 275  */
 276 int plugin_set_data(const char* path, char* buffer, int size);
 277
 278 /**
 279  * @brief typdef of callback function prototype
 280  *
 281  * @param int pass a statusId to the function
 282  * @param void* pass an argument to the function
 283  */
 284 typedef int (*plugin_callback_t) (int, void*);
 285
 286 /**
 287  * @brief registercallback for status notifications
 288  *
 289  * @param pFunct the callback
 290  *
 291  * @return positive value: register success; negative value error code (\ref PCCL_RETURNS)
 292  */
 293 int plugin_get_status_notification_clbk(plugin_callback_t pFunct);
 294
 295 /**
 296  * @brief get size
 297  *
 298  * @param handle the handle given by open
 299  *
 300  * @return positive value: the size; negative value: error error code (\ref PCCL_RETURNS)
 301  */
 302 int plugin_handle_get_size(int handle);
 303
 304 /**
 305  * @brief flush the cache (if used) into the non-volatile storage
 306  *
 307  * @return positive value for success; negative value: error code (\ref PCCL_RETURNS)
 308  *
 309  * @note
 310  *       - To be used only by Persistence Administrator Service !
 311  */
 312 int plugin_sync(void);
 313
 314 /**
 315  * @brief information to be provided as status
 316  */
 317 typedef struct _plugin_info_s
 318 {
 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 */
 322 }plugin_info_s ;
 323
 324 /**
 325  * @brief get the status information for the plugin's data
 326  *
 327  * @param pInfo_out the status information
 328  *
 329  * @return positive value for success; negative value: error code (\ref PCCL_RETURNS)
 330  *
 331  * @note
 332  *       - To be used only by Persistence Administrator Service !
 333  */
 334 int plugin_get_info(plugin_info_s* pInfo_out);
 335
 336 /** \} */
 337 /** \} */
 338
 339 #endif /* PERSISTENCE_CLIENT_LIBRARY_CUSTOM_H */
 340 /** \} */ /* End of INTERFACE */
 341