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 implementation of class CNSSharedMemReader.
20 /// This class provides API to open, close and perform read operation on shared memory.
22 ////////////////////////////////////////////////////////////////////////////////////////////////////
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.
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_READER_H__ // NOLINT (build/header_guard)
46 #define __NATIVESERVICES_NATIVESERVICES_INC_NATIVE_NS_SHAREDMEM_READER_H__
48 ////////////////////////////////////////////////////////////////////////////////////////////////////
50 ////////////////////////////////////////////////////////////////////////////////////////////////////
51 #include <native_service/frameworkunified_types.h>
57 * @class CNSSharedMemReader
58 * \~english @brief read shared memory
59 * \~english @par Brief Introduction
60 * This class is used for read shared memory.
63 class CNSSharedMemReader {
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
78 /// \~english @par Change of internal status
80 /// \~english @par Conditions of processing failure
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
87 /// \~english @par Type
89 /// \~english @see ~CNSSharedMemReader
90 ////////////////////////////////////////////////////////////////////////////////////////////////
91 CNSSharedMemReader(const std::string &f_cSharedMemName, const BOOL f_bBlock = TRUE); // NOLINT (readability/nolint)
93 ////////////////////////////////////////////////////////////////////////////////////////////////
94 /// \ingroup CNSSharedMemReader
95 /// \~english @par Brief
96 /// Destructor for CNSSharedMemReader.
97 /// \~english @param None
98 /// \~english @retval none
99 /// \~english @par Preconditons
101 /// \~english @par Change of internal status
102 /// - Change the state of shared memory to closed state
103 /// \~english @par Conditions of processing failure
105 /// \~english @par Detail
106 /// Closes the shared memory, if it is open.
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
113 /// \~english @par Type
115 /// \~english @see CNSSharedMemReader(const std::string&, const BOOL), CNSSharedMemReader(), Close
116 ////////////////////////////////////////////////////////////////////////////////////////////////
117 ~CNSSharedMemReader();
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
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
139 /// \~english @par Type
141 /// \~english @see Close
142 ////////////////////////////////////////////////////////////////////////////////////////////////
143 EFrameworkunifiedStatus Open();
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
153 /// \~english @par Change of internal status
155 /// \~english @par Conditions of processing failure
157 /// \~english @par Detail
158 /// - Check whether the shared memory buffer is opened or not, and return the result.
159 /// \~english @par Classification
161 /// \~english @par Type
163 /// \~english @see none
164 ////////////////////////////////////////////////////////////////////////////////////////////////
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.
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
188 /// \~english @par Type
190 /// \~english @see Open
191 ////////////////////////
192 ////////////////////////////////////////////////////////////////////////////////////////////////
193 EFrameworkunifiedStatus Close();
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
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
217 /// \~english @par Type
219 /// \~english @see Write
220 ////////////////////////////////////////////////////////////////////////////////////////////////
221 SI_32 Read(PSTR buffer, const UI_32 f_uilength);
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
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.
254 /// This function overwrites the file if it exists.
255 /// \~english @par Classification
257 /// \~english @par Type
259 /// \~english @see Open
260 ////////////////////////////////////////////////////////////////////////////////////////////////
261 EFrameworkunifiedStatus DumpToFile(PCSTR f_pPath, PUI_32 f_uiDumpSize);
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
272 /// \~english @par Change of internal status
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
280 /// \~english @par Type
283 /// - l_uiReadSize:Result
284 /// - NS_SHM_ERROR:Failure
285 /// - Except NS_SHM_ERROR:Success
286 /// \~english @see None
287 ////////////////////////////////////////////////////////////////////////////////////////////////
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
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
311 /// \~english @par Type
313 /// \~english @see Open
314 ////////////////////////////////////////////////////////////////////////////////////////////////
315 EFrameworkunifiedStatus SetReadPtrToWritePtr();
318 // no members in protected
321 ////////////////////////////////////////////////////////////////////////////////////////////////
322 /// CNSSharedMemReader
323 /// Constructor of CNSSharedMemReader class
327 ////////////////////////////////////////////////////////////////////////////////////////////////
328 CNSSharedMemReader();
330 CNSSharedMem *m_pShmReader; // pointer to the CNSSharedMem object
332 BOOL m_bBlock; // blocking or non blocking read
335 #endif /*__NATIVESERVICES_NATIVESERVICES_INC_NATIVE_NS_SHAREDMEM_READER_H__*/ // NOLINT (build/header_guard)