include/persistence_client_library_key.h

   1 #ifndef PERSISTENCE_CLIENT_LIBRARY_KEY_H
   2 #define PERSISTENCE_CLIENT_LIBRARY_KEY_H
   3
   4 /******************************************************************************
   5  * Project         Persistency
   6  * (c) copyright   2011
   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_library_key.h
  16  * @ingroup        Persistence client library
  17  * vauthor         Ingo Huerner (XSe) / Guy Sagnes (Continental)
  18  * @brief          Header of the persistence client library.
  19  *                 Library provides an API to access persistent data
  20  * @par change history
  21  * Date     Author          Version
  22  * 27/03/13 Ingo Hürner     4.0.0 - Add registration for callback notification
  23  * 28/05/13 Ingo Hürner     5.0.0 - Add pclInitLibrary(), pcl DeInitLibrary() incl. shutdown notification
  24  * 05/06/13 Oliver Bach     6.0.0 - Rework of Init functions
  25  * 04/11/13 Ingo Hürner     6.1.0 - Added functions to unregister notifications
  26  */
  27 /** \ingroup GEN_PERS */
  28 /** \defgroup PERS_KEYVALUE Client: Key-value access
  29  *  \{
  30  */
  31 /** \defgroup PERS_KEYVALUE_INTERFACE API document
  32  *  \{
  33  */
  34
  35 #ifdef __cplusplus
  36 extern "C" {
  37 #endif
  38
  39 /** \defgroup PCL_DEFINES_KEYVALUE Defines, Struct, Enum
  40  * \{
  41  */
  42
  43 #define  PERSIST_KEYVALUEAPI_INTERFACE_VERSION   (0x06010000U)
  44
  45 #include "persistence_client_library.h"
  46
  47
  48 /**
  49 * status returned in notification structure
  50 */
  51 typedef enum _pclNotifyStatus_e
  52 {
  53    pclNotifyStatus_no_changed = 0,
  54    pclNotifyStatus_created,
  55    pclNotifyStatus_changed,
  56    pclNotifyStatus_deleted,
  57    /* insert new_ entries here .. */
  58    pclNotifyStatus_lastEntry
  59 } pclNotifyStatus_e;
  60
  61
  62 /**
  63 * structure to return in case of notification
  64 */
  65 typedef struct _pclNotification_s
  66 {
  67    pclNotifyStatus_e pclKeyNotify_Status;    /// notification status
  68    unsigned int ldbid;                       /// logical db id
  69    const char * resource_id;                 /// resource id
  70    unsigned int user_no;                     /// user id
  71    unsigned int seat_no;                     /// seat id
  72 } pclNotification_s;
  73
  74
  75
  76 /** \} */
  77
  78
  79 /** definition of the change callback
  80  *
  81  * @param notifyStruct structure for notifcation
  82  *
  83  * @return positive value (0 or greater): success;
  84  * On error a negative value will be returned with the following error codes: ::EPERS_LOCKFS
  85 */
  86 typedef int(* pclChangeNotifyCallback_t)(pclNotification_s * notifyStruct);
  87
  88
  89 /** \defgroup PCL_KEYVALUE functions Key-Value access
  90  * \{
  91  */
  92
  93 /**
  94  * @brief delete persistent data
  95  *
  96  * @param ldbid logical database ID
  97  * @param resource_id the resource ID
  98  * @param user_no  the user ID; user_no=0 can not be used as user-ID beacause ‘0’ is defined as System/node
  99  * @param seat_no  the seat number
 100  *
 101  * @return positive value (0 or greater) : success;
 102  * On error a negative value will be returned with the following error codes:
 103  * ::EPERS_LOCKFS, ::EPERS_NOTIFY_SIG, ::EPERS_NOT_INITIALIZED, ::EPERS_BADPOL
 104  */
 105 int pclKeyDelete(unsigned int ldbid, const char* resource_id, unsigned int user_no, unsigned int seat_no);
 106
 107
 108
 109 /**
 110  * @brief gets the size of persistent data in bytes
 111  *
 112  * @param ldbid logical database ID
 113  * @param resource_id the resource ID
 114  * @param user_no  the user ID; user_no=0 can not be used as user-ID beacause ‘0’ is defined as System/node
 115  * @param seat_no  the seat number
 116  *
 117  * @return positive value (0 or greater): the size;
 118  * On error a negative value will be returned with the following error codes:
 119  * ::EPERS_LOCKFS, ::EPERS_BADPOL, ::EPERS_NOKEY, ::EPERS_NOKEYDATA or ::EPERS_NOPRCTABLE
 120  * ::EPERS_NOT_INITIALIZED
 121  */
 122 int pclKeyGetSize(unsigned int ldbid, const char* resource_id, unsigned int user_no, unsigned int seat_no);
 123
 124 /**
 125  * @brief close the access to a key-value identified by key handle
 126  *
 127  * @param key_handle key value handle return by key_handle_open()
 128  *
 129  * @return positive value (0 or greater): success;
 130  * On error a negative value will be returned with the following error codes:
 131  * ::EPERS_LOCKFS ::EPERS_MAXHANDLE ::EPERS_NOPLUGINFUNCT ::EPERS_NOT_INITIALIZED
 132  */
 133 int pclKeyHandleClose(int key_handle);
 134
 135
 136
 137 /**
 138  * @brief gets the size of persistent data in bytes identified by key handle
 139  *
 140  * @param key_handle key value handle return by key_handle_open()
 141  *
 142  * @return positive value (0 or greater): the size;
 143  * On error a negative value will be returned with the following error codes:
 144  * ::EPERS_NOT_INITIALIZED ::EPERS_LOCKFS ::EPERS_NOPLUGINFUNCT ::EPERS_MAXHANDLE
 145  * ::EPERS_NOKEY ::EPERS_DB_KEY_SIZE ::EPERS_NOPRCTABLE
 146  */
 147 int pclKeyHandleGetSize(int key_handle);
 148
 149
 150
 151 /**
 152  * @brief open a key-value
 153  *
 154  * @param ldbid logical database ID
 155  * @param resource_id the resource ID
 156  * @param user_no  the user ID; user_no=0 can not be used as user-ID beacause ‘0’ is defined as System/node
 157  * @param seat_no  the seat number
 158  *
 159  * @return positive value (0 or greater): the key handle to access the value;
 160  * On error a negative value will be returned with the following error codes:
 161  * ::EPERS_NOT_INITIALIZED ::EPERS_NOPLUGINFUNCT ::
 162  */
 163 int pclKeyHandleOpen(unsigned int ldbid, const char* resource_id, unsigned int user_no, unsigned int seat_no);
 164
 165
 166
 167 /**
 168  * @brief reads persistent data identified by key handle
 169  *
 170  * @param key_handle key value handle return by key_handle_open()
 171  * @param buffer the buffer for persistent data
 172  * @param buffer_size size of buffer for reading
 173  *
 174  * @return positive value (0 or greater): the bytes read;
 175  * On error a negative value will be returned with the following error codes:
 176  * ::EPERS_NOT_INITIALIZED ::EPERS_NOPLUGINFUNCT ::EPERS_MAXHANDLE
 177  */
 178 int pclKeyHandleReadData(int key_handle, unsigned char* buffer, int buffer_size);
 179
 180
 181
 182 /**
 183  * @brief register a change notification for persistent data
 184  *
 185  * @param key_handle key value handle return by key_handle_open()
 186  * @param callback notification callback
 187  *
 188  * @return positive value (0 or greater): registration OK;
 189  * On error a negative value will be returned with the following error codes:
 190  * ::EPERS_NOT_INITIALIZED ::EPERS_MAXHANDLE ::EPERS_NOTIFY_NOT_ALLOWED
 191  */
 192 int pclKeyHandleRegisterNotifyOnChange(int key_handle, pclChangeNotifyCallback_t callback);
 193
 194
 195
 196 /**
 197  * @brief unregister a change notification for persistent data
 198  *
 199  * @param key_handle key value handle return by key_handle_open()
 200  * @param callback notification callback
 201  *
 202  * @return positive value (0 or greater): registration OK;
 203  * On error a negative value will be returned with the following error codes:
 204  * ::EPERS_NOT_INITIALIZED ::EPERS_LOCKFS ::EPERS_MAXHANDLE ::EPERS_NOTIFY_NOT_ALLOWED
 205  */
 206 int pclKeyHandleUnRegisterNotifyOnChange(int key_handle, pclChangeNotifyCallback_t callback);
 207
 208
 209
 210 /**
 211  * @brief writes persistent data identified by key handle
 212  *
 213  * @param key_handle key value handle return by key_handle_open()
 214  * @param buffer the buffer containing the persistent data to write
 215  * @param buffer_size the number of bytes to write (default max size is set to 16kB)
 216  *                    use environment variable PERS_MAX_KEY_VAL_DATA_SIZE to modify default size in bytes
 217  *
 218  * @return positive value (0 or greater): the bytes written;
 219  * On error a negative value will be returned with the following error codes:
 220  * ::EPERS_LOCKFS ::EPERS_MAX_BUFF_SIZE ::EPERS_NOTIFY_SIG ::EPERS_DB_VALUE_SIZE ::EPERS_DB_KEY_SIZE
 221  * ::EPERS_NOPRCTABLE ::EPERS_DB_VALUE_SIZE ::EPERS_RESOURCE_READ_ONLY
 222  */
 223 int pclKeyHandleWriteData(int key_handle, unsigned char* buffer, int buffer_size);
 224
 225
 226
 227 /**
 228  * @brief reads persistent data identified by ldbid and resource_id
 229  *
 230  * @param ldbid logical database ID
 231  * @param resource_id the resource ID
 232  * @param user_no  the user ID; user_no=0 can not be used as user-ID beacause ‘0’ is defined as System/node
 233  * @param seat_no  the seat number
 234  * @param buffer the buffer to read the persistent data
 235  * @param buffer_size size of buffer for reading
 236  *
 237  * @return positive value (0 or greater): the bytes read;
 238  * On error a negative value will be returned with th following error codes:
 239  * ::EPERS_LOCKFS ::EPERS_NOT_INITIALIZED ::EPERS_BADPOL ::EPERS_NOPLUGINFUNCT
 240  */
 241 int pclKeyReadData(unsigned int ldbid, const char* resource_id, unsigned int user_no, unsigned int seat_no, unsigned char* buffer, int buffer_size);
 242
 243
 244
 245 /**
 246  * @brief register a change notification for persistent data
 247  *
 248  * @param ldbid logical database ID of the resource to monitor
 249  * @param resource_id the resource ID
 250  * @param user_no  the user ID; user_no=0 can not be used as user-ID beacause ‘0’ is defined as System/node
 251  * @param seat_no  the seat number
 252  * @param callback notification callback
 253  *
 254  * @return positive value (0 or greater): registration OK;
 255  * On error a negative value will be returned with the following error codes:
 256  * ::EPERS_RES_NO_KEY ::EPERS_NOKEYDATA  ::EPERS_NOPRCTABLE ::EPERS_NOTIFY_NOT_ALLOWED
 257  */
 258 int pclKeyRegisterNotifyOnChange(unsigned int ldbid, const char* resource_id, unsigned int user_no, unsigned int seat_no, pclChangeNotifyCallback_t callback);
 259
 260
 261
 262 /**
 263  * @brief unregister a change notification for persistent data
 264  *
 265  * @param ldbid logical database ID of the resource to monitor
 266  * @param resource_id the resource ID
 267  * @param user_no  the user ID; user_no=0 can not be used as user-ID beacause ‘0’ is defined as System/node
 268  * @param seat_no  the seat number
 269  * @param callback notification callback
 270  *
 271  * @return positive value (0 or greater): registration OK;
 272  * On error a negative value will be returned with the following error codes:
 273  * ::EPERS_RES_NO_KEY ::EPERS_NOKEYDATA  ::EPERS_NOPRCTABLE ::EPERS_NOTIFY_NOT_ALLOWED
 274  */
 275 int pclKeyUnRegisterNotifyOnChange( unsigned int  ldbid, const char *  resource_id, unsigned int  user_no, unsigned int  seat_no, pclChangeNotifyCallback_t  callback);
 276
 277
 278
 279 /**
 280  * @brief writes persistent data identified by ldbid and resource_id
 281  *
 282  * @param ldbid logical database ID
 283  * @param resource_id the resource ID
 284  * @param user_no  the user ID; user_no=0 can not be used as user-ID beacause ‘0’ is defined as System/node
 285  * @param seat_no  the seat number
 286  * @param buffer the buffer containing the persistent data to write
 287  * @param buffer_size the number of bytes to write (default max size is set to 16kB)
 288  *                    use environment variable PERS_MAX_KEY_VAL_DATA_SIZE to modify default size in bytes
 289  *
 290  * @return positive value (0 or greater): the bytes written;
 291  * On error a negative value will be returned with the following error codes:
 292  * ::EPERS_LOCKFS ::EPERS_BADPOL ::EPERS_BUFLIMIT ::EPERS_DB_VALUE_SIZE ::EPERS_DB_KEY_SIZE
 293  * ::EPERS_NOTIFY_SIG ::EPERS_RESOURCE_READ_ONLY
 294  */
 295 int pclKeyWriteData(unsigned int ldbid, const char* resource_id, unsigned int user_no, unsigned int seat_no, unsigned char* buffer, int buffer_size);
 296
 297
 298 /** \} */
 299
 300 #ifdef __cplusplus
 301 }
 302 #endif
 303
 304 /** \} */ /* End of API */
 305 /** \} */ /* End of MODULE */
 306
 307 #endif /* PERSISTENCY_CLIENT_LIBRARY_KEY_H */