1 #ifndef PERSISTENCE_CLIENT_LIBRARY_DB_ACCESS_H
2 #define PERSISTENCE_CLIENT_LIBRARY_DB_ACCESS_H
4 /******************************************************************************
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 ******************************************************************************/
15 * @file persistence_client_library_data_access.h
16 * @ingroup Persistence client library
17 * @author Ingo Huerner
18 * @brief Header of the persistence client library database access.
19 * Library provides an API to access persistent data
27 #define PERSIST_DATA_ACCESS_INTERFACE_VERSION (0x04020000U)
30 #include "persistence_client_library_data_organization.h"
31 #include "persistence_client_library_rc_table.h"
32 #include "../include/persistence_client_library_key.h"
37 * @brief write data to a key
39 * @param dbPath the path to the database where the key is in
40 * @param key the database key
41 * @param info persistence information
42 * @param buffer the buffer holding the data
43 * @param buffer_size the size of the buffer
45 * @return the number of bytes written or a negative value if an error occured with the following error codes:
46 * EPERS_SETDTAFAILED EPERS_NOPRCTABLE EPERS_NOKEYDATA EPERS_NOKEY
48 int pers_db_write_key(char* dbPath, char* key, PersistenceInfo_s* info, unsigned char* buffer, unsigned int buffer_size);
53 * @brief get data of a key
55 * @param dbPath the path to the database where the key is in
56 * @param key the database key
57 * @param info persistence information
58 * @param buffer the buffer holding the data
59 * @param buffer_size the size of the buffer
61 * @return the number of bytes read or a negative value if an error occured with the following error codes:
62 * EPERS_NOPRCTABLE EPERS_NOKEYDATA EPERS_NOKEY
64 int pers_db_read_key(char* dbPath, char* key, PersistenceInfo_s* info, unsigned char* buffer, unsigned int buffer_size);
69 * @brief get the size of the data from a given key
71 * @param dbPath the path to the database where the key is in
72 * @param key the database key
73 * @param info persistence information
75 * @return size of data in bytes read from the key or on error a negative value with the following error codes:
76 * EPERS_NOPRCTABLE or EPERS_NOKEY
78 int pers_db_get_key_size(char* dbPath, char* key, PersistenceInfo_s* info);
85 * @param dbPath the path to the database where the key is in
86 * @param key the database key to register on
87 * @param info persistence information
89 * @return 0 if deletion was successfull;
90 * or an error code: EPERS_DB_KEY_SIZE, EPERS_NOPRCTABLE, EPERS_DB_ERROR_INTERNAL or EPERS_NOPLUGINFUNCT
92 int pers_db_delete_key(char* dbPath, char* key, PersistenceInfo_s* info);
97 * @brief close the database for the given storage type
99 * @param info persistence information
101 void pers_db_close(PersistenceInfo_s* info);
106 * @brief close all databases
108 void pers_db_close_all();
113 * @brief register for change notifications of a key
115 * @param dbPath the path to the database where the key is in
116 * @param key the database key to register on
118 * @return 0 of registration was successfull; -1 if registration failes
120 int persistence_reg_notify_on_change(char* dbPath, char* key, unsigned int ldbid, unsigned int user_no, unsigned int seat_no,
121 pclChangeNotifyCallback_t callback);
126 * @brief send a notification signal
128 * @param key the database key to register on
129 * @param context the database context
130 * @param reason the reason of the signal, values see pclNotifyStatus_e.
132 * @return 0 of registration was successfull; -1 if registration failes
134 int pers_send_Notification_Signal(const char* key, PersistenceDbContext_s* context, pclNotifyStatus_e reason);
136 //---------------------------------------------------------------------------------------------
137 // C U R S O R F U N C T I O N S
138 //---------------------------------------------------------------------------------------------
141 * @brief create a cursor to a DB ; if success, the cursor points to (-1)
142 * to access the first entry in DB, call persistence_db_cursor_next
144 * @param dbPath[in] absolute path to the database
146 * @return handler to the DB (to be used in successive calls) or error code (< 0)
148 int pers_db_cursor_create(char* dbPath);
151 * @brief move cursor to the next position
153 * @param handlerDB[in] handler to DB (obtained with persistence_db_cursor_create())
155 * @return 0 for success, negative value in case of error (check against EPERS_LAST_ENTRY_IN_DB)
157 int pers_db_cursor_next(unsigned int handlerDB);
160 * @brief get the name of the key pointed by the cursor associated with the database
162 * @param handlerDB[in] handler to DB (obtained with persistence_db_cursor_create())
163 * @param bufKeyName_out[out] buffer where to pass the name of the key
164 * @param bufSize[out] size of bufKeyName_out
166 * @return read size (if >= 0), error other way
168 int pers_db_cursor_get_key(unsigned int handlerDB, char * bufKeyName_out, int bufSize) ;
171 * @brief get the data of the key pointed by the cursor associated with the database
173 * @param handlerDB[in] handler to DB (obtained with persistence_db_cursor_create())
174 * @param bufKeyData_out[out] buffer where to pass the data of the key
175 * @param bufSize[out] size of bufKeyData_out
177 * @return read size (if >= 0), error other way
179 int pers_db_cursor_get_data(unsigned int handlerDB, char * bufData_out, int bufSize) ;
182 * @brief get the data size of the key pointed by the cursor associated with the database
184 * @param handlerDB[in] handler to DB (obtained with persistence_db_cursor_create())
186 * @return positive value for data size, negative value for error
188 int pers_db_cursor_get_data_size(unsigned int handlerDB) ;
192 * @brief remove the cursor
194 * @param handlerDB[in] handler to DB (obtained with persistence_db_cursor_create())
196 * @return 0 for success, negative value in case of error
198 int pers_db_cursor_destroy(unsigned int handlerDB) ;
205 #endif /* PERSISTENCY_CLIENT_LIBRARY_DB_ACCESS_H */