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     7.0.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   (0x06020000U)
  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 /** \defgroup SHUTDOWN_TYPE shutdown notification type definitions
  75  *  according to Node State Manager component
  76  * \{
  77  */
  78
  79
  80 /** \} */
  81
  82 /** \} */
  83
  84 /** definition of the change callback
  85  *
  86  * @param notifyStruct structure for notifcation
  87  *
  88  * @return positive value: success;
  89  *   On error a negative value will be returned with the following error codes: ::EPERS_LOCKFS
  90 */
  91 typedef int(* pclChangeNotifyCallback_t)(pclNotification_s * notifyStruct);
  92
  93
  94 /** \defgroup PCL_KEYVALUE functions Key-Value access
  95  * \{
  96  */
  97
  98 /**
  99  * @brief delete persistent data
 100  *
 101  * @param ldbid logical database ID
 102  * @param resource_id the resource ID
 103  * @param user_no  the user ID; user_no=0 can not be used as user-ID beacause ‘0’ is defined as System/node
 104  * @param seat_no  the seat number
 105  *
 106  * @return positive value: success; On error a negative value will be returned with the following error codes:
 107  * ::EPERS_LOCKFS ::EPERS_NOTIFY_SIG
 108  */
 109 int pclKeyDelete(unsigned int ldbid, const char* resource_id, unsigned int user_no, unsigned int seat_no);
 110
 111
 112
 113 /**
 114  * @brief gets the size of persistent data in bytes
 115  *
 116  * @param ldbid logical database ID
 117  * @param resource_id the resource ID
 118  * @param user_no  the user ID; user_no=0 can not be used as user-ID beacause ‘0’ is defined as System/node
 119  * @param seat_no  the seat number
 120  *
 121  * @return positive value: the size; On error a negative value will be returned with the following error codes:
 122  * ::EPERS_LOCKFS, ::EPERS_BADPOL, ::EPERS_NOKEY, ::EPERS_NOKEYDATA or ::EPERS_NOPRCTABLE
 123  */
 124 int pclKeyGetSize(unsigned int ldbid, const char* resource_id, unsigned int user_no, unsigned int seat_no);
 125
 126 /**
 127  * @brief close the access to a key-value identified by key handle
 128  *
 129  * @param key_handle key value handle return by key_handle_open()
 130  *
 131  * @return positive value: success; On error a negative value will be returned with the following error codes:
 132  * ::EPERS_LOCKFS
 133  */
 134 int pclKeyHandleClose(int key_handle);
 135
 136
 137
 138 /**
 139  * @brief gets the size of persistent data in bytes identified by key handle
 140  *
 141  * @param key_handle key value handle return by key_handle_open()
 142  *
 143  * @return positive value: the size; On error a negative value will be returned with the following error codes:
 144  * ::EPERS_LOCKFS
 145  */
 146 int pclKeyHandleGetSize(int key_handle);
 147
 148
 149
 150 /**
 151  * @brief open a key-value
 152  *
 153  * @param ldbid logical database ID
 154  * @param resource_id the resource ID
 155  * @param user_no  the user ID; user_no=0 can not be used as user-ID beacause ‘0’ is defined as System/node
 156  * @param seat_no  the seat number
 157  *
 158  * @return positive value: the key handle to access the value;
 159  * On error a negative value will be returned with the following error codes:
 160  * ::EPERS_LOCKFS
 161  */
 162 int pclKeyHandleOpen(unsigned int ldbid, const char* resource_id, unsigned int user_no, unsigned int seat_no);
 163
 164
 165
 166 /**
 167  * @brief reads persistent data identified by key handle
 168  *
 169  * @param key_handle key value handle return by key_handle_open()
 170  * @param buffer the buffer for persistent data
 171  * @param buffer_size size of buffer for reading
 172  *
 173  * @return positive value: the bytes read; On error a negative value will be returned with the following error codes:
 174  * ::EPERS_LOCKFS
 175  */
 176 int pclKeyHandleReadData(int key_handle, unsigned char* buffer, int buffer_size);
 177
 178
 179
 180 /**
 181  * @brief register a change notification for persistent data
 182  *
 183  * @param key_handle key value handle return by key_handle_open()
 184  * @param callback notification callback
 185  *
 186  * @return positive value: registration OK; On error a negative value will be returned with the following error codes:
 187  * ::EPERS_LOCKFS ::EPERS_MAXHANDLE ::EPERS_NOTIFY_NOT_ALLOWED
 188  */
 189 int pclKeyHandleRegisterNotifyOnChange(int key_handle, pclChangeNotifyCallback_t callback);
 190
 191 /**
 192  * @brief unregister a change notification for persistent data
 193  *
 194  * @param key_handle key value handle return by key_handle_open()
 195  * @param callback notification callback
 196  *
 197  * @return positive value: registration OK; On error a negative value will be returned with the following error codes:
 198  * ::EPERS_LOCKFS ::EPERS_MAXHANDLE ::EPERS_NOTIFY_NOT_ALLOWED
 199  */
 200 int pclKeyHandleUnRegisterNotifyOnChange(int key_handle, pclChangeNotifyCallback_t callback);
 201
 202 /**
 203  * @brief writes persistent data identified by key handle
 204  *
 205  * @param key_handle key value handle return by key_handle_open()
 206  * @param buffer the buffer containing the persistent data to write
 207  * @param buffer_size the number of bytes to write (default max size is set to 16kB)
 208  *                    use environment variable PERS_MAX_KEY_VAL_DATA_SIZE to modify default size in bytes
 209  *
 210  * @return positive value: the bytes written; On error a negative value will be returned with the following error codes:
 211  * ::EPERS_LOCKFS ::EPERS_MAX_BUFF_SIZE ::EPERS_NOTIFY_SIG
 212  */
 213 int pclKeyHandleWriteData(int key_handle, unsigned char* buffer, int buffer_size);
 214
 215
 216
 217 /**
 218  * @brief reads persistent data identified by ldbid and resource_id
 219  *
 220  * @param ldbid logical database ID
 221  * @param resource_id the resource ID
 222  * @param user_no  the user ID; user_no=0 can not be used as user-ID beacause ‘0’ is defined as System/node
 223  * @param seat_no  the seat number
 224  * @param buffer the buffer to read the persistent data
 225  * @param buffer_size size of buffer for reading
 226  *
 227  * @return positive value: the bytes read; On error a negative value will be returned with th follwoing error codes:
 228  * ::EPERS_LOCKFS
 229  */
 230 int pclKeyReadData(unsigned int ldbid, const char* resource_id, unsigned int user_no, unsigned int seat_no, unsigned char* buffer, int buffer_size);
 231
 232
 233
 234 /**
 235  * @brief register a change notification for persistent data
 236  *
 237  * @param ldbid logical database ID of the resource to monitor
 238  * @param resource_id the resource ID
 239  * @param user_no  the user ID; user_no=0 can not be used as user-ID beacause ‘0’ is defined as System/node
 240  * @param seat_no  the seat number
 241  * @param callback notification callback
 242  *
 243  * @return positive value: registration OK; On error a negative value will be returned with the following error codes:
 244  *                         ::EPERS_RES_NO_KEY ::EPERS_NOKEYDATA  ::EPERS_NOPRCTABLE ::EPERS_NOTIFY_NOT_ALLOWED
 245  */
 246 int pclKeyRegisterNotifyOnChange(unsigned int ldbid, const char* resource_id, unsigned int user_no, unsigned int seat_no, pclChangeNotifyCallback_t callback);
 247
 248
 249
 250 /**
 251  * @brief unregister a change notification for persistent data
 252  *
 253  * @param ldbid logical database ID of the resource to monitor
 254  * @param resource_id the resource ID
 255  * @param user_no  the user ID; user_no=0 can not be used as user-ID beacause ‘0’ is defined as System/node
 256  * @param seat_no  the seat number
 257  * @param callback notification callback
 258  *
 259  * @return positive value: registration OK; On error a negative value will be returned with the following error codes:
 260  *                         ::EPERS_RES_NO_KEY ::EPERS_NOKEYDATA  ::EPERS_NOPRCTABLE ::EPERS_NOTIFY_NOT_ALLOWED
 261  */
 262 int pclKeyUnRegisterNotifyOnChange( unsigned int  ldbid, const char *  resource_id, unsigned int  user_no, unsigned int  seat_no, pclChangeNotifyCallback_t  callback);
 263
 264 /**
 265  * @brief writes persistent data identified by ldbid and resource_id
 266  *
 267  * @param ldbid logical database ID
 268  * @param resource_id the resource ID
 269  * @param user_no  the user ID; user_no=0 can not be used as user-ID beacause ‘0’ is defined as System/node
 270  * @param seat_no  the seat number
 271  * @param buffer the buffer containing the persistent data to write
 272  * @param buffer_size the number of bytes to write (default max size is set to 16kB)
 273  *                    use environment variable PERS_MAX_KEY_VAL_DATA_SIZE to modify default size in bytes
 274  *
 275  * @return positive value: the bytes written; On error a negative value will be returned with the following error codes:
 276  * ::EPERS_LOCKFS ::EPERS_NOTIFY_NOT_ALLOWED
 277  */
 278 int pclKeyWriteData(unsigned int ldbid, const char* resource_id, unsigned int user_no, unsigned int seat_no, unsigned char* buffer, int buffer_size);
 279
 280 /** \} */
 281
 282 #ifdef __cplusplus
 283 }
 284 #endif
 285
 286 /** \} */ /* End of API */
 287 /** \} */ /* End of MODULE */
 288
 289 #endif /* PERSISTENCY_CLIENT_LIBRARY_KEY_H */