inc/protected/persComRct.h

   1 #ifndef OSS_PERSISTENCE_RESOURCE_CONFIG_TABLE_H
   2 #define OSS_PERSISTENCE_RESOURCE_CONFIG_TABLE_H
   3
   4 /**********************************************************************************************************************
   5 *
   6 * Copyright (C) 2012 Continental Automotive Systems, Inc.
   7 *
   8 * Author: Ionut.Ieremie@continental-corporation.com
   9 *
  10 * Interface: protected - Access to resource configuration table
  11 *
  12 * For additional details see
  13 * https://collab.genivi.org/wiki/display/genivi/SysInfraEGPersistenceConceptInterface
  14 *
  15 * This Source Code Form is subject to the terms of the Mozilla Public
  16 * License, v. 2.0. If a copy of the MPL was not distributed with this
  17 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
  18 *
  19 * Date       Author             Reason
  20 * 2014.07.17 ihuerner  5.0.0.0             :  Update of PersistencePolicy_e, added PersistencePolicy_cd and PersistencePolicy_c
  21 * 2013.04.02 uidl9757  5.0.0.0  CSP_WZ#3321:  Update of PersistenceConfigurationKey_s.permission
  22 * 2013.03.21 uidl9757  4.0.0.0  CSP_WZ#2798:  Update of PersistenceConfigurationKey_s
  23 * 2013.01.23 uidl9757  3.0.0.0  CSP_WZ#2060:  CoC_SSW:Persistence: common interface to be used by both PCL and PAS
  24 *
  25 **********************************************************************************************************************/
  26
  27 /**
  28  * \brief For details see https://collab.genivi.org/wiki/display/genivi/SysInfraEGPersistenceConceptInterface
  29  */
  30
  31
  32 /** \defgroup PERS_COM_RCT Resource Config Table API
  33  *  \{
  34  */
  35
  36
  37 #ifdef __cplusplus
  38 extern "C"
  39 {
  40 #endif  /* #ifdef __cplusplus */
  41
  42 /** \defgroup PERS_RCT_IF_VERSION Interface version
  43  *  \{
  44  */
  45 #define PERS_COM_RESOURCE_CONFIG_TABLE_INTERFACE_VERSION  (0x05010000U)
  46 /** \} */ /* end of PERS_RCT_IF_VERSION */
  47
  48
  49
  50 /** \defgroup PERS_RCT_CONFIG Configuration parameters
  51  * see the defines below for their meaning
  52  *  \{
  53  */
  54
  55 #define PERS_RCT_MAX_LENGTH_RESOURCE_ID 64 /**< Max. length of the resource identifier */
  56 #define PERS_RCT_MAX_LENGTH_RESPONSIBLE 64 /**< Max. length of the responsible application */
  57 #define PERS_RCT_MAX_LENGTH_CUSTOM_NAME 64 /**< Max. length of the customer plugin */
  58 #define PERS_RCT_MAX_LENGTH_CUSTOM_ID   64 /**< Max. length of the custom ID */
  59
  60 /** \} */ /* End of PERS_RCT_CONFIG */
  61
  62
  63
  64 /** \defgroup PERS_RCT_ENUM Enumerators managed in the RCT
  65  *  \{
  66  */
  67 /** data policies */
  68 typedef enum PersistencePolicy_e_
  69 {
  70    PersistencePolicy_wc    = 0,  /**< the data is managed write cached */
  71    PersistencePolicy_wt,         /**< the data is managed write through */
  72    /** insert new entries here ... */
  73
  74    /** make sure this are the last ones, add new enums only before this */
  75    PersistencePolicy_cd,                        /**< configurable default data */
  76    PersistencePolicy_d,                         /**< default data */
  77    PersistencePolicy_na,         /**< the data is not applicable */
  78    PersistencePolicy_LastEntry   /**< last entry */
  79
  80 } PersistencePolicy_e;
  81
  82
  83 /** storages to manage the data */
  84 typedef enum PersistenceStorage_e_
  85 {
  86    PersistenceStorage_local    = 0,  /**< the data is managed local */
  87    PersistenceStorage_shared,        /**< the data is managed shared */
  88    PersistenceStorage_custom,        /**< the data is managed over custom client implementation */
  89
  90    /** insert new entries here ... */
  91    PersistenceStorage_LastEntry      /**< last entry */
  92
  93 } PersistenceStorage_e;
  94
  95 /** specifies the type of the resource */
  96 typedef enum PersistenceResourceType_e_
  97 {
  98    PersistenceResourceType_key    = 0,  /**< key type resource */
  99    PersistenceResourceType_file,        /**< file type resourced */
 100
 101    /** insert new entries here ... */
 102    PersistenceResourceType_LastEntry    /**< last entry */
 103
 104 } PersistenceResourceType_e;
 105
 106 /** specifies the permission on resource's data */
 107 typedef enum PersistencePermission_e_
 108 {
 109     PersistencePermission_ReadWrite = 0,    /**< random access to data is allowed */
 110     PersistencePermission_ReadOnly,         /**< only read access to data is allowed */
 111     PersistencePermission_WriteOnly,        /**< only write access to data is allowed */
 112
 113     /** insert new entries here ... */
 114     PersistencePermission_LastEntry         /**< last entry */
 115 } PersistencePermission_e;
 116
 117 /** \} */ /* End of PERS_RCT_ENUM */
 118
 119
 120
 121 /** \defgroup PERS_RCT_STRUCT Structures managed in the RCT
 122  *  \{
 123  */
 124 /** resource configuration */
 125 typedef struct PersistenceConfigurationKey_s_
 126 {
 127    PersistencePolicy_e          policy;                                              /**< policy  */
 128    PersistenceStorage_e         storage;                                             /**< definition of storage to use */
 129    PersistenceResourceType_e    type;                                                /**< type of the resource */
 130    PersistencePermission_e      permission;                                          /**< access right */
 131    unsigned int                 max_size;                                            /**< max size expected for the key */
 132    char                         reponsible[PERS_RCT_MAX_LENGTH_RESPONSIBLE];         /**< name of responsible application */
 133    char                         custom_name[PERS_RCT_MAX_LENGTH_CUSTOM_NAME];        /**< name of the customer plugin */
 134    char                         customID[PERS_RCT_MAX_LENGTH_CUSTOM_ID];             /**< internal ID for the custom type resource */
 135 } PersistenceConfigurationKey_s;
 136 /** \} */ /* End of PERS_RCT_STRUCT */
 137
 138
 139
 140 /** \defgroup PERS_RCT_FUNCTIONS Functions
 141  *  \{
 142  */
 143
 144
 145 /**
 146  * \brief Obtain a handler to RCT indicated by rctPathname
 147  * \note : RCT is created if it does not exist and (bForceCreationIfNotPresent != 0)
 148  *
 149  * \param rctPathname                   [in] absolute path to RCT (length limited to \ref PERS_ORG_MAX_LENGTH_PATH_FILENAME)
 150  * \param bForceCreationIfNotPresent    [in] if !=0x0, the RCT is created if it does not exist
 151  *
 152  * \return >= 0 for valid handler, negative value for error (\ref PERS_COM_ERROR_CODES_DEFINES)
 153  */
 154 signed int persComRctOpen(char const * rctPathname, unsigned char bForceCreationIfNotPresent) ;
 155
 156 /**
 157  * \brief Close handler to RCT
 158  *
 159  * \param handlerRCT    [in] handler obtained with persComRctOpen
 160  *
 161  * \return 0 for success, negative value for error (\ref PERS_COM_ERROR_CODES_DEFINES)
 162  */
 163 signed int persComRctClose(signed int handlerRCT) ;
 164
 165 /**
 166  * \brief write a resourceID-value pair into RCT
 167  *
 168  * \param handlerRCT    [in] handler obtained with persComRctOpen
 169  * \param resourceID    [in] resource's identifier (length limited to \ref PERS_RCT_MAX_LENGTH_RESOURCE_ID)
 170  * \param psConfig      [in] configuration for resourceID
 171  *
 172  * \return 0 for success, negative value for error (\ref PERS_COM_ERROR_CODES_DEFINES)
 173  */
 174 signed int persComRctWrite(signed int handlerRCT, char const * resourceID, PersistenceConfigurationKey_s const * psConfig) ;
 175
 176
 177 /**
 178  * \brief read a resourceID's configuration from RCT
 179  *
 180  * \param handlerRCT    [in] handler obtained with persComRctOpen
 181  * \param resourceID    [in] resource's identifier (length limited to \ref PERS_RCT_MAX_LENGTH_RESOURCE_ID)
 182  * \param psConfig_out  [out]where to return the configuration for resourceID
 183  *
 184  * \return read size [byte], or negative value for error (\ref PERS_COM_ERROR_CODES_DEFINES)
 185  */
 186 signed int persComRctRead(signed int handlerRCT, char const * resourceID, PersistenceConfigurationKey_s const * psConfig_out) ;
 187
 188
 189 /**
 190  * \brief delete a resourceID's configuration from RCT
 191  *
 192  * \param handlerRCT    [in] handler obtained with persComRctOpen
 193  * \param resourceID    [in] resource's identifier (length limited to \ref PERS_RCT_MAX_LENGTH_RESOURCE_ID)
 194  *
 195  * \return 0 for success, or negative value for error (\ref PERS_COM_ERROR_CODES_DEFINES)
 196  */
 197 signed int persComRctDelete(signed int handlerRCT, char const * resourceID) ;
 198
 199
 200 /**
 201  * \brief Find the buffer's size needed to accomodate the listing of resourceIDs in RCT
 202  *
 203  * \param handlerRCT    [in] handler obtained with persComRctOpen
 204  *
 205  * \return needed size [byte], or negative value for error (\ref PERS_COM_ERROR_CODES_DEFINES)
 206  */
 207 signed int persComRctGetSizeResourcesList(signed int handlerRCT) ;
 208
 209
 210 /**
 211  * \brief Get the list of the resourceIDs in RCT
 212  * \note : resourceIDs in the list are separated by '\0'
 213  *
 214  * \param handlerRCT        [in] handler obtained with persComRctOpen
 215  * \param listBuffer_out    [out]buffer where to return the list of resourceIDs
 216  * \param listBufferSize    [in] size of listBuffer_out
 217  *
 218  * \return list size [byte], or negative value for error (\ref PERS_COM_ERROR_CODES_DEFINES)
 219  */
 220 signed int persComRctGetResourcesList(signed int handlerRCT, char* listBuffer_out, signed int listBufferSize) ;
 221
 222
 223 /** \} */ /* End of PERS_RCT_FUNCTIONS */
 224
 225 #ifdef __cplusplus
 226 }
 227 #endif /* extern "C" { */
 228
 229 /** \} */ /* End of PERS_COM_RCT */
 230 #endif /* OSS_PERSISTENCE_DATA_ORGANIZATION_H */