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
  37 #ifdef __cplusplus
  38 extern "C" {
  39 #endif
  40
  41
  42 #define         PERSIST_KEYVALUEAPI_INTERFACE_VERSION   (0x01000000U)
  43
  44
  45
  46 /**
  47  * @brief delete persistent data
  48  *
  49  * @param ldbid logical database ID
  50  * @param resource_id the resource ID
  51  * @param user_no  the user ID
  52  * @param seat_no  the seat number (seat 0 to 3)
  53  *
  54  * @return positive value: success; negative value: error code
  55  */
  56 int key_delete(unsigned char ldbid, char* resource_id, unsigned char user_no, unsigned char seat_no);
  57
  58
  59
  60 /**
  61  * @brief gets the size of persistent data in bytes
  62  *
  63  * @param ldbid logical database ID
  64  * @param resource_id the resource ID
  65  * @param user_no  the user ID
  66  * @param seat_no  the seat number (seat 0 to 3)
  67  *
  68  * @return positive value: the size; negative value: error code
  69  */
  70 int key_get_size(unsigned char ldbid, char* resource_id, unsigned char user_no, unsigned char seat_no);
  71
  72 /**
  73  * @brief close the access to a key-value identified by key handle
  74  *
  75  * @param key_handle key value handle return by key_handle_open()
  76  *
  77  * @return positive value: success; negative value: error code
  78  */
  79 int key_handle_close(int key_handle);
  80
  81
  82
  83 /**
  84  * @brief gets the size of persistent data in bytes identified by key handle
  85  *
  86  * @param key_handle key value handle return by key_handle_open()
  87  *
  88  * @return positive value: the size; negative value: error code
  89  */
  90 int key_handle_get_size(int key_handle);
  91
  92
  93
  94 /**
  95  * @brief open a key-value
  96  *
  97  * @param ldbid logical database ID
  98  * @param resource_id the resource ID
  99  * @param user_no  the user ID
 100  * @param seat_no  the seat number (seat 0 to 3)
 101  *
 102  * @return positive value: the key handle to access the value; negative value: Error code
 103  */
 104 int key_handle_open(unsigned char ldbid, char* resource_id, unsigned char user_no, unsigned char seat_no);
 105
 106
 107
 108 /**
 109  * @brief reads persistent data identified by key handle
 110  *
 111  * @param key_handle key value handle return by key_handle_open()
 112  * @param buffer the buffer for persistent data
 113  * @param buffer_size size of buffer for reading
 114  *
 115  * @return positive value: the bytes read; negative value: error code
 116  */
 117 int key_handle_read_data(int key_handle, unsigned char* buffer, unsigned long buffer_size);
 118
 119
 120
 121 /**
 122  * @brief register a change notification for persistent data
 123  *
 124  * @param key_handle key value handle return by key_handle_open()
 125  *
 126  * @return positive value: registration OK; negative value: error code
 127  */
 128 int key_handle_register_notify_on_change(int key_handle);
 129
 130
 131
 132 /**
 133  * @brief writes persistent data identified by key handle
 134  *
 135  * @param key_handle key value handle return by key_handle_open()
 136  * @param buffer the buffer containing the persistent data to write
 137  * @param buffer_size the number of bytes to write (default max size is set to 16kB)
 138  *                    use environment variable PERS_MAX_KEY_VAL_DATA_SIZE to modify default size in bytes
 139  *
 140  * @return positive value: the bytes written; negative value: error code
 141  */
 142 int key_handle_write_data(int key_handle, unsigned char* buffer, unsigned long buffer_size);
 143
 144
 145
 146 /**
 147  * @brief reads persistent data identified by ldbid and resource_id
 148  *
 149  * @param ldbid logical database ID
 150  * @param resource_id the resource ID
 151  * @param user_no  the user ID
 152  * @param seat_no  the seat number (seat 0 to 3)
 153  * @param buffer the buffer to read the persistent data
 154  * @param buffer_size size of buffer for reading
 155  *
 156  * @return positive value: the bytes read; negative value: error code
 157  */
 158 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);
 159
 160
 161
 162 /**
 163  * @brief register a change notification for persistent data
 164  *
 165  * @param ldbid logical database ID of the resource to monitor
 166  * @param resource_id the resource ID
 167  * @param user_no  the user ID
 168  * @param seat_no  the seat number (seat 0 to 3)
 169  *
 170  * @return positive value: registration OK; negative value: error code
 171  */
 172 int key_register_notify_on_change(unsigned char ldbid, char* resource_id, unsigned char user_no, unsigned char seat_no);
 173
 174
 175
 176 /**
 177  * @brief writes persistent data identified by ldbid and resource_id
 178  *
 179  * @param ldbid logical database ID
 180  * @param resource_id the resource ID
 181  * @param user_no  the user ID
 182  * @param seat_no  the seat number (seat 0 to 3)
 183  * @param buffer the buffer containing the persistent data to write
 184  * @param buffer_size the number of bytes to write (default max size is set to 16kB)
 185  *                    use environment variable PERS_MAX_KEY_VAL_DATA_SIZE to modify default size in bytes
 186  *
 187  * @return positive value: the bytes written; negative value: error code
 188  */
 189 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);
 190
 191
 192 #ifdef __cplusplus
 193 }
 194 #endif
 195
 196
 197 #endif /* PERSISTENCY_CLIENT_LIBRARY_KEY_H */
 198