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    Permission is hereby granted, free of charge, to any person obtaining
  11    a copy of this software and associated documentation files (the "Software"),
  12    to deal in the Software without restriction, including without limitation
  13    the rights to use, copy, modify, merge, publish, distribute, sublicense,
  14    and/or sell copies of the Software, and to permit persons to whom the
  15    Software is furnished to do so, subject to the following conditions:
  16
  17    The above copyright notice and this permission notice shall be included
  18    in all copies or substantial portions of the Software.
  19
  20    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  21    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  22    MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
  23    IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
  24    DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
  25    TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE
  26    OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  27 ******************************************************************************/
  28  /**
  29  * @file           persistence_client_library_key.h
  30  * @ingroup        Persistence client library
  31  * @author         Ingo Huerner (XSe) / Guy Sagnes (Continental)
  32  * @brief          Header of the persistence client library.
  33  *                 Library provides an API to access persistent data
  34  * @see
  35  */
  36 /** \ingroup SSW_PERS */
  37 /** \defgroup SSW_PERS_KEYVALUE Client: Key-value access
  38  *  \{
  39  */
  40 /** \defgroup SSW_PERS_KEYVALUE_INTERFACE API document
  41  *  \{
  42  */
  43
  44 #ifdef __cplusplus
  45 extern "C" {
  46 #endif
  47
  48
  49 #define         PERSIST_KEYVALUEAPI_INTERFACE_VERSION   (0x01000000U)
  50
  51
  52
  53 /**
  54  * @brief delete persistent data
  55  *
  56  * @param ldbid logical database ID
  57  * @param resource_id the resource ID
  58  * @param user_no  the user ID
  59  * @param seat_no  the seat number (seat 0 to 3)
  60  *
  61  * @return positive value: success; On error a negative value will be returned with th follwoing error codes:
  62  * EPERS_LOCKFS
  63  */
  64 int key_delete(unsigned char ldbid, char* resource_id, unsigned char user_no, unsigned char seat_no);
  65
  66
  67
  68 /**
  69  * @brief gets the size of persistent data in bytes
  70  *
  71  * @param ldbid logical database ID
  72  * @param resource_id the resource ID
  73  * @param user_no  the user ID
  74  * @param seat_no  the seat number (seat 0 to 3)
  75  *
  76  * @return positive value: the size; On error a negative value will be returned with th follwoing error codes:
  77  * EPERS_LOCKFS, EPERS_BADPOL, EPERS_NOKEY, EPERS_NOKEYDATA or EPERS_NOPRCTABLE
  78  */
  79 int key_get_size(unsigned char ldbid, char* resource_id, unsigned char user_no, unsigned char seat_no);
  80
  81 /**
  82  * @brief close the access to a key-value identified by key handle
  83  *
  84  * @param key_handle key value handle return by key_handle_open()
  85  *
  86  * @return positive value: success; On error a negative value will be returned with th follwoing error codes:
  87  * EPERS_LOCKFS
  88  */
  89 int key_handle_close(int key_handle);
  90
  91
  92
  93 /**
  94  * @brief gets the size of persistent data in bytes identified by key handle
  95  *
  96  * @param key_handle key value handle return by key_handle_open()
  97  *
  98  * @return positive value: the size; On error a negative value will be returned with th follwoing error codes:
  99  */
 100 int key_handle_get_size(int key_handle);
 101
 102
 103
 104 /**
 105  * @brief open a key-value
 106  *
 107  * @param ldbid logical database ID
 108  * @param resource_id the resource ID
 109  * @param user_no  the user ID
 110  * @param seat_no  the seat number (seat 0 to 3)
 111  *
 112  * @return positive value: the key handle to access the value;
 113  * On error a negative value will be returned with th follwoing error codes:
 114  */
 115 int key_handle_open(unsigned char ldbid, char* resource_id, unsigned char user_no, unsigned char seat_no);
 116
 117
 118
 119 /**
 120  * @brief reads persistent data identified by key handle
 121  *
 122  * @param key_handle key value handle return by key_handle_open()
 123  * @param buffer the buffer for persistent data
 124  * @param buffer_size size of buffer for reading
 125  *
 126  * @return positive value: the bytes read; On error a negative value will be returned with th follwoing error codes:
 127  *
 128  */
 129 int key_handle_read_data(int key_handle, unsigned char* buffer, unsigned long buffer_size);
 130
 131
 132
 133 /**
 134  * @brief register a change notification for persistent data
 135  *
 136  * @param key_handle key value handle return by key_handle_open()
 137  *
 138  * @return positive value: registration OK; On error a negative value will be returned with th follwoing error codes:
 139  */
 140 int key_handle_register_notify_on_change(int key_handle);
 141
 142
 143
 144 /**
 145  * @brief writes persistent data identified by key handle
 146  *
 147  * @param key_handle key value handle return by key_handle_open()
 148  * @param buffer the buffer containing the persistent data to write
 149  * @param buffer_size the number of bytes to write (default max size is set to 16kB)
 150  *                    use environment variable PERS_MAX_KEY_VAL_DATA_SIZE to modify default size in bytes
 151  *
 152  * @return positive value: the bytes written; On error a negative value will be returned with th follwoing error codes:
 153  */
 154 int key_handle_write_data(int key_handle, unsigned char* buffer, unsigned long buffer_size);
 155
 156
 157
 158 /**
 159  * @brief reads persistent data identified by ldbid and resource_id
 160  *
 161  * @param ldbid logical database ID
 162  * @param resource_id the resource ID
 163  * @param user_no  the user ID
 164  * @param seat_no  the seat number (seat 0 to 3)
 165  * @param buffer the buffer to read the persistent data
 166  * @param buffer_size size of buffer for reading
 167  *
 168  * @return positive value: the bytes read; On error a negative value will be returned with th follwoing error codes:
 169  */
 170 int key_read_data(unsigned char ldbid, char* resource_id, unsigned char user_no, unsigned char seat_no, unsigned char* buffer, unsigned long buffer_size);
 171
 172
 173
 174 /**
 175  * @brief register a change notification for persistent data
 176  *
 177  * @param ldbid logical database ID of the resource to monitor
 178  * @param resource_id the resource ID
 179  * @param user_no  the user ID
 180  * @param seat_no  the seat number (seat 0 to 3)
 181  *
 182  * @return positive value: registration OK; On error a negative value will be returned with th follwoing error codes:
 183  */
 184 int key_register_notify_on_change(unsigned char ldbid, char* resource_id, unsigned char user_no, unsigned char seat_no);
 185
 186
 187
 188 /**
 189  * @brief writes persistent data identified by ldbid and resource_id
 190  *
 191  * @param ldbid logical database ID
 192  * @param resource_id the resource ID
 193  * @param user_no  the user ID
 194  * @param seat_no  the seat number (seat 0 to 3)
 195  * @param buffer the buffer containing the persistent data to write
 196  * @param buffer_size the number of bytes to write (default max size is set to 16kB)
 197  *                    use environment variable PERS_MAX_KEY_VAL_DATA_SIZE to modify default size in bytes
 198  *
 199  * @return positive value: the bytes written; On error a negative value will be returned with th follwoing error codes:
 200  */
 201 int key_write_data(unsigned char ldbid, char* resource_id, unsigned char user_no, unsigned char seat_no, unsigned char* buffer, unsigned long buffer_size);
 202
 203
 204 #ifdef __cplusplus
 205 }
 206 #endif
 207
 208 /** \} */ /* End of API */
 209 /** \} */ /* End of MODULE */
 210
 211 #endif /* PERSISTENCY_CLIENT_LIBRARY_KEY_H */
 212