src/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_db_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   (0x05000000U)
  28
  29
  30 #include "persistence_client_library_data_organization.h"
  31
  32 //#include "persistence_client_library_rc_table.h"
  33 #include <persComRct.h>
  34
  35 #include "../include/persistence_client_library_key.h"
  36
  37
  38
  39 /**
  40  * @brief get the raw key without prefixed '/node/', '/user/3/' etc
  41  *
  42  * @param key the ptr. to the key which should be stripped
  43  *
  44  * @return the pointer to the stripped 'raw key'
  45  */
  46 char* pers_get_raw_key(char *key);
  47
  48
  49
  50 /**
  51  * @brief open the default value database specified by the 'DefaultType'
  52  *
  53  * @param dbPath path to the directory were the databases are included in.
  54  * @param DefaultType the default type
  55  *
  56  * @return >= 0 for valid handler; if an error occured the following error code:
  57  *   EPERS_COMMON
  58  */
  59 int pers_db_open_default(const char* dbPath, PersDefaultType_e DefaultType);
  60
  61
  62
  63 /**
  64  * @brief tries to get default values for a key from the configurable and factory default databases.
  65  *
  66  * @param dbPath the path to the directory where the default databases are in
  67  * @param key the database key
  68  * @param info the persistence context information
  69  * @param buffer the buffer holding the data
  70  * @param buffer_size the size of the buffer
  71  * @param job the info to specify what to do. Get Data or the DataSize.
  72  *
  73  * @return the number of bytes read or the size of the key (depends on parameter 'job').
  74            negative value if an error occured and the following error code:
  75  *         EPERS_NOKEY
  76  */
  77 int pers_get_defaults(char* dbPath, char* key, PersistenceInfo_s* info, unsigned char* buffer, unsigned int buffer_size, PersGetDefault_e job);
  78
  79
  80
  81 /**
  82  * @brief write data to a key
  83  *
  84  * @param dbPath the path to the database where the key is in
  85  * @param key the database key
  86  * @param info persistence information
  87  * @param buffer the buffer holding the data
  88  * @param buffer_size the size of the buffer
  89  *
  90  * @return the number of bytes written or a negative value if an error occured with the following error codes:
  91  *   EPERS_SETDTAFAILED  EPERS_NOPRCTABLE  EPERS_NOKEYDATA  EPERS_NOKEY
  92  */
  93 int persistence_set_data(char* dbPath, char* key, PersistenceInfo_s* info, unsigned char* buffer, unsigned int buffer_size);
  94
  95
  96
  97 /**
  98  * @brief get data of a key
  99  *
 100  * @param dbPath the path to the database where the key is in
 101  * @param key the database key
 102  * @param resourceID the resource id
 103  * @param info persistence information
 104  * @param buffer the buffer holding the data
 105  * @param buffer_size the size of the buffer
 106  *
 107  * @return the number of bytes read or a negative value if an error occured with the following error codes:
 108  *  EPERS_NOPRCTABLE  EPERS_NOKEYDATA  EPERS_NOKEY
 109  */
 110 int persistence_get_data(char* dbPath, char* key, const char* resourceID, PersistenceInfo_s* info, unsigned char* buffer, unsigned int buffer_size);
 111
 112
 113
 114 /**
 115  * @brief get the size of the data from a given key
 116  *
 117  * @param dbPath the path to the database where the key is in
 118  * @param key the database key
 119  * @param resourceID the resource id
 120  * @param info persistence information
 121  *
 122  * @return size of data in bytes read from the key or on error a negative value with the following error codes:
 123  *  EPERS_NOPRCTABLE or EPERS_NOKEY
 124  */
 125 int persistence_get_data_size(char* dbPath, char* key, const char* resourceID, PersistenceInfo_s* info);
 126
 127
 128
 129 /**
 130  * @brief delete data
 131  *
 132  * @param dbPath the path to the database where the key is in
 133  * @param key the database key to register on
 134  * @param info persistence information
 135  *
 136  * @return 0 if deletion was successfull;
 137  *         or an error code: EPERS_DB_KEY_SIZE, EPERS_NOPRCTABLE, EPERS_DB_ERROR_INTERNAL or EPERS_NOPLUGINFUNCT
 138  */
 139 int persistence_delete_data(char* dbPath, char* key, PersistenceInfo_s* info);
 140
 141
 142
 143 /**
 144  * @brief close the database for the given storage type
 145  *
 146  * @param info persistence information
 147  */
 148 //void database_close(PersistenceInfo_s* info);
 149
 150
 151
 152 /**
 153  * @brief close all databases
 154  */
 155 void database_close_all();
 156
 157
 158
 159 /**
 160  * @brief register or unregister for change notifications of a key
 161  *
 162  * @param key the database key to register on
 163  * @param ldbid logical database ID of the resource to monitor
 164  * @param user_no  the user ID; user_no=0 can not be used as user-ID beacause '0' is defined as System/node
 165  * @param seat_no  the seat number
 166  * @param callback the function callback to be called
 167  * @param regPolicy ::Notify_register to register; ::Notify_unregister to unregister
 168  *
 169  * @return 0 of registration was successful; -1 if registration fails
 170  */
 171 int persistence_notify_on_change(const char* key, unsigned int ldbid, unsigned int user_no, unsigned int seat_no,
 172                                      pclChangeNotifyCallback_t callback, PersNotifyRegPolicy_e regPolicy);
 173
 174
 175
 176 /**
 177  * @brief send a notification signal
 178  *
 179  * @param key the database key to register on
 180  * @param context the database context
 181  * @param reason the reason of the signal, values see pclNotifyStatus_e.
 182  *
 183  * @return 0 of registration was successful; -1 if registration failes
 184  */
 185 int pers_send_Notification_Signal(const char* key, PersistenceDbContext_s* context, pclNotifyStatus_e reason);
 186
 187
 188 /**
 189  * @brief close all open persistence resource configuration tables
 190  */
 191 void pers_rct_close_all();
 192
 193 #ifdef __cplusplus
 194 }
 195 #endif
 196
 197 #endif /* PERSISTENCY_CLIENT_LIBRARY_DB_ACCESS_H */