Added ref counter for init/deinit; updated header doxygen tags; removed several printf; different minor optimizations

5 files changed, 213 insertions, 123 deletions

diff --git a/include/persistence_client_custom.h b/include/persistence_client_custom.h
index f33df45..3fc894e 100644
--- a/include/persistence_client_custom.h
+++ b/include/persistence_client_custom.h
@@ -17,6 +17,7 @@
  *  \par change history
  *  \verbatim
  *  Date       Author    Version  Description 
+ *  2013.06.26 ihuerner  1.5.0.0  added description of parameters
  *  2013.01.06 ihuerner  1.4.0.0  plugin_handle_open and plugin_set_data changed from char* to const char*
  *  2012.11.22 gsagnes   1.3.0.0  add the handle_get_size, correct the type to int
  *  2012.10.16 gsagnes   1.2.0.0  add get_size, create_backup, restore_backup
@@ -33,7 +34,7 @@
 /** Module version
 The lower significant byte is equal 0 for released version only
 */
-#define     PERSIST_CUSTOMER_INTERFACE_VERSION            (0x01040000U)
+#define     PERSIST_CUSTOMER_INTERFACE_VERSION            (0x01050000U)

 
 /**
  * <b>Plugin interface:</b>
@@ -46,149 +47,152 @@ The lower significant byte is equal 0 for released version only
  */
  
 /**
- * \brief create backup
+ * @brief create backup
  *
- * \param backup_id Name of the backup / identifier
+ * @param backup_id Name of the backup / identifier
  *
- * \return positive value: backup success (size of backup, bytes); negative value: error
+ * @return positive value: backup success (size of backup, bytes); negative value: error
  */
 int plugin_create_backup(const char* backup_id);
 
  /**
- * \brief deinitialize plugin (during shutdown)
+ * @brief deinitialize plugin (during shutdown)
  *
- * \return positive value: init success; negative value: error
+ * @return positive value: init success; negative value: error
  */
 int plugin_deinit();
 
 /**
- * \brief delete data
+ * @brief delete data
  *
- * \param path the path to the data to delete
+ * @param path the path to the data to delete
  *
- * \return positive value: delete success; negative value: error
+ * @return positive value: delete success; negative value: error
  */
 int plugin_delete_data(const char* path);
 
 /**
- * \brief get backup name
+ * @brief get backup name
  *
- * \param backup_id Name of the backup / identifier
- * \param size size of the buffer to return the identifier
+ * @param backup_id Name of the backup / identifier
+ * @param size size of the buffer to return the identifier
  *
- * \return positive value: success, length of identifier; negative value: error
+ * @return positive value: success, length of identifier; negative value: error
  */
 int plugin_get_backup(char* backup_id, int size);
 
 /**
- * \brief gets the size of persistent data in bytes
+ * @brief gets the size of persistent data in bytes
  *
- * \param path the path to the data
+ * @param path the path to the data
  *
- * \return positive value: the size; negative value: error code
+ * @return positive value: the size; negative value: error code
  */
 int plugin_get_size(const char* path);
 
 /**
- * \brief get data
+ * @brief get data
  *
- * \param path the path to the resource to get
- * \param buffer the buffer to store data
- * \param size the number of bytes to get data
+ * @param path the path to the resource to get
+ * @param buffer the buffer to store data
+ * @param size the number of bytes to get data
  *
- * \return positive value: size data read in bytes; negative value: error
+ * @return positive value: size data read in bytes; negative value: error
  */
 int plugin_get_data(const char* path, char* buffer, int size);
  
 /**
- * \brief close the given handle
+ * @brief close the given handle
  *
- * \param handle the handle to close
+ * @param handle the handle to close
  *
- * \return positive value: successfully closed; negative value: error
+ * @return positive value: successfully closed; negative value: error
  */
 int plugin_handle_close(int handle);
 
 /**
- * \brief get data
+ * @brief get data
  *
- * \param handle the handle returned from open
- * \param buffer the buffer to store data
- * \param size the number of bytes to get data
+ * @param handle the handle returned from open
+ * @param buffer the buffer to store data
+ * @param size the number of bytes to get data
  *
- * \return positive value: size data read in bytes; negative value: error
+ * @return positive value: size data read in bytes; negative value: error
  */
 int plugin_handle_get_data(int handle, char* buffer, int size);
 
 /**
- * \brief open a resource
+ * @brief open a resource
  *
- * \param path the path to the resource to open
- * \param flag open flags
- * \param mode the open mode
+ * @param path the path to the resource to open
+ * @param flag open flags
+ * @param mode the open mode
  *
- * \return positive value: handle; negative value: error
+ * @return positive value: handle; negative value: error
  */
 int plugin_handle_open(const char* path, int flag, int mode);
 
 /**
- * \brief set data
+ * @brief set data
  *
- * \param handle the handle given by open
- * \param buffer the data to write
- * \param size the number of bytes to write
+ * @param handle the handle given by open
+ * @param buffer the data to write
+ * @param size the number of bytes to write
  *
- * \return positive size data set; negative value: error
+ * @return positive size data set; negative value: error
  */
 int plugin_handle_set_data(int handle, char* buffer, int size);
 
 /**
- * \brief initialize plugin
+ * @brief initialize plugin
  *
- * \return positive value: init success; negative value: error
+ * @return positive value: init success; negative value: error
  */
 int plugin_init();
 
 /**
- * \brief restore backup
+ * @brief restore backup
  *
- * \param backup_id Name of the backup / identifier
+ * @param backup_id Name of the backup / identifier
  *
- * \return positive value: backup success (size of backup, bytes); negative value: error
+ * @return positive value: backup success (size of backup, bytes); negative value: error
  */
 int plugin_restore_backup(const char* backup_id);
 
 /**
- * \brief set data
+ * @brief set data
  *
- * \param path the path to the resource to set
- * \param buffer the data to write
- * \param size the number of bytes to write
+ * @param path the path to the resource to set
+ * @param buffer the data to write
+ * @param size the number of bytes to write
  *
- * \return positive size data set; negative value: error
+ * @return positive size data set; negative value: error
  */
 int plugin_set_data(const char* path, char* buffer, int size);
 
 /**
- * \brief typdef of callback function prototype
+ * @brief typdef of callback function prototype
+ *
+ * @param int pass a statusId to the function
+ * @param void* pass an argument to the function
  */
 typedef int (*plugin_callback_t) (int, void*);
 
 /**
- * \brief registercallback for status notifications
+ * @brief registercallback for status notifications
  *
- * \param pFunct the callback
+ * @param pFunct the callback
  *
- * \return positive value: register success; negative value error
+ * @return positive value: register success; negative value error
  */
 int plugin_get_status_notification_clbk(plugin_callback_t pFunct);
 
 /**
- * \brief get size
+ * @brief get size
  *
- * \param handle the handle given by open
+ * @param handle the handle given by open
  *
- * \return positive value: the size; negative value: error code
+ * @return positive value: the size; negative value: error code
  */
 int plugin_handle_get_size(int handle);
 
