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
42 #define PERSIST_KEYVALUEAPI_INTERFACE_VERSION (0x01000000U)
47 * @brief delete persistent data
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)
54 * @return positive value: success; negative value: error code
56 int key_delete(unsigned char ldbid, char* resource_id, unsigned char user_no, unsigned char seat_no);
61 * @brief gets the size of persistent data in bytes
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)
68 * @return positive value: the size; negative value: error code
70 int key_get_size(unsigned char ldbid, char* resource_id, unsigned char user_no, unsigned char seat_no);
73 * @brief close the access to a key-value identified by key handle
75 * @param key_handle key value handle return by key_handle_open()
77 * @return positive value: success; negative value: error code
79 int key_handle_close(int key_handle);
84 * @brief gets the size of persistent data in bytes identified by key handle
86 * @param key_handle key value handle return by key_handle_open()
88 * @return positive value: the size; negative value: error code
90 int key_handle_get_size(int key_handle);
95 * @brief open a key-value
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)
102 * @return positive value: the key handle to access the value; negative value: Error code
104 int key_handle_open(unsigned char ldbid, char* resource_id, unsigned char user_no, unsigned char seat_no);
109 * @brief reads persistent data identified by key handle
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
115 * @return positive value: the bytes read; negative value: error code
117 int key_handle_read_data(int key_handle, unsigned char* buffer, unsigned long buffer_size);
122 * @brief register a change notification for persistent data
124 * @param key_handle key value handle return by key_handle_open()
126 * @return positive value: registration OK; negative value: error code
128 int key_handle_register_notify_on_change(int key_handle);
133 * @brief writes persistent data identified by key handle
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
140 * @return positive value: the bytes written; negative value: error code
142 int key_handle_write_data(int key_handle, unsigned char* buffer, unsigned long buffer_size);
147 * @brief reads persistent data identified by ldbid and resource_id
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
156 * @return positive value: the bytes read; negative value: error code
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);
163 * @brief register a change notification for persistent data
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)
170 * @return positive value: registration OK; negative value: error code
172 int key_register_notify_on_change(unsigned char ldbid, char* resource_id, unsigned char user_no, unsigned char seat_no);
177 * @brief writes persistent data identified by ldbid and resource_id
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
187 * @return positive value: the bytes written; negative value: error code
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);
197 #endif /* PERSISTENCY_CLIENT_LIBRARY_KEY_H */