nsframework/framework_unified/client/include/native_service/ns_transmit_log.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 declaration of wrapper C type API's for class CNSSharedMem
  20 ///           to read and write transmit log to shared memory.
  21 ///
  22 ////////////////////////////////////////////////////////////////////////////////////////////////////
  23 //@{
  24 /**
  25  * @file ns_transmit_log.h
  26  * @brief \~english This file contains declaration of wrapper C type API for reading and writing
  27  *        transmit log 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_LOG_H__  // NOLINT  (build/header_guard)
  46 #define __NATIVESERVICES_NATIVESERVICES_INC_NATIVE_NS_SHAREDMEM_LOG_H__
  47
  48 ////////////////////////////////////////////////////////////////////////////////////////////////////
  49 // Include Files
  50 ////////////////////////////////////////////////////////////////////////////////////////////////////
  51 #include <native_service/frameworkunified_types.h>
  52
  53 #ifdef __cplusplus
  54 extern "C" {
  55 #endif
  56
  57
  58
  59 #define TRANSMIT_LOG_SHAREDMEM_NAME         "/TransmitLogShBuf"
  60 #define TRANSMIT_LOG_SHAREDMEM_SIZE         5242880         // 5MB
  61
  62 ////////////////////////////////////////////////////////////////////////////////////////////
  63 /// \ingroup NSSharedMemTransmitLogOpen
  64 /// \~english @par Brief
  65 ///           Open the shared memory for transmit logging.
  66 /// \~english @param[in]
  67 /// \~english @retval eFrameworkunifiedStatusOK if shared memory is opened.
  68 /// \~english @retval eFrameworkunifiedStatusNullPointer if memory allocation error while creating shared memory pointer.
  69 /// \~english @retval eFrameworkunifiedStatusFail if shared memory not open
  70 /// \~english @par Preconditons
  71 ///           - None
  72 /// \~english @par Change of internal status
  73 ///           - Open shared memory object
  74 /// \~english @par Conditions of processing failure
  75 ///           - Memory allocation error while creating shared memory pointer.[eFrameworkunifiedStatusNullPointer]
  76 ///           - If shared memory not open.[eFrameworkunifiedStatusFail]
  77 /// \~english @par Detail
  78 ///            Open the shared memory for transmit logging.\n
  79 ///            If shared memory is not exist,then create a shared memory,and open.
  80 /// \~english @par Classification
  81 ///           - public
  82 /// \~english @par Type
  83 ///           - sync only
  84 /// \~english @par
  85 ///           - eFrameworkunifiedStatus:Result
  86 ///               - eFrameworkunifiedStatusOK:Success
  87 ///               - Except eFrameworkunifiedStatusOK:Failure
  88 /// \~english @see NSSharedMemTransmitLogClose
  89 ////////////////////////////////////////////////////////////////////////////////////////////////
  90 EFrameworkunifiedStatus NSSharedMemTransmitLogOpen();
  91
  92 ////////////////////////////////////////////////////////////////////////////////////////////
  93 /// \ingroup NSSharedMemTransmitLogClose
  94 /// \~english @par Brief
  95 ///           Close the transmit logging shared memory
  96 /// \~english @param[in]
  97 /// \~english @retval eFrameworkunifiedStatusOK if shared memory is closed
  98 /// \~english @retval eFrameworkunifiedStatusNullPointer if shared memory pointer is NULL.
  99 /// \~english @retval eFrameworkunifiedStatusFail if shared memory was not closed.
 100 /// \~english @par Preconditons
 101 ///           - None
 102 /// \~english @par Change of internal status
 103 ///           -Open shared memory object
 104 /// \~english @par Conditions of processing failure
 105 ///           - shared memory pointer is NULL.[eFrameworkunifiedStatusNullPointer]
 106 ///           - If shared memory not close.[eFrameworkunifiedStatusFail]
 107 /// \~english @par Detail
 108 ///            Close the transmit logging shared memory.\n
 109 ///            If shared memory closed failure or shared memory don't exist,then return failure.
 110 /// \~english @par Classification
 111 ///           - public
 112 /// \~english @par Type
 113 ///           - sync only
 114 /// \~english @par
 115 ///           - eFrameworkunifiedStatus:Result
 116 ///               - eFrameworkunifiedStatusOK:Success
 117 ///               - Except eFrameworkunifiedStatusOK:Failure
 118 /// \~english @see NSSharedMemTransmitLogOpen
 119 ////////////////////////////////////////////////////////////////////////////////////////////////
 120 EFrameworkunifiedStatus NSSharedMemTransmitLogClose();
 121
 122 ////////////////////////////////////////////////////////////////////////////////////////////
 123 /// \ingroup NSSharedMemReadTransmitLog
 124 /// \~english @par Brief
 125 ///           Reads transmit log from the shared memory buffer.
 126 /// \~english @param [in] f_pBuffer
 127 ///           PSTR - pointer to the buffer in which data to be read.
 128 /// \~english @param [in] f_uiLength
 129 ///           UI_32 - length of the data to be read.
 130 /// \~english @param [in] f_bBlock
 131 ///           BOOL - TRUE -  blocking call
 132 ///                  FALSE - non blocking call
 133 /// \~english @retval Except NS_SHM_ERROR - Indicates the number of bytes read.
 134 /// \~english @retval NS_SHM_ERROR  -if shared memory is not opened.
 135 /// \~english @par Preconditons
 136 ///           -None
 137 /// \~english @par Change of internal status
 138 ///           None
 139 /// \~english @par Conditions of processing failure
 140 ///           if g_pTransmitLogSharedBuf or f_pBuffer is null.[NS_SHM_ERROR]
 141 /// \~english @par Detail
 142 ///           If this function is used as blocking call,\n
 143 ///           then the calling thread will get blocked until data is available for read.
 144 /// \~english @par Classification
 145 ///           Public
 146 /// \~english @par Type
 147 ///           sync only
 148 /// \~english @par
 149 ///           - l_iReadSize:Result
 150 ///               - NS_SHM_ERROR:Failure
 151 ///               - Except NS_SHM_ERROR:Success
 152 /// \~english @see NSSharedMemWriteTransmitLog
 153 ////////////////////////////////////////////////////////////////////////////////////////////////
 154 SI_32 NSSharedMemReadTransmitLog(PSTR f_pBuffer, const UI_32 f_uiLength, const BOOL f_bBlock);
 155
 156 ////////////////////////////////////////////////////////////////////////////////////////////
 157 /// \ingroup NSSharedMemWriteTransmitLog
 158 /// \~english @par Brief
 159 ///           Write transmit log into the shared memory buffer.
 160 /// \~english @param [in] f_pBuffer
 161 ///           PSTR - pointer to the buffer containing the data to be written.
 162 /// \~english @param [in] f_uiLength
 163 ///           UI_32 - length of the data buffer to be written.
 164 /// \~english @retval Except NS_SHM_ERROR - Indicates the number of bytes written,
 165 /// \~english @retval NS_SHM_ERROR  -if shared memory is not opened.
 166 /// \~english @par Preconditons
 167 ///           -None
 168 /// \~english @par Change of internal status
 169 ///           None
 170 /// \~english @par Conditions of processing failure
 171 ///           if g_pTransmitLogSharedBuf or f_pBuffer is null.[NS_SHM_ERROR]
 172 /// \~english @par Detail
 173 ///           If this function is used as blocking call,\n
 174 ///           then the calling thread will get blocked until data is available for write.
 175 /// \~english @par Classification
 176 ///           Public
 177 /// \~english @par Type
 178 ///           sync only
 179 /// \~english @par
 180 ///           - l_iReadSize:Result
 181 ///               - NS_SHM_ERROR:Failure
 182 ///               - Except NS_SHM_ERROR:Success
 183 /// \~english @see NSSharedMemReadTransmitLog
 184 ////////////////////////////////////////////////////////////////////////////////////////////////
 185 SI_32 NSSharedMemWriteTransmitLog(PCSTR f_pBuffer, const UI_32 f_uiLength);
 186
 187 ////////////////////////////////////////////////////////////////////////////////////////////
 188 /// \ingroup NSSharedMemDumpTransmitLogToFile
 189 /// \~english @par Brief
 190 ///           Dump the transmit logging shared memory to file
 191 /// \~english @param [in] f_pPath
 192 ///           PCSTR - full file path
 193 /// \~english @param [in] f_puiSize
 194 ///           PCSTR - Size of data dumped to file
 195 /// \~english @retval eFrameworkunifiedStatusOK if shared memory is closed
 196 /// \~english @retval eFrameworkunifiedStatusFileLoadError file path is incorrect
 197 /// \~english @retval eFrameworkunifiedStatusSemLockFail/
 198 ///                   eFrameworkunifiedStatusSemUnLockFail - mutex locking/unlocking error
 199 /// \~english @retval eFrameworkunifiedStatusFail shared memory is not open
 200 /// \~english @par Preconditons
 201 ///           - None
 202 /// \~english @par Change of internal status
 203 ///           -Open shared memory object
 204 /// \~english @par Conditions of processing failure
 205 ///           - shared memory pointer is NULL.[eFrameworkunifiedStatusNullPointer]
 206 ///           - mutex locking/unlocking error.[eFrameworkunifiedStatusSemLockFail/eFrameworkunifiedStatusSemUnLockFail]
 207 ///           - shared memory is not open.[eFrameworkunifiedStatusFail]
 208 ///           - file path is incorrect.[eFrameworkunifiedStatusFileLoadError]
 209 /// \~english @par Detail
 210 ///            Writes all the data in the buffer into provided file path.\n
 211 ///            Overwrites the file if it exists.
 212 /// \~english @par Classification
 213 ///           - public
 214 /// \~english @par Type
 215 ///           - sync only
 216 /// \~english @par
 217 ///           - eFrameworkunifiedStatus:Result
 218 ///               - eFrameworkunifiedStatusOK:Success
 219 ///               - Except eFrameworkunifiedStatusOK:Failure
 220 /// \~english @see None
 221 ////////////////////////////////////////////////////////////////////////////////////////////////
 222 EFrameworkunifiedStatus NSSharedMemDumpTransmitLogToFile(PCSTR f_pPath, PUI_32 f_puiDumpSize);
 223
 224 ////////////////////////////////////////////////////////////////////////////////////////////////
 225 /// \ingroup NSSharedMemTransmitLogIsOpen
 226 /// \~english @par Brief
 227 ///        This function is used to check whether the shared memory buffer is opened or not.
 228 /// \~english @retval TRUE - Open
 229 /// \~english @retval FALSE - Not open
 230 /// \~english @par Preconditons
 231 ///           - None
 232 /// \~english @par Change of internal status
 233 ///           - None
 234 /// \~english @par Conditions of processing failure
 235 ///           - None
 236 /// \~english @par Detail
 237 ///           - This function is used to check whether the shared memory buffer is opened or not.\n
 238 ///             Used only in nstest_sharedmem.
 239 /// \~english @par Classification
 240 ///           - public
 241 /// \~english @par Type
 242 ///         Sync only
 243 /// \~english @see none
 244 ////////////////////////////////////////////////////////////////////////////////////////////////
 245 BOOL NSSharedMemTransmitLogIsOpen();
 246
 247 #ifdef __cplusplus
 248 }
 249 #endif
 250
 251 #endif /* __NATIVESERVICES_NATIVESERVICES_INC_NATIVE_NS_SHAREDMEM_LOG_H__ */  // NOLINT  (build/header_guard)
 252 /** @}*/
 253 /** @}*/
 254 /** @}*/
 255 /** @}*/
 256 //@}