diff --git a/include/persistence_client_library.h b/include/persistence_client_library.h
new file mode 100644
index 0000000..646215e
--- /dev/null
+++ b/include/persistence_client_library.h
@@ -0,0 +1,81 @@
+#ifndef PERSISTENCY_CLIENT_LIBRARY_H
+#define PERSISTENCY_CLIENT_LIBRARY_H
+
+/******************************************************************************
+ * Project         Persistency
+ * (c) copyright   2011
+ * 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_key.h
+ * \ingroup        Persistence client library
+ * \author         Ingo Huerner (XSe) / Guy Sagnes (Continental)
+ * \brief          Header of the persistence client library.
+ *                 Library provides an API to access persistent data
+ * \par change history
+ * Date     Author          Version
+ * 25/06/13 Ingo Hürner     1.0.0 - Rework of Init functions
+ *
+ */
+/** \ingroup GEN_PERS */
+/** \defgroup PERS_CLIENT Client: initialisation access
+ *  \{
+ */
+/** \defgroup PERS_CLIENT_INTERFACE API document
+ *  \{
+ */
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** \defgroup PCL_DEFINES_API Defines, Struct, Enum
+ * \{
+ */
+
+#define  PERSIST_API_INTERFACE_VERSION   (0x01000000U)
+
+/** \} */
+
+
+/** \defgroup PCL_OVERALL functions for Library Initialisation
+ * The following functions have to be called to allow intialisation of the internal interfaces.
+ * \{
+ */
+
+/**
+ * @brief initalize client library
+ *
+ * @attention This function is currently  N O T  part of the GENIVI compliance specification
+ *
+ * @param appname application name, the name must be a unique name in the system
+ * @param shutdownMode shutdown mode ::PCL_SHUTDOWN_TYPE_FAST or ::PCL_SHUTDOWN_TYPE_NORMAL
+ *
+ * @return positive value: success;
+ *   On error a negative value will be returned with th follwoing error codes:
+ *   ::EPERS_LOCKFS, ::EPERS_NOT_INITIALIZED
+ */
+int pclInitLibrary(const char* appname, int shutdownMode);
+
+
+/**
+ * @brief deinitialize client library
+ *
+ * @attention This function is currently  N O T  part of the GENIVI compliance specification
+ *
+ * @return positive value: success;
+ *   On error a negative value will be returned with th follwoing error codes: ::EPERS_LOCKFS
+ */
+int pclDeinitLibrary(void);
+
+/** \} */
+
+/** \} */ /* End of API */
+/** \} */ /* End of MODULE */
+
+#endif /* PERSISTENCY_CLIENT_LIBRARY_H */
diff --git a/include/persistence_client_library_error_def.h b/include/persistence_client_library_error_def.h
index 458af90..6897667 100644
--- a/include/persistence_client_library_error_def.h
+++ b/include/persistence_client_library_error_def.h
@@ -18,6 +18,10 @@
  * @brief          Error definition header
  * @see
  */
+/** \ingroup GEN_PERS */
+/** \defgroup PERS_GEN_ERROR Client Library: Generic errors
+ *  \{
+ */
 
 #ifdef __cplusplus
 extern "C" {
@@ -85,19 +89,13 @@ extern "C" {
 #define EPERS_DB_VALUE_SIZE      (-29)
 /// resource is not a key
 #define EPERS_RES_NO_KEY         (-30)
-/// chnage notification signal could ne be sent
-#define EPERS_NOTIFY_SIG         (-30)
-
-
-/**
- * @brief Main dispatching loop
- *
- * @return 0
- */
-void* dbus_main_dispatching_loop(void* dataPtr);
+/// change notification signal could ne be sent
+#define EPERS_NOTIFY_SIG         (-31)
+/// client library has not been initialized
+#define EPERS_NOT_INITIALIZED 	(-32)
 
 #ifdef __cplusplus
 }
 #endif
-
+/** \} */ /* End of PERS_GEN_ERROR */
 #endif /* PERSISTENCE_CLIENT_LIBRARY_ERROR_DEF_H */
diff --git a/include/persistence_client_library_file.h b/include/persistence_client_library_file.h
index f56ccd2..1cdd8a3 100644
--- a/include/persistence_client_library_file.h
+++ b/include/persistence_client_library_file.h
@@ -17,13 +17,13 @@
  * @author         Ingo Huerner (XSe) / Guy Sagnes (Continental)
  * @brief          Header of the persistence client library.
  *                 Library provides an API to access persistent data
- * @see            
+ * @see
  */
-/** \ingroup SSW_PERS */
-/** \defgroup SSW_PERS_FILE Client: File access
+/** \ingroup GEN_PERS */
+/** \defgroup PERS_FILE Client: File access
  *  \{
  */
-/** \defgroup SSW_PERS_FILE_INTERFACE API document
+/** \defgroup PERS_FILE_INTERFACE API document
  *  \{
  */
 #ifdef __cplusplus
@@ -31,9 +31,13 @@ extern "C" {
 #endif
 
 
-#define 	PERSIST_FILEAPI_INTERFACE_VERSION   (0x03000000U)
+#define  PERSIST_FILEAPI_INTERFACE_VERSION   (0x03000000U)
 
+#include "persistence_client_library.h"
 
+/** \defgroup PCL_FILE functions file access
+ * \{
+ */
 
 /**
  * @brief close the given POSIX file descriptor
@@ -168,11 +172,7 @@ int pclFileUnmapData(void* address, long size);
  */
 int pclFileWriteData(int fd, const void * buffer, int buffer_size);
 
-
-
-
-
-
+/** \} */ 
 
 #ifdef __cplusplus
 }
@@ -184,4 +184,3 @@ int pclFileWriteData(int fd, const void * buffer, int buffer_size);
 
 
 #endif /* PERSISTENCY_CLIENT_LIBRARY_FILE_H */
-
diff --git a/include/persistence_client_library_key.h b/include/persistence_client_library_key.h
index ea0b7af..e125bfa 100644
--- a/include/persistence_client_library_key.h
+++ b/include/persistence_client_library_key.h
@@ -14,16 +14,20 @@
  /**
  * @file           persistence_client_library_key.h
  * @ingroup        Persistence client library
- * @author         Ingo Huerner (XSe) / Guy Sagnes (Continental)
+ * vauthor         Ingo Huerner (XSe) / Guy Sagnes (Continental)
  * @brief          Header of the persistence client library.
  *                 Library provides an API to access persistent data
- * @see            
+ * @par change history
+ * Date     Author          Version
+ * 27/03/13 Ingo Hürner     4.0.0 - Add registration for callback notification
+ * 28/05/13 Ingo Hürner     5.0.0 - Add pclInitLibrary(), pcl DeInitLibrary() incl. shutdown notification
+ * 05/06/13 Oliver Bach     6.0.0 - Rework of Init functions
  */
-/** \ingroup SSW_PERS */
-/** \defgroup SSW_PERS_KEYVALUE Client: Key-value access
+/** \ingroup GEN_PERS */
+/** \defgroup PERS_KEYVALUE Client: Key-value access
  *  \{
  */
-/** \defgroup SSW_PERS_KEYVALUE_INTERFACE API document
+/** \defgroup PERS_KEYVALUE_INTERFACE API document
  *  \{
  */
 
@@ -31,8 +35,14 @@
 extern "C" {
 #endif
 
+/** \defgroup PCL_DEFINES_KEYVALUE Defines, Struct, Enum
+ * \{
+ */
+
+#define  PERSIST_KEYVALUEAPI_INTERFACE_VERSION   (0x06000000U)
+
+#include "persistence_client_library.h"
 
-#define 	PERSIST_KEYVALUEAPI_INTERFACE_VERSION   (0x05000000U)
 
 /**
 * status returned in notification structure
@@ -60,39 +70,31 @@ typedef struct _pclNotification_s
    unsigned int seat_no;                     /// seat id
 } pclNotification_s;
 
-
-/**
- * shutdown notification type definitions
+/** \defgroup SHUTDOWN_TYPE shutdown notification type definitions
  *  according to Node State Manager component
+ * \{
  */
-enum pclShutdownTypeNotification
-{
-   NSM_SHUTDOWN_TYPE_FAST   = 2,    /// Client registered for fast lifecycle shutdown
-   NSM_SHUTDOWN_TYPE_NORMAL = 1     /// Client registered for normal lifecycle shutdown
-};
 
+#define PCL_SHUTDOWN_TYPE_FAST   2      /// Client registered for fast lifecycle shutdown
+#define PCL_SHUTDOWN_TYPE_NORMAL 1      /// Client registered for normal lifecycle shutdown
 
-/// defiinition of the change callback
-typedef int(* pclChangeNotifyCallback_t)(pclNotification_s * notifyStruct);
+/** \} */
 
-/**
- * @brief itialize client library
+/** \} */
+
+/** definition of the change callback
  *
- * @param application name
- * @param shutdown mode NSM_SHUTDOWN_TYPE_FAST or NSM_SHUTDOWN_TYPE_NORMAL
+ * @param notifyStruct structure for notifcation
  *
- */
-void pclInitLibrary(const char* appname, int shutdownMode);
-
+ * @return positive value: success;
+ *   On error a negative value will be returned with the following error codes: ::EPERS_LOCKFS
+*/
+typedef int(* pclChangeNotifyCallback_t)(pclNotification_s * notifyStruct);
 
 
-/**
- * @brief deinitialize client library
- *
- * @param shutdown mode NSM_SHUTDOWN_TYPE_FAST or NSM_SHUTDOWN_TYPE_NORMAL
+/** \defgroup PCL_KEYVALUE functions Key-Value access
+ * \{
  */
-void pclDeinitLibrary(int shutdownMode);
-
 
 /**
  * @brief delete persistent data
@@ -102,8 +104,8 @@ void pclDeinitLibrary(int shutdownMode);
  * @param user_no  the user ID; user_no=0 can not be used as user-ID beacause ‘0’ is defined as System/node
  * @param seat_no  the seat number
  *
- * @return positive value: success; On error a negative value will be returned with th follwoing error codes:
- * EPERS_LOCKFS
+ * @return positive value: success; On error a negative value will be returned with the following error codes:
+ * ::EPERS_LOCKFS
  */
 int pclKeyDelete(unsigned int ldbid, const char* resource_id, unsigned int user_no, unsigned int seat_no);
 
@@ -117,8 +119,8 @@ int pclKeyDelete(unsigned int ldbid, const char* resource_id, unsigned int user_
  * @param user_no  the user ID; user_no=0 can not be used as user-ID beacause ‘0’ is defined as System/node
  * @param seat_no  the seat number
  *
- * @return positive value: the size; On error a negative value will be returned with th follwoing error codes:
- * EPERS_LOCKFS, EPERS_BADPOL, EPERS_NOKEY, EPERS_NOKEYDATA or EPERS_NOPRCTABLE
+ * @return positive value: the size; On error a negative value will be returned with the following error codes:
+ * ::EPERS_LOCKFS, ::EPERS_BADPOL, ::EPERS_NOKEY, ::EPERS_NOKEYDATA or ::EPERS_NOPRCTABLE
  */
 int pclKeyGetSize(unsigned int ldbid, const char* resource_id, unsigned int user_no, unsigned int seat_no);
 
@@ -127,8 +129,8 @@ int pclKeyGetSize(unsigned int ldbid, const char* resource_id, unsigned int user
  *
  * @param key_handle key value handle return by key_handle_open()
  *
- * @return positive value: success; On error a negative value will be returned with th follwoing error codes:
- * EPERS_LOCKFS
+ * @return positive value: success; On error a negative value will be returned with the following error codes:
+ * ::EPERS_LOCKFS
  */
 int pclKeyHandleClose(int key_handle);
 
@@ -139,7 +141,8 @@ int pclKeyHandleClose(int key_handle);
  *
  * @param key_handle key value handle return by key_handle_open()
  *
- * @return positive value: the size; On error a negative value will be returned with th follwoing error codes:
+ * @return positive value: the size; On error a negative value will be returned with the following error codes:
+ * ::EPERS_LOCKFS
  */
 int pclKeyHandleGetSize(int key_handle);
 
@@ -154,7 +157,8 @@ int pclKeyHandleGetSize(int key_handle);
  * @param seat_no  the seat number
  *
  * @return positive value: the key handle to access the value;
- * On error a negative value will be returned with th follwoing error codes:
+ * On error a negative value will be returned with the following error codes:
+ * ::EPERS_LOCKFS
  */
 int pclKeyHandleOpen(unsigned int ldbid, const char* resource_id, unsigned int user_no, unsigned int seat_no);
 
@@ -167,8 +171,8 @@ int pclKeyHandleOpen(unsigned int ldbid, const char* resource_id, unsigned int u
  * @param buffer the buffer for persistent data
  * @param buffer_size size of buffer for reading
  *
- * @return positive value: the bytes read; On error a negative value will be returned with th follwoing error codes:
- *
+ * @return positive value: the bytes read; On error a negative value will be returned with the following error codes:
+ * ::EPERS_LOCKFS
  */
 int pclKeyHandleReadData(int key_handle, unsigned char* buffer, int buffer_size);
 
@@ -180,7 +184,8 @@ int pclKeyHandleReadData(int key_handle, unsigned char* buffer, int buffer_size)
  * @param key_handle key value handle return by key_handle_open()
  * @param callback notification callback
  *
- * @return positive value: registration OK; On error a negative value will be returned with th follwoing error codes:
+ * @return positive value: registration OK; On error a negative value will be returned with the following error codes:
+ * ::EPERS_LOCKFS
  */
 int pclKeyHandleRegisterNotifyOnChange(int key_handle, pclChangeNotifyCallback_t callback);
 
@@ -194,7 +199,8 @@ int pclKeyHandleRegisterNotifyOnChange(int key_handle, pclChangeNotifyCallback_t
  * @param buffer_size the number of bytes to write (default max size is set to 16kB)
  *                    use environment variable PERS_MAX_KEY_VAL_DATA_SIZE to modify default size in bytes
  *
- * @return positive value: the bytes written; On error a negative value will be returned with th follwoing error codes:
+ * @return positive value: the bytes written; On error a negative value will be returned with the following error codes:
+ * ::EPERS_LOCKFS
  */
 int pclKeyHandleWriteData(int key_handle, unsigned char* buffer, int buffer_size);
 
@@ -211,6 +217,7 @@ int pclKeyHandleWriteData(int key_handle, unsigned char* buffer, int buffer_size
  * @param buffer_size size of buffer for reading
  *
  * @return positive value: the bytes read; On error a negative value will be returned with th follwoing error codes:
+ * ::EPERS_LOCKFS
  */
 int pclKeyReadData(unsigned int ldbid, const char* resource_id, unsigned int user_no, unsigned int seat_no, unsigned char* buffer, int buffer_size);
 
@@ -225,8 +232,8 @@ int pclKeyReadData(unsigned int ldbid, const char* resource_id, unsigned int use
  * @param seat_no  the seat number
  * @param callback notification callback
  *
- * @return positive value: registration OK; On error a negative value will be returned with th follwoing error codes:
- *                         EPERS_RES_NO_KEY EPERS_NOKEYDATA  EPERS_NOPRCTABLE
+ * @return positive value: registration OK; On error a negative value will be returned with the following error codes:
+ *                         ::EPERS_RES_NO_KEY ::EPERS_NOKEYDATA  ::EPERS_NOPRCTABLE
  */
 int pclKeyRegisterNotifyOnChange(unsigned int ldbid, const char* resource_id, unsigned int user_no, unsigned int seat_no, pclChangeNotifyCallback_t callback);
 
@@ -243,10 +250,12 @@ int pclKeyRegisterNotifyOnChange(unsigned int ldbid, const char* resource_id, un
  * @param buffer_size the number of bytes to write (default max size is set to 16kB)
  *                    use environment variable PERS_MAX_KEY_VAL_DATA_SIZE to modify default size in bytes
  *
- * @return positive value: the bytes written; On error a negative value will be returned with th follwoing error codes:
+ * @return positive value: the bytes written; On error a negative value will be returned with the following error codes:
+ * ::EPERS_LOCKFS
  */
 int pclKeyWriteData(unsigned int ldbid, const char* resource_id, unsigned int user_no, unsigned int seat_no, unsigned char* buffer, int buffer_size);
 
+/** \} */
 
 #ifdef __cplusplus
 }
@@ -256,4 +265,3 @@ int pclKeyWriteData(unsigned int ldbid, const char* resource_id, unsigned int us
 /** \} */ /* End of MODULE */
 
 #endif /* PERSISTENCY_CLIENT_LIBRARY_KEY_H */
-