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