2 * @copyright Copyright (c) 2016-2020 TOYOTA MOTOR CORPORATION.
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
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.
22 ////////////////////////////////////////////////////////////////////////////////////////////////////
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.
30 /** @addtogroup BaseSystem
33 /** @addtogroup native_service
37 /** @addtogroup framework_unified
38 * @ingroup native_service
41 /** @addtogroup native
42 * @ingroup framework_unified
45 #ifndef __NATIVESERVICES_NATIVESERVICES_INC_NATIVE_NS_SHAREDMEM_LOG_H__ // NOLINT (build/header_guard)
46 #define __NATIVESERVICES_NATIVESERVICES_INC_NATIVE_NS_SHAREDMEM_LOG_H__
48 ////////////////////////////////////////////////////////////////////////////////////////////////////
50 ////////////////////////////////////////////////////////////////////////////////////////////////////
51 #include <native_service/frameworkunified_types.h>
59 #define TRANSMIT_LOG_SHAREDMEM_NAME "/TransmitLogShBuf"
60 #define TRANSMIT_LOG_SHAREDMEM_SIZE 5242880 // 5MB
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
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
82 /// \~english @par Type
85 /// - eFrameworkunifiedStatus:Result
86 /// - eFrameworkunifiedStatusOK:Success
87 /// - Except eFrameworkunifiedStatusOK:Failure
88 /// \~english @see NSSharedMemTransmitLogClose
89 ////////////////////////////////////////////////////////////////////////////////////////////////
90 EFrameworkunifiedStatus NSSharedMemTransmitLogOpen();
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
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
112 /// \~english @par Type
115 /// - eFrameworkunifiedStatus:Result
116 /// - eFrameworkunifiedStatusOK:Success
117 /// - Except eFrameworkunifiedStatusOK:Failure
118 /// \~english @see NSSharedMemTransmitLogOpen
119 ////////////////////////////////////////////////////////////////////////////////////////////////
120 EFrameworkunifiedStatus NSSharedMemTransmitLogClose();
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
137 /// \~english @par Change of internal status
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
146 /// \~english @par Type
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);
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
168 /// \~english @par Change of internal status
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
177 /// \~english @par Type
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);
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
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
214 /// \~english @par Type
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);
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
232 /// \~english @par Change of internal status
234 /// \~english @par Conditions of processing failure
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
241 /// \~english @par Type
243 /// \~english @see none
244 ////////////////////////////////////////////////////////////////////////////////////////////////
245 BOOL NSSharedMemTransmitLogIsOpen();
251 #endif /* __NATIVESERVICES_NATIVESERVICES_INC_NATIVE_NS_SHAREDMEM_LOG_H__ */ // NOLINT (build/header_guard)