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 #define PCL_SHUTDOWN_TYPE_FAST   2     /// Client registered for fast lifecycle shutdown
 112 #define PCL_SHUTDOWN_TYPE_NORMAL 1     /// Client registered for normal lifecycle shutdown
 113 #define PCL_SHUTDOWN_TYPE_NONE   0     /// Client does not register to lifecycle shutdown
 114 /** \} */
 115
 116
 117 /** \defgroup PCL_OVERALL functions for Library initialization
 118  *  The following functions have to be called for library initialization
 119  * \{
 120  */
 121
 122
 123 #define PCL_SHUTDOWN             1              /// trigger shutdown
 124 #define PCL_SHUTDOWN_CANEL       0              /// cancel shutdown
 125
 126
 127 /**
 128  * @brief initialize client library.
 129  *        This function will be called by the process using the PCL during startup phase.
 130  *
 131  * @attention This function is currently  N O T  part of the GENIVI compliance specification
 132  *
 133  * @param appname application name, the name must be a unique name in the system
 134  * @param shutdownMode shutdown mode ::PCL_SHUTDOWN_TYPE_FAST or ::PCL_SHUTDOWN_TYPE_NORMAL
 135  *
 136  * @return positive value: success;
 137  *   On error a negative value will be returned with the following error codes:
 138  *   ::EPERS_NOT_INITIALIZED, ::EPERS_DBUS_MAINLOOP,
 139  *   ::EPERS_REGISTER_LIFECYCLE, ::EPERS_REGISTER_ADMIN
 140  */
 141 int pclInitLibrary(const char* appname, int shutdownMode);
 142
 143
 144 /**
 145  * @brief deinitialize client library
 146  *        This function will be called during the shutdown phase of the process which uses the PCL.
 147  *
 148  * @attention This function is currently  N O T  part of the GENIVI compliance specification
 149  *
 150  * @return positive value: success;
 151  *   On error a negative value will be returned.
 152  */
 153 int pclDeinitLibrary(void);
 154
 155
 156
 157
 158 /**
 159  * @brief pclLifecycleSet client library
 160  *        This function can be called if to flush and write back the data form cache to memory device.
 161  *        The function is only available if PCL_SHUTDOWN_TYPE_NONE has been used in pclInitLibrary.
 162  *
 163  * @attention This function is currently  N O T  part of the GENIVI compliance specification
 164  * @attention In order to prevent misuse of this function the cancel shutdown request
 165  *            can only be called 3 times per lifecycle.
 166  *            If this function has been called by an application more then 3 times the application
 167  *            will not be able to store it's data anymore during the current lifecycle.
 168  *            The application isn't fully operable in this lifecycle anymore.
 169  *            In the next lifecycle the application can store data again until the limit above
 170  *            has been reached.
 171  *
 172  * @param shutdown PCL_SHUTDOWN for write back data when shutdown is requested,
 173  *        and PCL_SHUTDOWN_CANEL when shutdown cancel request has been received.
 174  *
 175  * @return positive value: success;
 176  *   On error a negative value will be returned with the following error codes:
 177  *   ::EPERS_COMMON, ::EPERS_SHUTDOWN_MAX_CANCEL, ::EPERS_SHUTDOWN_NO_PERMIT
 178  */
 179 int pclLifecycleSet(int shutdown);
 180
 181
 182 /** \} */
 183
 184 #ifdef __cplusplus
 185 }
 186 #endif
 187
 188 /** \} */ /* End of API */
 189 /** \} */ /* End of MODULE */
 190
 191
 192 #endif /* PERSISTENCY_CLIENT_LIBRARY_H */