include_protected/persistence_client_library_db_access.h

   1 #ifndef PERSISTENCE_CLIENT_LIBRARY_DB_ACCESS_H
   2 #define PERSISTENCE_CLIENT_LIBRARY_DB_ACCESS_H
   3
   4 /******************************************************************************
   5  * Project         Persistency
   6  * (c) copyright   2012
   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 ******************************************************************************/
  14  /**
  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
  20  * @see
  21  */
  22
  23 #ifdef __cplusplus
  24 extern "C" {
  25 #endif
  26
  27 #define  PERSIST_DATA_ACCESS_INTERFACE_VERSION   (0x04020000U)
  28
  29
  30 #include "persistence_client_library_data_organization.h"
  31 #include "persistence_client_library_rc_table.h"
  32 #include "../include/persistence_client_library_key.h"
  33
  34
  35
  36 /**
  37  * @brief write data to a key
  38  *
  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
  44  *
  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
  47  */
  48 int pers_db_write_key(char* dbPath, char* key, PersistenceInfo_s* info, unsigned char* buffer, unsigned int buffer_size);
  49
  50
  51
  52 /**
  53  * @brief get data of a key
  54  *
  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
  60  *
  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
  63  */
  64 int pers_db_read_key(char* dbPath, char* key, PersistenceInfo_s* info, unsigned char* buffer, unsigned int buffer_size);
  65
  66
  67
  68 /**
  69  * @brief get the size of the data from a given key
  70  *
  71  * @param dbPath the path to the database where the key is in
  72  * @param key the database key
  73  * @param info persistence information
  74  *
  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
  77  */
  78 int pers_db_get_key_size(char* dbPath, char* key, PersistenceInfo_s* info);
  79
  80
  81
  82 /**
  83  * @brief delete data
  84  *
  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
  88  *
  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
  91  */
  92 int pers_db_delete_key(char* dbPath, char* key, PersistenceInfo_s* info);
  93
  94
  95
  96 /**
  97  * @brief close the database for the given storage type
  98  *
  99  * @param info persistence information
 100  */
 101 void pers_db_close(PersistenceInfo_s* info);
 102
 103
 104
 105 /**
 106  * @brief close all databases
 107  */
 108 void pers_db_close_all();
 109
 110
 111
 112 /**
 113  * @brief register for change notifications of a key
 114  *
 115  * @param dbPath the path to the database where the key is in
 116  * @param key the database key to register on
 117  *
 118  * @return 0 of registration was successfull; -1 if registration failes
 119  */
 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);
 122
 123
 124
 125 /**
 126  * @brief send a notification signal
 127  *
 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.
 131  *
 132  * @return 0 of registration was successfull; -1 if registration failes
 133  */
 134 int pers_send_Notification_Signal(const char* key, PersistenceDbContext_s* context, pclNotifyStatus_e reason);
 135
 136 //---------------------------------------------------------------------------------------------
 137 // C U R S O R    F U N C T I O N S
 138 //---------------------------------------------------------------------------------------------
 139
 140 /**
 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
 143  *
 144  * @param dbPath[in] absolute path to the database
 145  *
 146  * @return handler to the DB (to be used in successive calls) or error code (< 0)
 147  */
 148 int pers_db_cursor_create(char* dbPath);
 149
 150 /**
 151  * @brief move cursor to the next position
 152  *
 153  * @param handlerDB[in] handler to DB (obtained with persistence_db_cursor_create())
 154  *
 155  * @return 0 for success, negative value in case of error (check against EPERS_LAST_ENTRY_IN_DB)
 156  */
 157 int pers_db_cursor_next(unsigned int handlerDB);
 158
 159 /**
 160  * @brief get the name of the key pointed by the cursor associated with the database
 161  *
 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
 165  *
 166  * @return read size (if >= 0), error other way
 167  */
 168 int pers_db_cursor_get_key(unsigned int handlerDB, char * bufKeyName_out, int bufSize) ;
 169
 170 /**
 171  * @brief get the data of the key pointed by the cursor associated with the database
 172  *
 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
 176  *
 177  * @return read size (if >= 0), error other way
 178  */
 179 int pers_db_cursor_get_data(unsigned int handlerDB, char * bufData_out, int bufSize) ;
 180
 181 /**
 182  * @brief get the data size of the key pointed by the cursor associated with the database
 183  *
 184  * @param handlerDB[in] handler to DB (obtained with persistence_db_cursor_create())
 185  *
 186  * @return positive value for data size, negative value for error
 187  */
 188 int pers_db_cursor_get_data_size(unsigned int handlerDB) ;
 189
 190
 191 /**
 192  * @brief remove the cursor
 193  *
 194  * @param handlerDB[in] handler to DB (obtained with persistence_db_cursor_create())
 195  *
 196  * @return 0 for success, negative value in case of error
 197  */
 198 int pers_db_cursor_destroy(unsigned int handlerDB) ;
 199
 200
 201 #ifdef __cplusplus
 202 }
 203 #endif
 204
 205 #endif /* PERSISTENCY_CLIENT_LIBRARY_DB_ACCESS_H */