video_in_hal/nsframework/framework_unified/client/include/native_service/ns_sharedmem_reader.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 CNSSharedMemReader.
  20 ///           This class provides API to open, close and perform read operation on shared memory.
  21 ///
  22 ////////////////////////////////////////////////////////////////////////////////////////////////////
  23 //@{
  24 /**
  25  * @file ns_sharedmem_reader.h
  26  * @brief \~english This file contains implementation of class CNSSharedMemReader.
  27  *        This class provides API to open, close and perform read 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_READER_H__  // NOLINT  (build/header_guard)
  46 #define __NATIVESERVICES_NATIVESERVICES_INC_NATIVE_NS_SHAREDMEM_READER_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 CNSSharedMemReader
  58  * \~english @brief read shared memory
  59  * \~english @par   Brief Introduction
  60  *        This class is used for read shared memory.
  61  *
  62  */
  63 class CNSSharedMemReader {
  64  public:
  65   ////////////////////////////////////////////////////////////////////////////////////////////////
  66   /// \ingroup CNSSharedMemReader
  67   /// \~english @par Brief
  68   ///        Constructor for CNSSharedMemReader
  69   /// \~english @param[in] f_cSharedMemName
  70   ///        const std::string& - name of the shared memory
  71   /// \~english @param[in]  f_bBlock
  72   ///         BOOL - TRUE -  blocking call for Read() API,Thread will get blocked \n
  73   ///                        the thread until data is available for read.
  74   ///                FALSE - non blocking call for Read() API
  75   /// \~english @retval None
  76   /// \~english @par Preconditons
  77   ///           -None
  78   /// \~english @par Change of internal status
  79   ///           - None
  80   /// \~english @par Conditions of processing failure
  81   ///           - None
  82   /// \~english @par Detail
  83   ///           Create object of CNSSharedMemReader class.
  84   ///           This class don't used to open shared memory object or allocate memory.
  85   /// \~english @par Classification
  86   ///           - public
  87   /// \~english @par Type
  88   ///           - None
  89   /// \~english @see ~CNSSharedMemReader
  90   ////////////////////////////////////////////////////////////////////////////////////////////////
  91   CNSSharedMemReader(const std::string &f_cSharedMemName, const BOOL f_bBlock = TRUE);  // NOLINT  (readability/nolint)
  92
  93   ////////////////////////////////////////////////////////////////////////////////////////////////
  94   /// \ingroup CNSSharedMemReader
  95   /// \~english @par Brief
  96   ///        Destructor for CNSSharedMemReader.
  97   /// \~english @param None
  98   /// \~english @retval none
  99   /// \~english @par Preconditons
 100   ///           - None
 101   /// \~english @par Change of internal status
 102   ///           - Change the state of shared memory to closed state
 103   /// \~english @par Conditions of processing failure
 104   ///           -None
 105   /// \~english @par Detail
 106   ///       Closes the shared memory, if it is open.
 107   /// \~english @par
 108   ///         Please note the following points when using this API for application.
 109   ///         - Since the destructor does not delete the shared memory area, \n
 110   ///           the application must execute shm_unlink to delete the shared memory area.
 111   /// \~english @par Classification
 112   ///           - Public
 113   /// \~english @par Type
 114   ///           -None
 115   /// \~english @see CNSSharedMemReader(const std::string&, const BOOL), CNSSharedMemReader(), Close
 116   ////////////////////////////////////////////////////////////////////////////////////////////////
 117   ~CNSSharedMemReader();
 118
 119   ////////////////////////////////////////////////////////////////////////////////////////////////
 120   /// \ingroup CNSSharedMemReader
 121   /// \~english @par Brief
 122   ///        This function opens and maps the shared memory object.
 123   /// \~english @retval eFrameworkunifiedStatusOK if shared memory opened successfully
 124   /// \~english @retval eFrameworkunifiedStatusFail unable to open shared memory
 125   /// \~english @retval eFrameworkunifiedStatusErrOther if shared memory already opened
 126   /// \~english @par Preconditons
 127   ///         None
 128   /// \~english @par Change of internal status
 129   ///         - Open shared memory object
 130   /// \~english @par Conditions of processing failure
 131   ///         - if shared memory already opened [eFrameworkunifiedStatusErrOther]
 132   ///         - Unable to open shared memory(shm_open) [eFrameworkunifiedStatusFail]
 133   ///         - Unable to create shared memory(mmap) [eFrameworkunifiedStatusFail]
 134   /// \~english @par Detail
 135   ///         Opens a shared memory object and allocates it to a memory space.\n
 136   ///         It creates the shared memory if it does not exists.
 137   /// \~english @par Classification
 138   ///         Public
 139   /// \~english @par Type
 140   ///         Open Close
 141   /// \~english @see Close
 142   ////////////////////////////////////////////////////////////////////////////////////////////////
 143   EFrameworkunifiedStatus Open();
 144
 145   ////////////////////////////////////////////////////////////////////////////////////////////////
 146   /// \ingroup CNSSharedMemReader
 147   /// \~english @par Brief
 148   ///        This function is used to check whether the shared memory buffer is opened or not.
 149   /// \~english @retval TRUE - Open
 150   /// \~english @retval FALSE - Not open
 151   /// \~english @par Preconditons
 152   ///         - None
 153   /// \~english @par Change of internal status
 154   ///         - None
 155   /// \~english @par Conditions of processing failure
 156   ///         - None
 157   /// \~english @par Detail
 158   ///         - Check whether the shared memory buffer is opened or not, and return the result.
 159   /// \~english @par Classification
 160   ///         public
 161   /// \~english @par Type
 162   ///         Open Close
 163   /// \~english @see none
 164   ////////////////////////////////////////////////////////////////////////////////////////////////
 165   BOOL IsOpen();
 166
 167   ////////////////////////////////////////////////////////////////////////////////////////////////
 168   /// \ingroup CNSSharedMemReader
 169   /// \~english @par Brief
 170   ///        This function unmaps the shared memory object.
 171   /// \~english @retval eFrameworkunifiedStatusOK if shared memory closed successfully
 172   /// \~english @retval eFrameworkunifiedStatusFail if shared memory is not opened
 173   /// \~english @par Preconditons
 174   ///         - Open the shared memory object
 175   /// \~english @par Change of internal status
 176   ///         - Close the shared memory object
 177   /// \~english @par Conditions of processing failure
 178   ///         - The shared memory object is not opened. [eFrameworkunifiedStatusFail]
 179   ///         - Unable to unmap(munmap) the shared memory object [eFrameworkunifiedStatusFail]
 180   /// \~english @par Detail
 181   ///         - This function unmaps the shared memory object from memory space.
 182   /// \~english @par
 183   ///         Please note the following points when using this API for application.
 184   ///         - Since the closing does not delete the shared memory area, \n
 185   ///           the application must execute shm_unlink to delete the shared memory area.
 186   /// \~english @par Classification
 187   ///         public
 188   /// \~english @par Type
 189   ///         Open Close
 190   /// \~english @see Open
 191   ////////////////////////
 192   ////////////////////////////////////////////////////////////////////////////////////////////////
 193   EFrameworkunifiedStatus Close();
 194
 195   ////////////////////////////////////////////////////////////////////////////////////////////////
 196   /// \ingroup CNSSharedMemReader
 197   /// \~english @par Brief
 198   ///        This function reads data from the shared memory.
 199   /// \~english @param[in] buffer
 200   ///        PSTR - pointer to the buffer in which the read data is stored
 201   /// \~english @param[in] f_uilength
 202   ///        const UI_32 - length of the data buffer provided
 203   /// \~english @retval The number of bytes actually read, or NS_SHM_ERROR if an error occurred
 204   /// \~english @par Preconditons
 205   ///        - Open the shared memory object
 206   /// \~english @par Change of internal status
 207   ///        - None
 208   /// \~english @par Conditions of processing failure
 209   ///         - The shared memory object is not opened. [NS_SHM_ERROR]
 210   ///         - Pointor to buffer(buffer) is NULL. [NS_SHM_ERROR]
 211   ///         - Byte of data(f_uilength)is 0. [NS_SHM_ERROR]
 212   /// \~english @par Detail
 213   ///       If this constructor is used as blocking call, then the calling thread will get blocked\n
 214   ///       until data is available for read.
 215   /// \~english @par Classification
 216   ///         public
 217   /// \~english @par Type
 218   ///         Open Close
 219   /// \~english @see Write
 220   ////////////////////////////////////////////////////////////////////////////////////////////////
 221   SI_32 Read(PSTR buffer, const UI_32 f_uilength);
 222
 223   ////////////////////////////////////////////////////////////////////////////////////////////////
 224   /// \ingroup CNSSharedMemReader
 225   /// \~english @par Brief
 226   ///        This function writes all the data in the buffer into provided file f_pPath.
 227   /// \~english @param[in] f_pPath
 228   ///        PCSTR - file path.
 229   /// \~english @param[in] f_uiDumpSize
 230   ///        PUI_32 - Returns The number of bytes written into file
 231   /// \~english @retval eFrameworkunifiedStatusOK - on success
 232   /// \~english @retval eFrameworkunifiedStatusNullPointer
 233   /// \~english @retval eFrameworkunifiedStatusInvldParam - invalid param
 234   /// \~english @retval eFrameworkunifiedStatusFail - shared memory is not open
 235   /// \~english @retval eFrameworkunifiedStatusFileLoadError - file path is incorrect
 236   /// \~english @retval eFrameworkunifiedStatusErrOther
 237   /// \~english @retval eFrameworkunifiedStatusSemUnlockFail
 238   /// \~english @par Preconditons
 239   ///        - File is opened.
 240   /// \~english @par Change of internal status
 241   ///        - None
 242   /// \~english @par Conditions of processing failure
 243   ///       - Pointor to dump size(f_uiDumpSize)is NULL [eFrameworkunifiedStatusNullPointer]
 244   ///       - Dump file path is NULL [eFrameworkunifiedStatusInvldParam]
 245   ///       - File is not opened [eFrameworkunifiedStatusFail]
 246   ///       - Failed to open dump file [eFrameworkunifiedStatusFileLoadError]
 247   ///       - Failed to access shared memory [eFrameworkunifiedStatusFail]
 248   ///       - Failed to write data into dump file [eFrameworkunifiedStatusErrOther]
 249   ///       - Failed to lock mutex [eFrameworkunifiedStatusSemLockFail]
 250   ///       - Failed to unlock mutex [eFrameworkunifiedStatusSemUnlockFail]
 251   /// \~english @par Detail
 252   ///       This function does not changes the unread buffer.
 253   /// \~english @par
 254   ///       This function overwrites the file if it exists.
 255   /// \~english @par Classification
 256   ///       public
 257   /// \~english @par Type
 258   ///       none
 259   /// \~english @see Open
 260   ////////////////////////////////////////////////////////////////////////////////////////////////
 261   EFrameworkunifiedStatus DumpToFile(PCSTR f_pPath, PUI_32 f_uiDumpSize);
 262
 263   ////////////////////////////////////////////////////////////////////////////////////////////////
 264   /// \ingroup CNSSharedMemReader
 265   /// \~english @par Brief
 266   ///        This function gets size of unread .bytes.
 267   /// \~english @param None
 268   /// \~english @retval Except NS_SHM_ERROR - Returns The number of bytes written,
 269   /// \~english @retval NS_SHM_ERROR  -if an error occurred
 270   /// \~english @par Preconditons
 271   ///           -
 272   /// \~english @par Change of internal status
 273   ///           None
 274   /// \~english @par Conditions of processing failure
 275   ///           if m_pShmHdr is null.[NS_SHM_ERROR]
 276   /// \~english @par Detail
 277   ///           This function returns the number of unread bytes which can be read by Read().
 278   /// \~english @par Classification
 279   ///           Public
 280   /// \~english @par Type
 281   ///           sync only
 282   /// \~english @par
 283   ///           - l_uiReadSize:Result
 284   ///               - NS_SHM_ERROR:Failure
 285   ///               - Except NS_SHM_ERROR:Success
 286   /// \~english @see None
 287   ////////////////////////////////////////////////////////////////////////////////////////////////
 288   SI_32 GetSize();
 289
 290   ////////////////////////////////////////////////////////////////////////////////////////////////
 291   /// \ingroup CNSSharedMemReader
 292   /// \~english @par Brief
 293   ///        This function sets the position of read ptr to write ptr in buffer.
 294   /// \~english @retval eFrameworkunifiedStatusOK - on success
 295   /// \~english @retval eFrameworkunifiedStatusFail - shared memory is not open
 296   /// \~english @retval eFrameworkunifiedStatusSemLockFail - mutex locking error
 297   /// \~english @retval eFrameworkunifiedStatusSemUnlockFail - mutex unlocking error
 298   /// \~english @par Preconditons
 299   ///        - File is opened.
 300   /// \~english @par Change of internal status
 301   ///        - None
 302   /// \~english @par Conditions of processing failure
 303   ///        - File is not opened [eFrameworkunifiedStatusFail]
 304   ///        - Failed to lock mutex [eFrameworkunifiedStatusSemLockFail]
 305   ///        - Failed to unlock mutex [eFrameworkunifiedStatusSemUnlockFail]
 306   /// \~english @par Detail
 307   ///           - Set the position of read ptr to write ptr in buffer.\n
 308   ///           - Initialize state of unreading bytes to 0.
 309   /// \~english @par Classification
 310   ///           - public
 311   /// \~english @par Type
 312   ///         Open Close
 313   /// \~english @see Open
 314   ////////////////////////////////////////////////////////////////////////////////////////////////
 315   EFrameworkunifiedStatus SetReadPtrToWritePtr();
 316
 317  protected:
 318   // no members in protected
 319
 320  private:
 321   ////////////////////////////////////////////////////////////////////////////////////////////////
 322   /// CNSSharedMemReader
 323   /// Constructor of CNSSharedMemReader class
 324   ///
 325   /// \return     None
 326   ///
 327   ////////////////////////////////////////////////////////////////////////////////////////////////
 328   CNSSharedMemReader();
 329
 330   CNSSharedMem *m_pShmReader;  // pointer to the CNSSharedMem object
 331
 332   BOOL m_bBlock;              // blocking or non blocking read
 333 };
 334
 335 #endif  /*__NATIVESERVICES_NATIVESERVICES_INC_NATIVE_NS_SHAREDMEM_READER_H__*/  // NOLINT  (build/header_guard)
 336 /** @}*/
 337 /** @}*/
 338 /** @}*/
 339 /** @}*/
 340 //@}