nsframework/framework_unified/client/include/native_service/ns_sharedmem_writer.h

   1 /*
   2  * @copyright Copyright (c) 2016-2020 TOYOTA MOTOR CORPORATION.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 ////////////////////////////////////////////////////////////////////////////////////////////////////
  18 /// \ingroup  tag_NSSharedMemory
  19 /// \brief    This file contains implementation of class CNSSharedMemWriter.
  20 ///           This class provides API to open, close and perform write operation on shared memory.
  21 ///
  22 ////////////////////////////////////////////////////////////////////////////////////////////////////
  23 //@{
  24 /**
  25  * @file ns_sharedmem_writer.h
  26  * @brief \~english This file contains implementation of class CNSSharedMemWriter.
  27  *        This class provides API to open, close and perform write operation on shared memory.
  28  *
  29  */
  30 /** @addtogroup BaseSystem
  31  *  @{
  32  */
  33 /** @addtogroup native_service
  34  *  @ingroup BaseSystem
  35  *  @{
  36  */
  37 /** @addtogroup framework_unified
  38  *  @ingroup native_service
  39  *  @{
  40  */
  41 /** @addtogroup native
  42  *  @ingroup framework_unified
  43  *  @{
  44  */
  45 #ifndef __NATIVESERVICES_NATIVESERVICES_INC_NATIVE_NS_SHAREDMEM_WRITER_H__  // NOLINT  (build/header_guard)
  46 #define __NATIVESERVICES_NATIVESERVICES_INC_NATIVE_NS_SHAREDMEM_WRITER_H__
  47
  48 ////////////////////////////////////////////////////////////////////////////////////////////////////
  49 // Include Files
  50 ////////////////////////////////////////////////////////////////////////////////////////////////////
  51 #include <native_service/frameworkunified_types.h>
  52 #include <string>
  53
  54 class CNSSharedMem;
  55
  56 /**
  57  * @class CNSSharedMemWriter
  58  * \~english @brief write shared memory
  59  * \~english @par   Brief Introduction
  60  *        This class is used for write shared memory.
  61  *
  62  */
  63 class CNSSharedMemWriter {
  64  public:
  65   ////////////////////////////////////////////////////////////////////////////////////////////////
  66   /// \ingroup CNSSharedMemWriter
  67   /// \~english @par Brief
  68   ///        Constructor for CNSSharedMemWriter
  69   /// \~english @param[in] f_cSharedMemName
  70   ///        const std::string& - name of the shared memory
  71   /// \~english @param[in]  f_uiSize
  72   ///         UI_32 - size of shared memory
  73   /// \~english @retval None
  74   /// \~english @par Preconditons
  75   ///           -None
  76   /// \~english @par Change of internal status
  77   ///           - None
  78   /// \~english @par Conditions of processing failure
  79   ///           - None
  80   /// \~english @par Detail
  81   ///           Create object of CNSSharedMemWriter class.
  82   ///           This class don't used to open shared memory object or allocate memory.
  83   /// \~english @par Classification
  84   ///           - public
  85   /// \~english @par Type
  86   ///           - sync only
  87   /// \~english @see ~CNSSharedMemWriter
  88   ////////////////////////////////////////////////////////////////////////////////////////////////
  89   CNSSharedMemWriter(const std::string &f_cSharedMemName, const UI_32 f_uiSize);
  90
  91   ////////////////////////////////////////////////////////////////////////////////////////////////
  92   /// \ingroup CNSSharedMemWriter
  93   /// \~english @par Brief
  94   ///        Destructor of CNSSharedMemWriter class.
  95   /// \~english @param None
  96   /// \~english @retval none
  97   /// \~english @par Preconditons
  98   ///           - None
  99   /// \~english @par Change of internal status
 100   ///           - Change the state of shared memory to closed state
 101   /// \~english @par Conditions of processing failure
 102   ///           -None
 103   /// \~english @par Detail
 104   ///      Closes the shared memory, if it is open.
 105   /// \~english @par
 106   ///         Please note the following points when using this API for application.
 107   ///         - Since the destructor does not delete the shared memory area, \n
 108   ///           the application must execute shm_unlink to delete the shared memory area.
 109   /// \~english @par Classification
 110   ///           - Public
 111   /// \~english @par Type
 112   ///           - sync only
 113   /// \~english @see CNSSharedMemWriter(const std::string&, const BOOL), CNSSharedMemWriter(), Close
 114   ////////////////////////////////////////////////////////////////////////////////////////////////
 115   ~CNSSharedMemWriter();
 116
 117   ////////////////////////////////////////////////////////////////////////////////////////////////
 118   /// \ingroup CNSSharedMemWriter
 119   /// \~english @par Brief
 120   ///        This function opens and maps the shared memory object.
 121   /// \~english @param None
 122   /// \~english @retval eFrameworkunifiedStatusOK if shared memory opened successfully
 123   /// \~english @retval eFrameworkunifiedStatusNullPointer pointer of the CNSSharedMem object is NULL
 124   /// \~english @retval eFrameworkunifiedStatusFail unable to open shared memory
 125   /// \~english @par Preconditons
 126   ///           - None
 127   /// \~english @par Change of internal status
 128   ///           - Open shared memory object
 129   /// \~english @par Conditions of processing failure
 130   ///           - pointer of the CNSSharedMem object is NULL.[eFrameworkunifiedStatusNullPointer]
 131   ///           - unable to open shared memory.[eFrameworkunifiedStatusFail]
 132   /// \~english @par Detail
 133   ///            This function opens and maps the shared memory object.\n
 134   ///            It creates the shared memory if it does not exists.
 135   /// \~english @par Classification
 136   ///           - public
 137   /// \~english @par Type
 138   ///           - sync only
 139   /// \~english @par
 140   ///           - eFrameworkunifiedStatus:Result
 141   ///               - eFrameworkunifiedStatusOK:Success
 142   ///               - Except eFrameworkunifiedStatusOK:Failure
 143   /// \~english @see Close
 144   ////////////////////////////////////////////////////////////////////////////////////////////////
 145   EFrameworkunifiedStatus Open();
 146
 147   ////////////////////////////////////////////////////////////////////////////////////////////////
 148   /// \ingroup CNSSharedMemWriter
 149   /// \~english @par Brief
 150   ///        This function is used to check whether the shared memory buffer is opened or not.
 151   /// \~english @retval TRUE - Open
 152   /// \~english @retval FALSE - Not open
 153   /// \~english @par Preconditons
 154   ///           - None
 155   /// \~english @par Change of internal status
 156   ///           - None
 157   /// \~english @par Conditions of processing failure
 158   ///           - None
 159   /// \~english @par Detail
 160   ///           - Check whether the shared memory buffer is opened or not, and return the result.
 161   /// \~english @par Classification
 162   ///           - public
 163   /// \~english @par Type
 164   ///           - Sync only
 165   /// \~english @see none
 166   ////////////////////////////////////////////////////////////////////////////////////////////////
 167   BOOL IsOpen();
 168
 169   ////////////////////////////////////////////////////////////////////////////////////////////////
 170   /// \ingroup CNSSharedMemWriter
 171   /// \~english @par Brief
 172   ///           This function unmaps the shared memory object.
 173   /// \~english @retval eFrameworkunifiedStatusOK if shared memory closed successfully
 174   /// \~english @retval eFrameworkunifiedStatusNullPointer pointer of the CNSSharedMem object is NULL
 175   /// \~english @retval eFrameworkunifiedStatusFail if shared memory is not open
 176   /// \~english @par Preconditons
 177   ///           - None
 178   /// \~english @par Change of internal status
 179   ///           - Close the shared memory object
 180   /// \~english @par Conditions of processing failure
 181   ///           - Pointer of the CNSSharedMem object is NULL.[eFrameworkunifiedStatusNullPointer]
 182   ///           - If shared memory is not open.[eFrameworkunifiedStatusFail]
 183   /// \~english @par Detail
 184   ///           - This function unmaps the shared memory object.\n
 185   ///             If pointer of the CNSSharedMem object is NULL, will return eFrameworkunifiedStatusNullPointer.
 186   /// \~english @par Classification
 187   ///           - Public
 188   /// \~english @par Type
 189   ///           - Sync only
 190   /// \~english @par
 191   ///           - eFrameworkunifiedStatus:Result
 192   ///               - eFrameworkunifiedStatusOK:Success
 193   ///               - Except eFrameworkunifiedStatusOK:Failure
 194   /// \~english @see Open
 195   ////////////////////////////////////////////////////////////////////////////////////////////////
 196   EFrameworkunifiedStatus Close();
 197
 198   ////////////////////////////////////////////////////////////////////////////////////////////////
 199   /// \ingroup CNSSharedMemWriter
 200   /// \~english @par Brief
 201   ///        This function writes the data into the shared memory.
 202   /// \~english @param[in] buffer
 203   ///        PSTR - pointer to the buffer containing the data to be written
 204   /// \~english @param[in] f_uilength
 205   ///        const UI_32 - length of the data buffer to be written
 206   /// \~english @retval The number of bytes written
 207   /// \~english @retval NS_SHM_ERROR if an error occurred
 208   /// \~english @par Preconditons
 209   ///        - Open the shared memory object
 210   /// \~english @par Change of internal status
 211   ///        - shared memory is changed.
 212   /// \~english @par Conditions of processing failure
 213   ///        - m_pShmWriter is NULL.
 214   ///        - buffer is NULL.
 215   ///        - f_uilength is 0.
 216   /// \~english @par Detail
 217   ///        - This function writes the buffer's data whose length is f_uilength to shared memory.\n
 218   ///          If successed,return write size,else return NS_SHM_ERROR.
 219   /// \~english @par Classification
 220   ///        - Public
 221   /// \~english @par Type
 222   ///         Sync only
 223   /// \~english @par
 224   ///           - l_iWriteSize:Result
 225   ///               - NS_SHM_ERROR:Failure
 226   ///               - Except NS_SHM_ERROR:Success
 227   /// \~english @see None
 228   ////////////////////////////////////////////////////////////////////////////////////////////////
 229   SI_32 Write(PCSTR buffer, const UI_32 f_uilength);
 230
 231   ////////////////////////////////////////////////////////////////////////////////////////////////
 232   /// \ingroup CNSSharedMemWriter
 233   /// \~english @par Brief
 234   ///           This function clears the shared memory buffer.
 235   /// \~english @retval eFrameworkunifiedStatusOK if shared memory cleared successfully
 236   /// \~english @retval eFrameworkunifiedStatusNullPointer pointer of the CNSSharedMem object is NULL
 237   /// \~english @retval eFrameworkunifiedStatusFail if shared memory is not open
 238   /// \~english @par Preconditons
 239   ///           - None
 240   /// \~english @par Change of internal status
 241   ///           - shared memory is changed.
 242   /// \~english @par Conditions of processing failure
 243   ///           - Pointer of the CNSSharedMem object is NULL.[eFrameworkunifiedStatusNullPointer]
 244   ///           - If shared memory is not open.[eFrameworkunifiedStatusFail]
 245   /// \~english @par Detail
 246   ///           - This function clears the shared memory buffer.\n
 247   ///             If pointer of the CNSSharedMem object is NULL, will return eFrameworkunifiedStatusNullPointer.
 248   /// \~english @par Classification
 249   ///           - Public
 250   /// \~english @par Type
 251   ///           - Sync only
 252   /// \~english @par
 253   ///           - eFrameworkunifiedStatus:Result
 254   ///               - eFrameworkunifiedStatusOK:Success
 255   ///               - Except eFrameworkunifiedStatusOK:Failure
 256   /// \~english @see None
 257   ////////////////////////////////////////////////////////////////////////////////////////////////
 258   EFrameworkunifiedStatus ClearBuf();
 259
 260  protected:
 261   // no members in protected
 262
 263  private:
 264   ////////////////////////////////////////////////////////////////////////////////////////////////
 265   /// CNSSharedMemWriter
 266   /// Constructor of CNSSharedMemWriter class
 267   ///
 268   /// \param
 269   ///
 270   /// \return     None
 271   ///
 272   ////////////////////////////////////////////////////////////////////////////////////////////////
 273   CNSSharedMemWriter();
 274
 275   CNSSharedMem *m_pShmWriter;   // pointer to the CNSSharedMem object
 276 };
 277
 278 #endif  /*__NATIVESERVICES_NATIVESERVICES_INC_NATIVE_NS_SHAREDMEM_WRITER_H__*/  // NOLINT  (build/header_guard)
 279 /** @}*/
 280 /** @}*/
 281 /** @}*/
 282 /** @}*/
 283 //@}