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
  45
  46
  47 #ifdef __cplusplus
  48 extern "C" {
  49 #endif
  50
  51 /** \defgroup PCL_DEFINES_API Defines, Struct, Enum
  52  * \{
  53  */
  54
  55 #define  PERSIST_API_INTERFACE_VERSION   (0x01030000U)
  56
  57 /** \} */
  58
  59
  60 /** \defgroup SHUTDOWN_TYPE notifications type definitions
  61  * according to Node State Manager Component
  62  * \{
  63  */
  64
  65 #define PCL_SHUTDOWN_TYPE_FAST   2     /// Client registered for fast lifecycle shutdown
  66 #define PCL_SHUTDOWN_TYPE_NORMAL 1     /// Client registered for normal lifecycle shutdown
  67 #define PCL_SHUTDOWN_TYPE_NONE   0     /// Client does not register to lifecycle shutdown
  68 /** \} */
  69
  70
  71 /** \defgroup PCL_OVERALL functions for Library initialization
  72  *  The following functions have to be called for library initialization
  73  * \{
  74  */
  75
  76
  77 #define PCL_SHUTDOWN             1              /// trigger shutdown
  78 #define PCL_SHUTDOWN_CANEL       0              /// cancel shutdown
  79
  80
  81 /**
  82  * @brief initialize client library.
  83  *        This function will be called by the process using the PCL during startup phase.
  84  *
  85  * @attention This function is currently  N O T  part of the GENIVI compliance specification
  86  *
  87  * @param appname application name, the name must be a unique name in the system
  88  * @param shutdownMode shutdown mode ::PCL_SHUTDOWN_TYPE_FAST or ::PCL_SHUTDOWN_TYPE_NORMAL
  89  *
  90  * @return positive value: success;
  91  *   On error a negative value will be returned with the following error codes:
  92  *   ::EPERS_NOT_INITIALIZED, ::EPERS_INIT_DBUS_MAINLOOP,
  93  *   ::EPERS_REGISTER_LIFECYCLE, ::EPERS_REGISTER_ADMIN
  94  */
  95 int pclInitLibrary(const char* appname, int shutdownMode);
  96
  97
  98 /**
  99  * @brief deinitialize client library
 100  *        This function will be called during the shutdown phase of the process which uses the PCL.
 101  *
 102  * @attention This function is currently  N O T  part of the GENIVI compliance specification
 103  *
 104  * @return positive value: success;
 105  *   On error a negative value will be returned.
 106  */
 107 int pclDeinitLibrary(void);
 108
 109
 110
 111
 112 /**
 113  * @brief pclLifecycleSet client library
 114  *        This function can be called if to flush and write back the data form cache to memory device.
 115  *        The function is only available if PCL_SHUTDOWN_TYPE_NONE has been used in pclInitLibrary.
 116  *
 117  * @attention This function is currently  N O T  part of the GENIVI compliance specification
 118  * @attention In order to prevent misuse of this function the cancel shutdown request
 119  *            can only be called 3 times per lifecycle.
 120  *            If this function has been called by an application more then 3 times the application
 121  *            will not be able to store it's data anymore during the current lifecycle.
 122  *            The application isn't fully operable in this lifecycle anymore.
 123  *            In the next lifecycle the application can store data again until the limit above
 124  *            has been reached.
 125  *
 126  * @parm PCL_SHUTDOWN for write back data when shutdown is requested,
 127  *       and PCL_SHUTDOWN_CANEL when shutdown cancel request has been received.
 128  *
 129  * @return positive value: success;
 130  *   On error a negative value will be returned with the following error codes:
 131  *   ::EPERS_COMMON, ::EPERS_MAX_CANCEL_SHUTDOWN, ::EPERS_SHTDWN_NO_PERMIT
 132  */
 133 int pclLifecycleSet(int shutdown);
 134
 135
 136 /** \} */
 137
 138 #ifdef __cplusplus
 139 }
 140 #endif
 141
 142 /** \} */ /* End of API */
 143 /** \} */ /* End of MODULE */
 144
 145
 146 #endif /* PERSISTENCY_CLIENT_LIBRARY_H */