include/persistence_client_library.h

   1 #ifndef PERSISTENCY_CLIENT_LIBRARY_H
   2 #define PERSISTENCY_CLIENT_LIBRARY_H
   3
   4 /******************************************************************************
   5  * Project         Persistency
   6  * (c) copyright   2011
   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.h
  16  * \ingroup        Persistence client library
  17  * \author         Ingo Huerner (XSe) / Guy Sagnes (Continental)
  18  * \brief          Header of the persistence client library.
  19  *                 Library provides an API to access persistent data
  20  * \par change history
  21  * Date     Author          Version
  22  * 25/06/13 Ingo Hürner     1.0.0 - Rework of Init functions
  23  * 04/11/13 Ingo Hürner     1.3.0 - Added define for shutdown type none
  24  *
  25  */
  26 /** \ingroup GEN_PERS */
  27 /** \defgroup PERS_CLIENT Client: initialization access
  28  *  \{
  29  */
  30 /** \defgroup PERS_CLIENT_INTERFACE API document
  31  *  \{
  32  */
  33
  34 /**
  35  * @mainpage The Persistence Client Library documentation
  36  *           GENIVI's Persistence Client Library, known as PCL, is responsible for handling persistent data,
  37  *           including all data read and modified during a lifetime of an infotainment system.<br>
  38  *           "Persistent data" is data stored in a non-volatile storage such as a hard disk drive or FLASH memory.
  39  *           <br><br>
  40  *           The Persistence Client Library (PCL) provides an API to applications to read and write persistent data
  41  *           via a key-value and a file interface.<br>
  42  *           It also provide a plugin API to allow users to extend the client library with custom storage solutions.
  43  *
  44  * @section doc Further documentation
  45  * @subsection docUser User Manual
  46  *          There is a a user manual for the client library available,
  47  *          see: http://docs.projects.genivi.org/persistence-client-library/1.0/GENIVI_Persistence_Client_Library_UserManual.pdf
  48  *
  49  * @subsection docArch Architecture Manual
  50  *          For more information about the persistence architecture,
  51  *          see: http://docs.projects.genivi.org/persistence-client-library/1.0/GENIVI_Persistence_ArchitectureDocumentation.pdf
  52  *
  53  *
  54  * @section plugin Custom plugin configuration file
  55  *          @attention
  56  *          The plugin configuration file has been changed!
  57  *
  58  *          The configuration file has now the following format<br>
  59  *          &lt;predefinedPluginName&gt; &lt;pathAndLibraryName&gt; &lt;loadingType&gt; &lt;initType&gt;
  60  *
  61  *          <b>Predefined plugin name</b><br>
  62  *          Use one of the following names:
  63  *          - early     => predefined custom library for early persistence
  64  *          - secure    => predefined custom library for secure persistence
  65  *          - emergency => predefined custom library for emengency persistence
  66  *          - hwinfo    => predefined custom library for hw information
  67  *          - custom1   => custom library 1
  68  *          - custom2   => custom library 2
  69  *          - custom3   => custom library 3
  70  *
  71  *          <b>Path and library name:</b><br>
  72  *          The name and path of the library
  73  *
  74  *          <b>Valid loading type:</b>
  75  *          - "init" ==> if the plugin must be laoding during the pclInitLibrary function
  76  *          - "on"      ==> if on demand laoding of the plugin is requested. The plugin will be loaded
  77  *          when a plugin function will be loaded the first time
  78  *
  79  *          <b>Init Type:</b>
  80  *          - sync ==> use the "plugin_init" function for plugin initialization
  81  *          - async ==> use the "plugin_init_async" function for plugin initialization
  82  *
  83  *          <b>Example:</b><br>
  84  *          hwinfo /usr/local/lib/libhwinfoperscustom.so init async
  85  *
  86  *          @note
  87  *          Make sure that there is only ONE blank between each entry and no blank at the end of the file.
  88  *          The parser has been optimized for speed, so there is less error checking.
  89  */
  90
  91
  92
  93 #ifdef __cplusplus
  94 extern "C" {
  95 #endif
  96
  97 /** \defgroup PCL_DEFINES_API Defines, Struct, Enum
  98  * \{
  99  */
 100
 101 #define  PERSIST_API_INTERFACE_VERSION   (0x01030000U)
 102
 103 /** \} */
 104
 105
 106 /** \defgroup SHUTDOWN_TYPE notifications type definitions
 107  * according to Node State Manager Component
 108  * \{
 109  */
 110
 111
 112 /**
 113  * @brief PCL registered for fast lifecycle shutdown
 114  *        A lifecycle register message will be sent to the Node State Manager (NSM).
 115  *        When the system performs a fast shutdown the PCL receives this shutdown notification
 116  *        from the NSM, and will write back changed data to non volatile memory device.
 117  */
 118 #define PCL_SHUTDOWN_TYPE_FAST   2
 119
 120 /**
 121  * @brief PCL registered for normal lifecycle shutdown
 122  *        A lifecycle register message will be sent to the Node State Manager (NSM).
 123  *        When the system performs a normal shutdown the PCL receives this shutdown notification
 124  *        from the NSM, and will write back changed data to non volatile memory device.
 125  */
 126 #define PCL_SHUTDOWN_TYPE_NORMAL 1
 127
 128 /**
 129  * @brief PCL does NOT register to lifecycle shutdown
 130  *        The PCL does NOT receive any shutdown notification form the Node State Manager (NSM).
 131  *        The application itself is responsible to get shutdown information.
 132  *        To write back changed data to non volatile memory devicem, the application can use the
 133  *        function ::pclLifecycleSet with the parameter ::PCL_SHUTDOWN.
 134  *        PCL writes back the data, and blocks any further access to persistent data.
 135  *        In order to access data again (e.g. using ::pclKeyWriteData) the application
 136  *        needs to call ::pclLifecycleSet again with the parameter ::PCL_SHUTDOWN_CANCEL.
 137  *        There is a limitation for calling ::pclLifecycleSet with the parameter ::PCL_SHUTDOWN_CANCEL.
 138  *        It can be called only for a limited number, which is defined in ::Shutdown_MaxCount.
 139  *
 140  * @attention PCL does not receive any shutdown notifications from NSM.
 141  */
 142 #define PCL_SHUTDOWN_TYPE_NONE   0
 143 /** \} */
 144
 145
 146 /** \defgroup PCL_OVERALL functions for Library initialization
 147  *  The following functions have to be called for library initialization
 148  * \{
 149  */
 150
 151
 152 /// trigger shutdown
 153 #define PCL_SHUTDOWN              1
 154 /// cancel shutdown
 155 #define PCL_SHUTDOWN_CANCEL       0
 156
 157
 158 /**
 159  * @brief initialize client library.
 160  *        This function will be called by the process using the PCL during startup phase.
 161  *
 162  * @attention This function is currently  N O T  part of the GENIVI compliance specification
 163  *
 164  * @param appname application name, the name must be a unique name in the system
 165  * @param shutdownMode shutdown mode ::PCL_SHUTDOWN_TYPE_FAST or ::PCL_SHUTDOWN_TYPE_NORMAL
 166  *
 167  * @return positive value: success;
 168  *   On error a negative value will be returned with the following error codes:
 169  *   ::EPERS_NOT_INITIALIZED, ::EPERS_DBUS_MAINLOOP,
 170  *   ::EPERS_REGISTER_LIFECYCLE, ::EPERS_REGISTER_ADMIN
 171  */
 172 int pclInitLibrary(const char* appname, int shutdownMode);
 173
 174
 175 /**
 176  * @brief deinitialize client library
 177  *        This function will be called during the shutdown phase of the process which uses the PCL.
 178  *
 179  * @attention If this function will be called the PCL is NOT operational anymore.
 180  *            The function ::pclInitLibrary needs to be called to make PCL operational again.
 181  *            This function should only be called at the end of the lifecycle.
 182  *            It is not recommended to be called during a lifecycle,
 183  *            if it's needed your should know what you do and why exactly you need to do this in
 184  *            this way.
 185  *
 186  * @attention This function is currently  N O T  part of the GENIVI compliance specification
 187  *
 188  * @return positive value: success;
 189  *   On error a negative value will be returned.
 190  */
 191 int pclDeinitLibrary(void);
 192
 193
 194
 195
 196 /**
 197  * @brief pclLifecycleSet client library
 198  *        This function can be called if to flush and write back the data form cache to memory device.
 199  *        The function is only available if PCL_SHUTDOWN_TYPE_NONE has been used in pclInitLibrary.
 200  *
 201  * @attention This function is currently  N O T  part of the GENIVI compliance specification
 202  * @attention In order to prevent misuse of this function the cancel shutdown request
 203  *            can only be called 3 times per lifecycle.
 204  *            The function called by an application with the parameter ::PCL_SHUTDOWN_CANCEL
 205  *            is limited to a value defined in ::Shutdown_MaxCount.
 206  *            When an application has reached this limit, it will not be able to store
 207  *            it's data anymore during the current lifecycle.
 208  *            The application isn't fully operable in this lifecycle anymore.
 209  *            In the next lifecycle the application can store data again until the limit above
 210  *            has been reached.
 211  *
 212  * @param shutdown PCL_SHUTDOWN for write back data when shutdown is requested,
 213  *        and PCL_SHUTDOWN_CANEL when shutdown cancel request has been received.
 214  *
 215  * @return positive value: success;
 216  *   On error a negative value will be returned with the following error codes:
 217  *   ::EPERS_COMMON, ::EPERS_SHUTDOWN_MAX_CANCEL, ::EPERS_SHUTDOWN_NO_PERMIT
 218  */
 219 int pclLifecycleSet(int shutdown);
 220
 221
 222 /** \} */
 223
 224 #ifdef __cplusplus
 225 }
 226 #endif
 227
 228 /** \} */ /* End of API */
 229 /** \} */ /* End of MODULE */
 230
 231
 232 #endif /* PERSISTENCY_CLIENT_LIBRARY_H */