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  */
  26 /** \ingroup GEN_PERS */
  27 /** \defgroup PERS_KEYVALUE Client: Key-value access
  28  *  \{
  29  */
  30 /** \defgroup PERS_KEYVALUE_INTERFACE API document
  31  *  \{
  32  */
  33
  34 #ifdef __cplusplus
  35 extern "C" {
  36 #endif
  37
  38 /** \defgroup PCL_DEFINES_KEYVALUE Defines, Struct, Enum
  39  * \{
  40  */
  41
  42 #define  PERSIST_KEYVALUEAPI_INTERFACE_VERSION   (0x06010000U)
  43
  44 #include "persistence_client_library.h"
  45
  46
  47 /**
  48 * status returned in notification structure
  49 */
  50 typedef enum _pclNotifyStatus_e
  51 {
  52    pclNotifyStatus_no_changed = 0,
  53    pclNotifyStatus_created,
  54    pclNotifyStatus_changed,
  55    pclNotifyStatus_deleted,
  56    /* insert new_ entries here .. */
  57    pclNotifyStatus_lastEntry
  58 } pclNotifyStatus_e;
  59
  60
  61 /**
  62 * structure to return in case of notification
  63 */
  64 typedef struct _pclNotification_s
  65 {
  66    pclNotifyStatus_e pclKeyNotify_Status;    /// notification status
  67    unsigned int ldbid;                       /// logical db id
  68    const char * resource_id;                 /// resource id
  69    unsigned int user_no;                     /// user id
  70    unsigned int seat_no;                     /// seat id
  71 } pclNotification_s;
  72
  73 /** \defgroup SHUTDOWN_TYPE shutdown notification type definitions
  74  *  according to Node State Manager component
  75  * \{
  76  */
  77
  78
  79 /** \} */
  80
  81 /** \} */
  82
  83 /** definition of the change callback
  84  *
  85  * @param notifyStruct structure for notifcation
  86  *
  87  * @return positive value: success;
  88  *   On error a negative value will be returned with the following error codes: ::EPERS_LOCKFS
  89 */
  90 typedef int(* pclChangeNotifyCallback_t)(pclNotification_s * notifyStruct);
  91
  92
  93 /** \defgroup PCL_KEYVALUE functions Key-Value access
  94  * \{
  95  */
  96
  97 /**
  98  * @brief delete persistent data
  99  *
 100  * @param ldbid logical database ID
 101  * @param resource_id the resource ID
 102  * @param user_no  the user ID; user_no=0 can not be used as user-ID beacause ‘0’ is defined as System/node
 103  * @param seat_no  the seat number
 104  *
 105  * @return positive value: success; On error a negative value will be returned with the following error codes:
 106  * ::EPERS_LOCKFS
 107  */
 108 int pclKeyDelete(unsigned int ldbid, const char* resource_id, unsigned int user_no, unsigned int seat_no);
 109
 110
 111
 112 /**
 113  * @brief gets the size of persistent data in bytes
 114  *
 115  * @param ldbid logical database ID
 116  * @param resource_id the resource ID
 117  * @param user_no  the user ID; user_no=0 can not be used as user-ID beacause ‘0’ is defined as System/node
 118  * @param seat_no  the seat number
 119  *
 120  * @return positive value: the size; On error a negative value will be returned with the following error codes:
 121  * ::EPERS_LOCKFS, ::EPERS_BADPOL, ::EPERS_NOKEY, ::EPERS_NOKEYDATA or ::EPERS_NOPRCTABLE
 122  */
 123 int pclKeyGetSize(unsigned int ldbid, const char* resource_id, unsigned int user_no, unsigned int seat_no);
 124
 125 /**
 126  * @brief close the access to a key-value identified by key handle
 127  *
 128  * @param key_handle key value handle return by key_handle_open()
 129  *
 130  * @return positive value: success; On error a negative value will be returned with the following error codes:
 131  * ::EPERS_LOCKFS
 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: the size; On error a negative value will be returned with the following error codes:
 143  * ::EPERS_LOCKFS
 144  */
 145 int pclKeyHandleGetSize(int key_handle);
 146
 147
 148
 149 /**
 150  * @brief open a key-value
 151  *
 152  * @param ldbid logical database ID
 153  * @param resource_id the resource ID
 154  * @param user_no  the user ID; user_no=0 can not be used as user-ID beacause ‘0’ is defined as System/node
 155  * @param seat_no  the seat number
 156  *
 157  * @return positive value: the key handle to access the value;
 158  * On error a negative value will be returned with the following error codes:
 159  * ::EPERS_LOCKFS
 160  */
 161 int pclKeyHandleOpen(unsigned int ldbid, const char* resource_id, unsigned int user_no, unsigned int seat_no);
 162
 163
 164
 165 /**
 166  * @brief reads persistent data identified by key handle
 167  *
 168  * @param key_handle key value handle return by key_handle_open()
 169  * @param buffer the buffer for persistent data
 170  * @param buffer_size size of buffer for reading
 171  *
 172  * @return positive value: the bytes read; On error a negative value will be returned with the following error codes:
 173  * ::EPERS_LOCKFS
 174  */
 175 int pclKeyHandleReadData(int key_handle, unsigned char* buffer, int buffer_size);
 176
 177
 178
 179 /**
 180  * @brief register a change notification for persistent data
 181  *
 182  * @param key_handle key value handle return by key_handle_open()
 183  * @param callback notification callback
 184  *
 185  * @return positive value: registration OK; On error a negative value will be returned with the following error codes:
 186  * ::EPERS_LOCKFS
 187  */
 188 int pclKeyHandleRegisterNotifyOnChange(int key_handle, pclChangeNotifyCallback_t callback);
 189
 190
 191
 192 /**
 193  * @brief writes persistent data identified by key handle
 194  *
 195  * @param key_handle key value handle return by key_handle_open()
 196  * @param buffer the buffer containing the persistent data to write
 197  * @param buffer_size the number of bytes to write (default max size is set to 16kB)
 198  *                    use environment variable PERS_MAX_KEY_VAL_DATA_SIZE to modify default size in bytes
 199  *
 200  * @return positive value: the bytes written; On error a negative value will be returned with the following error codes:
 201  * ::EPERS_LOCKFS
 202  */
 203 int pclKeyHandleWriteData(int key_handle, unsigned char* buffer, int buffer_size);
 204
 205
 206
 207 /**
 208  * @brief reads persistent data identified by ldbid and resource_id
 209  *
 210  * @param ldbid logical database ID
 211  * @param resource_id the resource ID
 212  * @param user_no  the user ID; user_no=0 can not be used as user-ID beacause ‘0’ is defined as System/node
 213  * @param seat_no  the seat number
 214  * @param buffer the buffer to read the persistent data
 215  * @param buffer_size size of buffer for reading
 216  *
 217  * @return positive value: the bytes read; On error a negative value will be returned with th follwoing error codes:
 218  * ::EPERS_LOCKFS
 219  */
 220 int pclKeyReadData(unsigned int ldbid, const char* resource_id, unsigned int user_no, unsigned int seat_no, unsigned char* buffer, int buffer_size);
 221
 222
 223
 224 /**
 225  * @brief register a change notification for persistent data
 226  *
 227  * @param ldbid logical database ID of the resource to monitor
 228  * @param resource_id the resource ID
 229  * @param user_no  the user ID; user_no=0 can not be used as user-ID beacause ‘0’ is defined as System/node
 230  * @param seat_no  the seat number
 231  * @param callback notification callback
 232  *
 233  * @return positive value: registration OK; On error a negative value will be returned with the following error codes:
 234  *                         ::EPERS_RES_NO_KEY ::EPERS_NOKEYDATA  ::EPERS_NOPRCTABLE
 235  */
 236 int pclKeyRegisterNotifyOnChange(unsigned int ldbid, const char* resource_id, unsigned int user_no, unsigned int seat_no, pclChangeNotifyCallback_t callback);
 237
 238
 239
 240 /**
 241  * @brief writes persistent data identified by ldbid and resource_id
 242  *
 243  * @param ldbid logical database ID
 244  * @param resource_id the resource ID
 245  * @param user_no  the user ID; user_no=0 can not be used as user-ID beacause ‘0’ is defined as System/node
 246  * @param seat_no  the seat number
 247  * @param buffer the buffer containing the persistent data to write
 248  * @param buffer_size the number of bytes to write (default max size is set to 16kB)
 249  *                    use environment variable PERS_MAX_KEY_VAL_DATA_SIZE to modify default size in bytes
 250  *
 251  * @return positive value: the bytes written; On error a negative value will be returned with the following error codes:
 252  * ::EPERS_LOCKFS
 253  */
 254 int pclKeyWriteData(unsigned int ldbid, const char* resource_id, unsigned int user_no, unsigned int seat_no, unsigned char* buffer, int buffer_size);
 255
 256 /** \} */
 257
 258 #ifdef __cplusplus
 259 }
 260 #endif
 261
 262 /** \} */ /* End of API */
 263 /** \} */ /* End of MODULE */
 264
 265 #endif /* PERSISTENCY_CLIENT_LIBRARY_KEY_H */