New release 0.3.2, see ChangeLog for changes

3 files changed, 428 insertions, 0 deletions

diff --git a/include_protected/crc32.h b/include_protected/crc32.h
new file mode 100644
index 0000000..781e7eb
--- /dev/null
+++ b/include_protected/crc32.h
@@ -0,0 +1,40 @@
+#ifndef CRC32_H
+#define CRC32_H
+
+/******************************************************************************
+ * Project         Persistency
+ * (c) copyright   2012
+ * Company         XS Embedded GmbH
+ *****************************************************************************/
+/******************************************************************************
+ * Copyright
+ *
+ * This Source Code Form is subject to the terms of the
+ * Mozilla Public License, v. 2.0. If a  copy of the MPL was not distributed
+ * with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
+******************************************************************************/
+ /**
+ * @file           crc32.h
+ * @ingroup        Persistence client library
+ * @author         Ingo Huerner
+ * @brief          Header of crc32 checksum generation
+ * @see            
+ */
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+
+#define  PERSIST_CLIENT_LIBRARY_INTERFACE_VERSION   (0x01000000U)
+
+#include <string.h>
+
+const unsigned int crc32(unsigned int crc, const unsigned char *buf, size_t theSize);
+
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* CRC32_H */
diff --git a/include_protected/persistence_client_library.h b/include_protected/persistence_client_library.h
new file mode 100644
index 0000000..d34060e
--- /dev/null
+++ b/include_protected/persistence_client_library.h
@@ -0,0 +1,198 @@
+#ifndef PERSISTENCE_CLIENT_LIBRARY_H
+#define PERSISTENCE_CLIENT_LIBRARY_H
+
+/******************************************************************************
+ * Project         Persistency
+ * (c) copyright   2012
+ * Company         XS Embedded GmbH
+ *****************************************************************************/
+/******************************************************************************
+ * This Source Code Form is subject to the terms of the
+ * Mozilla Public License, v. 2.0. If a  copy of the MPL was not distributed
+ * with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
+******************************************************************************/
+ /**
+ * @file           persistence_client_library.h
+ * @ingroup        Persistence client library
+ * @author         Ingo Huerner
+ * @brief          Header of the persistence client library.
+ *                 Library provides an API to access persistent data
+ * @see            
+ */
+
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#define  PERSIST_CLIENT_LIBRARY_INTERFACE_VERSION   (0x01000000U)
+
+#include "../include/persistence_client_library_error_def.h"
+#include "crc32.h"
+
+#include <string.h>
+#include <stdio.h>
+
+
+/// constant definitions
+enum _PersistenceConstantDef
+{
+   ResIsNoFile          = 0,        /// flag to identify that resource a not file
+   ResIsFile            = 1,        /// flag to identify that resource a file
+   AccessNoLock         = 1,        /// flag to indicate that access is not locked
+
+   FileClosed           = 0,
+   FileOpen             = 1,
+
+   NsmShutdownNormal       = 1,     /// lifecycle shutdown normal
+   NsmErrorStatus_OK       = 1,
+   NsmErrorStatus_Fail     = -1,
+
+   PrctKeySize             = 64,    /// persistence resource config table max key size
+   PrctValueSize           = 256,   /// persistence resource config table max value size
+   PrctDbTableSize         = 1024,  /// number of persistence resource config tables to store
+
+   DbKeySize               = 64,    /// database max key size
+   DbValueSize             = 16384, /// database max value size
+   DbTableSize             = 1024,  /// database table size
+
+   PasMsg_Block            = 1,     /// persistence administration service block access
+   PasMsg_WriteBack        = 2,     /// persistence administration service write_back
+   PasMsg_Unblock          = 4,     /// persistence administration service unblock access
+   PasErrorStatus_RespPend = 88,    /// persistence administration service msg return status
+   PasErrorStatus_OK       = 100,   /// persistence administration service msg return status
+   PasErrorStatus_FAIL     = -1,    /// persistence administration service msg return status
+
+   CustLibMaxLen = 128,             /// max length of the custom library name and path
+   DbKeyMaxLen   = 128,             /// max database key length
+   DbPathMaxLen  = 128,             /// max database path length
+   MaxAppNameLen = 128,             /// max application name
+   MaxPersHandle = 256,             /// max number of parallel open persistence handles
+
+   defaultMaxKeyValDataSize = 16384 /// default limit the key-value data size to 16kB
+};
+
+
+/// enumerator used to identify the policy to manage the data
+typedef enum _PersistencePolicy_e
+{
+   PersistencePolicy_wc    = 0,  /**< the data is managed write cached */
+   PersistencePolicy_wt    = 1,  /**< the data is managed write through */
+   PersistencePolicy_na    = 2,  /**< the data is not applicable */
+
+   /** insert new entries here ... */
+   PersistencePolicy_LastEntry         /**< last entry */
+
+} PersistencePolicy_e;
+
+
+/// enumerator used to identify the persistence storage to manage the data
+typedef enum _PersistenceStorage_e
+{
+   PersistenceStorage_local    = 0,  /**< the data is managed local */
+   PersistenceStorage_shared   = 1,  /**< the data is managed shared */
+   PersistenceStorage_custom   = 2,  /**< the data is managed over custom client implementation */
+
+   /** insert new entries here ... */
+   PersistenceStoragePolicy_LastEntry         /**< last entry */
+
+} PersistenceStorage_e;
+
+
+/// structure used to manage database context
+typedef struct _PersistenceDbContext_s
+{
+   unsigned char ldbid;
+   unsigned char user_no;
+   unsigned char seat_no;
+} PersistenceDbContext_s;
+
+/// structure used to manage the persistence configuration for a key
+typedef struct _PersistenceConfigurationKey_s
+{
+   PersistencePolicy_e     policy;           /**< policy  */
+   PersistenceStorage_e    storage;          /**< definition of storage to use */
+   unsigned int            permission;       /**< access right, corresponds to UNIX */
+   unsigned int            max_size;         /**< max size expected for the key */
+   char *                  reponsible;       /**< name of responsible application */
+   char *                  custom_name;      /**< name of the customer plugin */
+} PersistenceConfigurationKey_s;
+
+
+/// persistence information
+typedef struct _PersistenceInfo_s
+{
+   PersistenceDbContext_s           context;          /**< database context*/
+   PersistenceConfigurationKey_s    configKey;        /**< prct configuration key*/
+
+} PersistenceInfo_s;
+
+
+/// persistence resource config table type definition
+typedef enum _PersistenceRCT_e
+{
+   PersistenceRCT_local         = 0,
+   PersistenceRCT_shared_public = 1,
+   PersistenceRCT_shared_group  = 2,
+
+   PersistenceRCT_LastEntry                // last Entry
+
+} PersistenceRCT_e;
+
+
+/// resource configuration table name
+extern const char* gResTableCfg;
+
+/// shared cached default database
+extern const char* gSharedCachedDefault;
+/// shared cached database
+extern const char* gSharedCached;
+/// shared write through default database
+extern const char* gSharedWtDefault;
+/// shared write through database
+extern const char* gSharedWt;
+
+/// local cached default database
+extern const char* gLocalCachedDefault;
+/// local cached default database
+extern const char* gLocalCached;
+/// local write through default database
+extern const char* gLocalWtDefault;
+/// local write through default database
+extern const char* gLocalWt;
+
+
+/// directory structure node name defintion
+extern const char* gNode;
+/// directory structure user name defintion
+extern const char* gUser;
+/// directory structure seat name defintion
+extern const char* gSeat;
+
+
+/// path prefic for local cached database: /Data/mnt_c/<appId>/<database_name>
+extern const char* gLocalCachePath;
+/// path prefic for local write through database /Data/mnt_wt/<appId>/<database_name>
+extern const char* gLocalWtPath;
+/// path prefic for shared cached database: /Data/mnt_c/Shared/Group/<group_no>/<database_name>
+extern const char* gSharedCachePath;
+/// path prefic for shared write through database: /Data/mnt_wt/Shared/Group/<group_no>/<database_name>
+extern const char* gSharedWtPath;
+/// path prefic for shared public cached database: /Data/mnt_c/Shared/Public//<database_name>
+extern const char* gSharedPublicCachePath;
+/// path prefic for shared public write through database: /Data/mnt_wt/Shared/Public/<database_name>
+extern const char* gSharedPublicWtPath;
+
+
+/// application id
+extern char gAppId[MaxAppNameLen];
+
+/// max key value data size
+extern int gMaxKeyValDataSize;
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* PERSISTENCY_CLIENT_LIBRARY_H */
+
diff --git a/include_protected/persistence_client_library_data_access.h b/include_protected/persistence_client_library_data_access.h
new file mode 100644
index 0000000..d0ec7df
--- /dev/null
+++ b/include_protected/persistence_client_library_data_access.h
@@ -0,0 +1,190 @@
+#ifndef PERSISTENCE_CLIENT_LIBRARY_DATA_ACCESS_H
+#define PERSISTENCE_CLIENT_LIBRARY_DATA_ACCESS_H
+
+/******************************************************************************
+ * Project         Persistency
+ * (c) copyright   2012
+ * Company         XS Embedded GmbH
+ *****************************************************************************/
+/******************************************************************************
+ * This Source Code Form is subject to the terms of the
+ * Mozilla Public License, v. 2.0. If a  copy of the MPL was not distributed
+ * with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
+******************************************************************************/
+ /**
+ * @file           persistence_client_library_data_access.h
+ * @ingroup        Persistence client library
+ * @author         Ingo Huerner
+ * @brief          Header of the persistence client library data access.
+ *                 Library provides an API to access persistent data
+ * @see            
+ */
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#define  PERSIST_DATA_ACCESS_INTERFACE_VERSION   (0x02100000U)
+
+
+#include "persistence_client_library.h"
+
+
+
+/**
+ * @brief write data to a key
+ *
+ * @param dbPath the path to the database where the key is in 
+ * @param key the database key
+ * @param info persistence information
+ * @param buffer the buffer holding the data
+ * @param buffer_size the size of the buffer
+ *
+ * @return the number of bytes written or a negative value if an error occured with the following error codes:
+ *   EPERS_SETDTAFAILED  EPERS_NOPRCTABLE  EPERS_NOKEYDATA  EPERS_NOKEY
+ */
+int persistence_set_data(char* dbPath, char* key, PersistenceInfo_s* info, unsigned char* buffer, unsigned int buffer_size);
+
+
+
+/**
+ * @brief get data of a key
+ *
+ * @param dbPath the path to the database where the key is in
+ * @param key the database key
+ * @param info persistence information
+ * @param buffer the buffer holding the data
+ * @param buffer_size the size of the buffer
+ *
+ * @return the number of bytes read or a negative value if an error occured with the following error codes:
+ *  EPERS_NOPRCTABLE  EPERS_NOKEYDATA  EPERS_NOKEY
+ */
+int persistence_get_data(char* dbPath, char* key, PersistenceInfo_s* info, unsigned char* buffer, unsigned int buffer_size);
+
+
+
+/**
+ * @brief get the size of the data from a given key
+ *
+ * @param dbPath the path to the database where the key is in
+ * @param key the database key
+ * @param info persistence information
+ *
+ * @return size of data in bytes read from the key or on error a negative value with the following error codes:
+ *  EPERS_NOPRCTABLE or EPERS_NOKEY
+ */
+int persistence_get_data_size(char* dbPath, char* key, PersistenceInfo_s* info);
+
+
+
+/**
+ * @brief register for change notifications of a key
+ *
+ * @param dbPath the path to the database where the key is in
+ * @param key the database key to register on
+ *
+ * @return 0 of registration was successfull; -1 if registration failes
+ */
+int persistence_reg_notify_on_change(char* dbPath, char* key);
+
+
+
+/**
+ * @brief delete data
+ *
+ * @param dbPath the path to the database where the key is in
+ * @param key the database key to register on
+ * @param info persistence information
+ *
+ * @return 0 if deletion was successfull;
+ *         or an error code: EPERS_DB_KEY_SIZE, EPERS_NOPRCTABLE, EPERS_DB_ERROR_INTERNAL or EPERS_NOPLUGINFUNCT
+ */
+int persistence_delete_data(char* dbPath, char* dbKey, PersistenceInfo_s* info);
+
+
+
+/**
+ * @brief close the database for the given storage type
+ *
+ * @param info persistence information
+ */
+void database_close(PersistenceInfo_s* info);
+
+
+
+/**
+ * @brief close all databases
+ */
+void database_close_all();
+
+
+//---------------------------------------------------------------------------------------------
+// C U R S O R    F U N C T I O N S
+//---------------------------------------------------------------------------------------------
+
+/**
+ * @brief create a cursor to a DB ; if success, the cursor points to (-1)
+ * to access the first entry in DB, call persistence_db_cursor_next
+ *
+ * @param dbPath[in] absolute path to the database
+ * @param storage[in] the storage identifier (local, shared or custom)
+ *
+ * @return handler to the DB (to be used in successive calls) or error code (< 0)
+ */
+int persistence_db_cursor_create(char* dbPath, PersistenceStorage_e storage, PersistencePolicy_e policy);
+
+/**
+ * @brief move cursor to the next position
+ *
+ * @param handlerDB[in] handler to DB (obtained with persistence_db_cursor_create())
+ *
+ * @return 0 for success, negative value in case of error (check against EPERS_LAST_ENTRY_IN_DB)
+ */
+int persistence_db_cursor_next(unsigned int handlerDB);
+
+/**
+ * @brief get the name of the key pointed by the cursor associated with the database
+ *
+ * @param handlerDB[in] handler to DB (obtained with persistence_db_cursor_create())
+ * @param bufKeyName_out[out] buffer where to pass the name of the key
+ * @param bufSize[out] size of bufKeyName_out
+ *
+ * @return read size (if >= 0), error other way
+ */
+int persistence_db_cursor_get_key(unsigned int handlerDB, char * bufKeyName_out, int bufSize) ;
+
+/**
+ * @brief get the data of the key pointed by the cursor associated with the database
+ *
+ * @param handlerDB[in] handler to DB (obtained with persistence_db_cursor_create())
+ * @param bufKeyData_out[out] buffer where to pass the data of the key
+ * @param bufSize[out] size of bufKeyData_out
+ *
+ * @return read size (if >= 0), error other way
+ */
+int persistence_db_cursor_get_data(unsigned int handlerDB, char * bufData_out, int bufSize) ;
+
+/**
+ * @brief get the data size of the key pointed by the cursor associated with the database
+ *
+ * @param handlerDB[in] handler to DB (obtained with persistence_db_cursor_create())
+ *
+ * @return positive value for data size, negative value for error
+ */
+int persistence_db_cursor_get_data_size(unsigned int handlerDB) ;
+
+
+/**
+ * @brief remove the cursor
+ *
+ * @param handlerDB[in] handler to DB (obtained with persistence_db_cursor_create())
+ *
+ * @return 0 for success, negative value in case of error
+ */
+int persistence_db_cursor_destroy(unsigned int handlerDB) ;
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* PERSISTENCY_CLIENT_LIBRARY_DATA_ACCESS_H */