Missing files for prevoius commitID; updated header documentation

7 files changed, 65 insertions, 15 deletions

diff --git a/include/persistence_client_library.h b/include/persistence_client_library.h
index b63ff0f..21615b1 100644
--- a/include/persistence_client_library.h
+++ b/include/persistence_client_library.h
@@ -108,9 +108,38 @@ extern "C" {
  * \{
  */
 
-#define PCL_SHUTDOWN_TYPE_FAST   2     /// Client registered for fast lifecycle shutdown
-#define PCL_SHUTDOWN_TYPE_NORMAL 1     /// Client registered for normal lifecycle shutdown
-#define PCL_SHUTDOWN_TYPE_NONE   0     /// Client does not register to lifecycle shutdown
+
+/**
+ * @brief PCL registered for fast lifecycle shutdown
+ *        A lifecycle register message will be sent to the Node State Manager (NSM).
+ *        When the system performs a fast shutdown the PCL receives this shutdown notification
+ *        from the NSM, and will write back changed data to non volatile memory device.
+ */
+#define PCL_SHUTDOWN_TYPE_FAST   2
+
+/**
+ * @brief PCL registered for normal lifecycle shutdown
+ *        A lifecycle register message will be sent to the Node State Manager (NSM).
+ *        When the system performs a normal shutdown the PCL receives this shutdown notification
+ *        from the NSM, and will write back changed data to non volatile memory device.
+ */
+#define PCL_SHUTDOWN_TYPE_NORMAL 1
+
+/**
+ * @brief PCL does NOT register to lifecycle shutdown
+ *        The PCL does NOT receive any shutdown notification form the Node State Manager (NSM).
+ *        The application itself is responsible to get shutdown information.
+ *        To write back changed data to non volatile memory devicem, the application can use the
+ *        function ::pclLifecycleSet with the parameter ::PCL_SHUTDOWN.
+ *        PCL writes back the data, and blocks any further access to persistent data.
+ *        In order to access data again (e.g. using ::pclKeyWriteData) the application
+ *        needs to call ::pclLifecycleSet again with the parameter ::PCL_SHUTDOWN_CANCEL.
+ *        There is a limitation for calling ::pclLifecycleSet with the parameter ::PCL_SHUTDOWN_CANCEL.
+ *        It can be called only for a limited number, which is defined in ::Shutdown_MaxCount.
+ *
+ * @attention PCL does not receive any shutdown notifications from NSM.
+ */
+#define PCL_SHUTDOWN_TYPE_NONE   0
 /** \} */
 
 
@@ -120,8 +149,10 @@ extern "C" {
  */
 
 
-#define PCL_SHUTDOWN             1		/// trigger shutdown
-#define PCL_SHUTDOWN_CANEL       0		/// cancel shutdown
+/// trigger shutdown
+#define PCL_SHUTDOWN              1
+/// cancel shutdown
+#define PCL_SHUTDOWN_CANCEL       0
 
 
 /**
@@ -145,6 +176,13 @@ int pclInitLibrary(const char* appname, int shutdownMode);
  * @brief deinitialize client library
  *        This function will be called during the shutdown phase of the process which uses the PCL.
  *
+ * @attention If this function will be called the PCL is NOT operational anymore.
+ *            The function ::pclInitLibrary needs to be called to make PCL operational again.
+ *            This function should only be called at the end of the lifecycle.
+ *            It is not recommended to be called during a lifecycle,
+ *            if it's needed your should know what you do and why exactly you need to do this in
+ *            this way.
+ *
  * @attention This function is currently  N O T  part of the GENIVI compliance specification
  *
  * @return positive value: success;
@@ -163,8 +201,10 @@ int pclDeinitLibrary(void);
  * @attention This function is currently  N O T  part of the GENIVI compliance specification
  * @attention In order to prevent misuse of this function the cancel shutdown request
  *            can only be called 3 times per lifecycle.
- *            If this function has been called by an application more then 3 times the application
- *            will not be able to store it's data anymore during the current lifecycle.
+ *            The function called by an application with the parameter ::PCL_SHUTDOWN_CANCEL
+ *            is limited to a value defined in ::Shutdown_MaxCount.
+ *            When an application has reached this limit, it will not be able to store
+ *            it's data anymore during the current lifecycle.
  *            The application isn't fully operable in this lifecycle anymore.
  *            In the next lifecycle the application can store data again until the limit above
  *            has been reached.
diff --git a/src/persistence_client_library.c b/src/persistence_client_library.c
index 27df48e..2ee3f23 100644
--- a/src/persistence_client_library.c
+++ b/src/persistence_client_library.c
@@ -167,7 +167,7 @@ int pclDeinitLibrary(void)
    	data.message.string[0] = '\0'; 	// no string parameter, set to 0
 
       DLT_LOG(gPclDLTContext, DLT_LOG_INFO, DLT_STRING("pclDeinitLibrary - D E I N I T  client library - "), DLT_STRING(gAppId),
-                                         DLT_STRING("- init counter: "), DLT_INT(gPclInitialized));
+                                            DLT_STRING("- init counter: "), DLT_INT(gPclInitialized));
 
       // unregister for lifecycle dbus messages
       if(gShutdownMode != PCL_SHUTDOWN_TYPE_NONE)
@@ -226,6 +226,8 @@ int pclDeinitLibrary(void)
    }
    else
    {
+   	DLT_LOG(gPclDLTContext, DLT_LOG_WARN, DLT_STRING("pclDeinitLibrary - D E I N I T  client library - "), DLT_STRING(gAppId),
+   	                                      DLT_STRING("- NOT INITIALIZED: "));
       rval = EPERS_NOT_INITIALIZED;
    }
    return rval;
@@ -241,10 +243,12 @@ int pclLifecycleSet(int shutdown)
 	{
 		if(shutdown == PCL_SHUTDOWN)
 		{
+			DLT_LOG(gPclDLTContext, DLT_LOG_INFO, DLT_STRING("pclLifecycleSet - PCL_SHUTDOWN -"), DLT_STRING(gAppId));
 			process_prepare_shutdown(Shutdown_Partial);	// close all db's and fd's and block access
 		}
-		else if(shutdown == PCL_SHUTDOWN_CANEL)
+		else if(shutdown == PCL_SHUTDOWN_CANCEL)
 		{
+			DLT_LOG(gPclDLTContext, DLT_LOG_INFO, DLT_STRING("pclLifecycleSet - PCL_SHUTDOWN_CANCEL -"), DLT_STRING(gAppId), DLT_STRING(" Cancel Counter - "), DLT_INT(gCancelCounter));
 			if(gCancelCounter < Shutdown_MaxCount)
 			{
 				pers_unlock_access();
diff --git a/src/persistence_client_library_dbus_cmd.c b/src/persistence_client_library_dbus_cmd.c
index 7275347..89c019c 100644
--- a/src/persistence_client_library_dbus_cmd.c
+++ b/src/persistence_client_library_dbus_cmd.c
@@ -186,6 +186,8 @@ void process_prepare_shutdown(int complete)
 {
    int i = 0, rval = 0;
 
+   DLT_LOG(gPclDLTContext, DLT_LOG_INFO, DLT_STRING("process_prepare_shutdown - writing down all changed data and closing all handles"));
+
    // block write
    pers_lock_access();
 
diff --git a/src/persistence_client_library_dbus_service.c b/src/persistence_client_library_dbus_service.c
index 0ecbac8..5f60264 100644
--- a/src/persistence_client_library_dbus_service.c
+++ b/src/persistence_client_library_dbus_service.c
@@ -617,6 +617,7 @@ int mainLoop(DBusObjectPathVTable vtable, DBusObjectPathVTable vtable2,
                                  {
                                     pthread_mutex_lock(&gMainCondMtx);
                                     //printf("--- *** --- Receive => mainloop => cmd: %d | string: %s | size: %d\n\n", readData.message.cmd, readData.message.string, ret);
+                                    DLT_LOG(gPclDLTContext, DLT_LOG_INFO, DLT_STRING("mainLoop - receive cmd:"), DLT_INT(readData.message.cmd));
                                     switch (readData.message.cmd)
                                     {
                                        case CMD_PAS_BLOCK_AND_WRITE_BACK:
diff --git a/src/persistence_client_library_lc_interface.c b/src/persistence_client_library_lc_interface.c
index 4149ace..5af3fca 100644
--- a/src/persistence_client_library_lc_interface.c
+++ b/src/persistence_client_library_lc_interface.c
@@ -138,6 +138,7 @@ DBusHandlerResult checkLifecycleMsg(DBusConnection * connection, DBusMessage * m
 
    if((0==strncmp(gDbusLcConsterface, dbus_message_get_interface(message), 46)))
    {
+   	DLT_LOG(gPclDLTContext, DLT_LOG_INFO, DLT_STRING("checkLifecycleMsg - Received dbus message: "), DLT_STRING(dbus_message_get_member(message)));
       if((0==strncmp(gDbusLcConsMsg, dbus_message_get_member(message), 16)))
       {
          result = msg_lifecycleRequest(connection, message);
diff --git a/src/persistence_client_library_pas_interface.c b/src/persistence_client_library_pas_interface.c
index 0079df0..94e3df6 100644
--- a/src/persistence_client_library_pas_interface.c
+++ b/src/persistence_client_library_pas_interface.c
@@ -209,6 +209,8 @@ DBusHandlerResult checkPersAdminMsg(DBusConnection * connection, DBusMessage * m
 
    if((0==strcmp(gDbusPersAdminConsInterface, dbus_message_get_interface(message))))
    {
+   	DLT_LOG(gPclDLTContext, DLT_LOG_INFO, DLT_STRING("checkPersAdminMsg - Received dbus message: "), DLT_STRING(dbus_message_get_member(message)));
+
       if((0==strcmp(gDbusPersAdminConsMsg, dbus_message_get_member(message))))
       {
          result = msg_persAdminRequest(connection, message);
diff --git a/test/persistence_client_library_test.c b/test/persistence_client_library_test.c
index 6e6e9aa..c5ea0a0 100644
--- a/test/persistence_client_library_test.c
+++ b/test/persistence_client_library_test.c
@@ -1284,12 +1284,12 @@ START_TEST(test_InitDeinit)
    x_fail_unless(rval != EPERS_SHUTDOWN_NO_PERMIT, "Lifecycle set NOT allowed, but should");
 
 
-   rval = pclLifecycleSet(PCL_SHUTDOWN_CANEL);
-   rval = pclLifecycleSet(PCL_SHUTDOWN_CANEL);
-   rval = pclLifecycleSet(PCL_SHUTDOWN_CANEL);
-   rval = pclLifecycleSet(PCL_SHUTDOWN_CANEL);
-   rval = pclLifecycleSet(PCL_SHUTDOWN_CANEL);
-   rval = pclLifecycleSet(PCL_SHUTDOWN_CANEL);
+   rval = pclLifecycleSet(PCL_SHUTDOWN_CANCEL);
+   rval = pclLifecycleSet(PCL_SHUTDOWN_CANCEL);
+   rval = pclLifecycleSet(PCL_SHUTDOWN_CANCEL);
+   rval = pclLifecycleSet(PCL_SHUTDOWN_CANCEL);
+   rval = pclLifecycleSet(PCL_SHUTDOWN_CANCEL);
+   rval = pclLifecycleSet(PCL_SHUTDOWN_CANCEL);
    //EPERS_COMMON
 
    pclDeinitLibrary();