1 #ifndef PERSISTENCE_CLIENT_LIBRARY_KEY_H
2 #define PERSISTENCE_CLIENT_LIBRARY_KEY_H
4 /******************************************************************************
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:
17 The above copyright notice and this permission notice shall be included
18 in all copies or substantial portions of the Software.
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 ******************************************************************************/
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
36 /** \ingroup SSW_PERS */
37 /** \defgroup SSW_PERS_KEYVALUE Client: Key-value access
40 /** \defgroup SSW_PERS_KEYVALUE_INTERFACE API document
49 #define PERSIST_KEYVALUEAPI_INTERFACE_VERSION (0x01000000U)
54 * @brief delete persistent data
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)
61 * @return positive value: success; On error a negative value will be returned with th follwoing error codes:
64 int key_delete(unsigned char ldbid, char* resource_id, unsigned char user_no, unsigned char seat_no);
69 * @brief gets the size of persistent data in bytes
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)
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
79 int key_get_size(unsigned char ldbid, char* resource_id, unsigned char user_no, unsigned char seat_no);
82 * @brief close the access to a key-value identified by key handle
84 * @param key_handle key value handle return by key_handle_open()
86 * @return positive value: success; On error a negative value will be returned with th follwoing error codes:
89 int key_handle_close(int key_handle);
94 * @brief gets the size of persistent data in bytes identified by key handle
96 * @param key_handle key value handle return by key_handle_open()
98 * @return positive value: the size; On error a negative value will be returned with th follwoing error codes:
100 int key_handle_get_size(int key_handle);
105 * @brief open a key-value
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)
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:
115 int key_handle_open(unsigned char ldbid, char* resource_id, unsigned char user_no, unsigned char seat_no);
120 * @brief reads persistent data identified by key handle
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
126 * @return positive value: the bytes read; On error a negative value will be returned with th follwoing error codes:
129 int key_handle_read_data(int key_handle, unsigned char* buffer, unsigned long buffer_size);
134 * @brief register a change notification for persistent data
136 * @param key_handle key value handle return by key_handle_open()
138 * @return positive value: registration OK; On error a negative value will be returned with th follwoing error codes:
140 int key_handle_register_notify_on_change(int key_handle);
145 * @brief writes persistent data identified by key handle
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
152 * @return positive value: the bytes written; On error a negative value will be returned with th follwoing error codes:
154 int key_handle_write_data(int key_handle, unsigned char* buffer, unsigned long buffer_size);
159 * @brief reads persistent data identified by ldbid and resource_id
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
168 * @return positive value: the bytes read; On error a negative value will be returned with th follwoing error codes:
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);
175 * @brief register a change notification for persistent data
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)
182 * @return positive value: registration OK; On error a negative value will be returned with th follwoing error codes:
184 int key_register_notify_on_change(unsigned char ldbid, char* resource_id, unsigned char user_no, unsigned char seat_no);
189 * @brief writes persistent data identified by ldbid and resource_id
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
199 * @return positive value: the bytes written; On error a negative value will be returned with th follwoing error codes:
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);
208 /** \} */ /* End of API */
209 /** \} */ /* End of MODULE */
211 #endif /* PERSISTENCY_CLIENT_LIBRARY_KEY_H */