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 Custom plugin configuration file
  45  *          @attention
  46  *          The plugin configuration file has been changed!
  47  *
  48  *          The configuration file has now the following format<br>
  49  *          <predefinedPluginName> <pathAndLibraryName> <loadingType> <initType>
  50  *
  51  *          <b>Predefined plugin name</b><br>
  52  *          Use one of the following names:
  53  *          - early     => predefined custom library for early persistence
  54  *          - secure    => predefined custom library for secure persistence
  55  *          - emergency => predefined custom library for emengency persistence
  56  *          - hwinfo    => predefined custom library for hw information
  57  *          - custom1   => custom library 1
  58  *          - custom2   => custom library 2
  59  *          - custom3   => custom library 3
  60  *
  61  *          <b>Path and library name:</b><br>
  62  *          The name and path of the library
  63  *
  64  *          <b>Valid loading type:</b>
  65  *          - "init" ==> if the plugin must be laoding during the pclInitLibrary function
  66  *          - "on"      ==> if on demand laoding of the plugin is requested. The plugin will be loaded
  67  *          when a plugin function will be loaded the first time
  68  *
  69  *          <b>Init Type:</b>
  70  *          - sync ==> use the "plugin_init" function for plugin initialization
  71  *          - async ==> use the "plugin_init_async" function for plugin initialization
  72  *
  73  *          <b>Example:</b><br>
  74  *          hwinfo /usr/local/lib/libhwinfoperscustom.so init async
  75  *
  76  *          @note
  77  *          Make sure that there is only ONE blank between each entry and no blank at the end of the file.
  78  *          The parser has been optimized for speed, so there is less error checking.
  79  */
  80
  81
  82
  83 #ifdef __cplusplus
  84 extern "C" {
  85 #endif
  86
  87 /** \defgroup PCL_DEFINES_API Defines, Struct, Enum
  88  * \{
  89  */
  90
  91 #define  PERSIST_API_INTERFACE_VERSION   (0x01030000U)
  92
  93 /** \} */
  94
  95
  96 /** \defgroup SHUTDOWN_TYPE notifications type definitions
  97  * according to Node State Manager Component
  98  * \{
  99  */
 100
 101 #define PCL_SHUTDOWN_TYPE_FAST   2     /// Client registered for fast lifecycle shutdown
 102 #define PCL_SHUTDOWN_TYPE_NORMAL 1     /// Client registered for normal lifecycle shutdown
 103 #define PCL_SHUTDOWN_TYPE_NONE   0     /// Client does not register to lifecycle shutdown
 104 /** \} */
 105
 106
 107 /** \defgroup PCL_OVERALL functions for Library initialization
 108  *  The following functions have to be called for library initialization
 109  * \{
 110  */
 111
 112
 113 #define PCL_SHUTDOWN             1              /// trigger shutdown
 114 #define PCL_SHUTDOWN_CANEL       0              /// cancel shutdown
 115
 116
 117 /**
 118  * @brief initialize client library.
 119  *        This function will be called by the process using the PCL during startup phase.
 120  *
 121  * @attention This function is currently  N O T  part of the GENIVI compliance specification
 122  *
 123  * @param appname application name, the name must be a unique name in the system
 124  * @param shutdownMode shutdown mode ::PCL_SHUTDOWN_TYPE_FAST or ::PCL_SHUTDOWN_TYPE_NORMAL
 125  *
 126  * @return positive value: success;
 127  *   On error a negative value will be returned with the following error codes:
 128  *   ::EPERS_NOT_INITIALIZED, ::EPERS_INIT_DBUS_MAINLOOP,
 129  *   ::EPERS_REGISTER_LIFECYCLE, ::EPERS_REGISTER_ADMIN
 130  */
 131 int pclInitLibrary(const char* appname, int shutdownMode);
 132
 133
 134 /**
 135  * @brief deinitialize client library
 136  *        This function will be called during the shutdown phase of the process which uses the PCL.
 137  *
 138  * @attention This function is currently  N O T  part of the GENIVI compliance specification
 139  *
 140  * @return positive value: success;
 141  *   On error a negative value will be returned.
 142  */
 143 int pclDeinitLibrary(void);
 144
 145
 146
 147
 148 /**
 149  * @brief pclLifecycleSet client library
 150  *        This function can be called if to flush and write back the data form cache to memory device.
 151  *        The function is only available if PCL_SHUTDOWN_TYPE_NONE has been used in pclInitLibrary.
 152  *
 153  * @attention This function is currently  N O T  part of the GENIVI compliance specification
 154  * @attention In order to prevent misuse of this function the cancel shutdown request
 155  *            can only be called 3 times per lifecycle.
 156  *            If this function has been called by an application more then 3 times the application
 157  *            will not be able to store it's data anymore during the current lifecycle.
 158  *            The application isn't fully operable in this lifecycle anymore.
 159  *            In the next lifecycle the application can store data again until the limit above
 160  *            has been reached.
 161  *
 162  * @parm PCL_SHUTDOWN for write back data when shutdown is requested,
 163  *       and PCL_SHUTDOWN_CANEL when shutdown cancel request has been received.
 164  *
 165  * @return positive value: success;
 166  *   On error a negative value will be returned with the following error codes:
 167  *   ::EPERS_COMMON, ::EPERS_MAX_CANCEL_SHUTDOWN, ::EPERS_SHTDWN_NO_PERMIT
 168  */
 169 int pclLifecycleSet(int shutdown);
 170
 171
 172 /** \} */
 173
 174 #ifdef __cplusplus
 175 }
 176 #endif
 177
 178 /** \} */ /* End of API */
 179 /** \} */ /* End of MODULE */
 180
 181
 182 #endif /* PERSISTENCY_CLIENT_LIBRARY_H */