3 * @copyright Copyright (c) 2016-2020 TOYOTA MOTOR CORPORATION.
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
9 * http://www.apache.org/licenses/LICENSE-2.0
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
18 ///////////////////////////////////////////////////////////////////////////////
19 /// \ingroup tag_NativeService
20 /// \brief This file contains the class declaration for synchronization
23 ///////////////////////////////////////////////////////////////////////////////
26 * @file frameworkunified_framework_sync.h
27 * @brief \~english This file contains the class declaration for synchronization
30 /** @addtogroup BaseSystem
33 /** @addtogroup native_service
37 /** @addtogroup framework_unified
38 * @ingroup native_service
41 /** @addtogroup framework
42 * @ingroup native_service
45 #ifndef __FRAMEWORKUNIFIED_NATIVESERVICES_NATIVESERVICES_INC_FRAMEWORK_FRAMEWORKUNIFIED_FRAMEWORK_SYNC_H__ // NOLINT (build/header_guard)
46 #define __FRAMEWORKUNIFIED_NATIVESERVICES_NATIVESERVICES_INC_FRAMEWORK_FRAMEWORKUNIFIED_FRAMEWORK_SYNC_H__
49 #include <native_service/frameworkunified_framework_types.h>
54 struct SFrameworkunifiedSyncDataPacket;
56 // Map containing the synchronization data as per the notification
57 typedef std::map<std::string, SFrameworkunifiedSyncDataPacket *> TSyncDataPacketList;
59 // Iterator to the map containing the synchronization data as per the notification
60 typedef TSyncDataPacketList::iterator TSyncDataPacketItr;
63 * @class CFrameworkunifiedSyncData
64 * \~english @brief this file has the CFrameworkunifiedSyncData class definitions
65 * \~english @par Brief Introduction
66 * - This class provids some functions to handle the synchronization data as per the notification.
69 class CFrameworkunifiedSyncData {
71 ///////////////////////////////////////////////////////////////////////////////////////////
72 /// \ingroup CFrameworkunifiedSyncData
73 /// \~english @par Brief
74 /// - This function is used to get the singleton instance of class.
75 /// \~english @param None
76 /// \~english @retval CFrameworkunifiedSyncData - singleton instance of class
77 /// \~english @par Preconditons
79 /// \~english @par Change of internal status
81 /// \~english @par Conditions of processing failure
83 /// \~english @par Detail
84 /// - If m_psSyncData is NULL,will create a new object,otherwise, will return m_psSyncData.
85 /// \~english @par Classification
87 /// \~english @see CFrameworkunifiedSyncData::CFrameworkunifiedSyncData
88 ///////////////////////////////////////////////////////////////////////////////////////////
89 static CFrameworkunifiedSyncData *FrameworkunifiedGetSyncDataInstance();
91 ///////////////////////////////////////////////////////////////////////////////////////////
92 /// \ingroup CFrameworkunifiedSyncData
93 /// \~english @par Brief
94 /// - This function is used to release the instance of class.
95 /// \~english @param None
96 /// \~english @retval eFrameworkunifiedStatusOK - success
97 /// \~english @retval except eFrameworkunifiedStatusOK - failure
98 /// \~english @par Preconditons
100 /// \~english @par Change of internal status
102 /// \~english @par Conditions of processing failure
103 /// - system function error.[Not eFrameworkunifiedStatusOK]
104 /// \~english @par Detail
105 /// - If m_psSyncData is NULL,return success,otherwise, will delete m_psSyncData.
106 /// \~english @par Classification
109 /// - eFrameworkunifiedStatus:Result
110 /// - eFrameworkunifiedStatusOK:Success
111 /// - Except eFrameworkunifiedStatusOK:Failure
112 /// \~english @see CFrameworkunifiedSyncData::CFrameworkunifiedSyncData
113 ///////////////////////////////////////////////////////////////////////////////////////////
114 static EFrameworkunifiedStatus FrameworkunifiedReleaseSyncDataInstance();
116 ///////////////////////////////////////////////////////////////////////////////////////////
117 /// \ingroup CFrameworkunifiedSyncData
118 /// \~english @par Brief
119 /// - This method is used by the application to start the notification synchronization thread.
120 /// \~english @param [in] hApp
121 /// HANDLE - Application Handle.
122 /// \~english @retval eFrameworkunifiedStatusOK - On Success
123 /// \~english @retval eFrameworkunifiedStatusThreadAlreadyRunning - If thread already running
124 /// \~english @retval eFrameworkunifiedStatusNullPointer - Null Handle
125 /// \~english @retval eFrameworkunifiedStatusInvldHandle - Invalid Handle
126 /// \~english @par Preconditons
127 /// - The function FrameworkunifiedReleaseSyncDataInstance is successed, object is created successfully.
128 /// \~english @par Change of internal status
129 /// -m_hSyncThreadMsgQHandle saves sync thread handle.
130 /// \~english @par Conditions of processing failure
131 /// - m_hSyncThreadMsgQHandle is not NULL, thread already running.[eFrameworkunifiedStatusThreadAlreadyRunning]
132 /// - Null Handle.[eFrameworkunifiedStatusNullPointer]
133 /// - Invalid Handle.[eFrameworkunifiedStatusInvldHandle]
134 /// \~english @par Detail
135 /// - This fucntion create a child thread of hApp, m_hSyncThreadMsgQHandle saves the child thread.
136 /// - The child thread will be used to receive and send notification data.
137 /// \~english @par Classification
140 /// - eFrameworkunifiedStatus:Result
141 /// - eFrameworkunifiedStatusOK:Success
142 /// - Except eFrameworkunifiedStatusOK:Failure
143 /// \~english @see None
144 ///////////////////////////////////////////////////////////////////////////////////////////
145 EFrameworkunifiedStatus FrameworkunifiedStartNotificationSync(HANDLE hApp);
147 ///////////////////////////////////////////////////////////////////////////////////////////
148 /// \ingroup CFrameworkunifiedSyncData
149 /// \~english @par Brief
150 /// - This method is used to stop the synchronization notification thread.
151 /// \~english @param [in] hApp
152 /// HANDLE - Application Handle.
153 /// \~english @retval eFrameworkunifiedStatusOK - On Success
154 /// \~english @retval eFrameworkunifiedStatusThreadNotExist - If thread already running
155 /// \~english @retval eFrameworkunifiedStatusNullPointer - Null Handle
156 /// \~english @retval eFrameworkunifiedStatusInvldHandle - Invalid Handle
157 /// \~english @par Preconditons
158 /// -The function FrameworkunifiedStartNotificationSync is successed.
159 /// \~english @par Change of internal status
160 /// - m_hSyncThreadMsgQHandle will be delete.
161 /// \~english @par Conditions of processing failure
162 /// - If thread doesn't exist.[eFrameworkunifiedStatusThreadNotExist]
163 /// - Null Handle.[eFrameworkunifiedStatusNullPointer]
164 /// - Invalid Handle.[eFrameworkunifiedStatusInvldHandle]
165 /// \~english @par Detail
166 /// - This method is used by the application to stop the notification synchronization thread.
167 /// m_hSyncThreadMsgQHandle is Invalid and can't be used to get notification data for hApp.
168 /// \~english @par Classification
171 /// - eFrameworkunifiedStatus:Result
172 /// - eFrameworkunifiedStatusOK:Success
173 /// - Except eFrameworkunifiedStatusOK:Failure
174 /// \~english @see None
175 ///////////////////////////////////////////////////////////////////////////////////////////
176 EFrameworkunifiedStatus FrameworkunifiedStopNotificationSync(HANDLE hApp);
178 ///////////////////////////////////////////////////////////////////////////////////////////
179 /// \ingroup CFrameworkunifiedSyncData
180 /// \~english @par Brief
181 /// - API to subscribe to a synchronization notification data.
182 /// \~english @param [in] f_cNotification
183 /// std::string - Notification to be subscribed.
184 /// \~english @retval eFrameworkunifiedStatusOK - On Success
185 /// \~english @retval eFrameworkunifiedStatusFail - On failure
186 /// \~english @par Preconditons
188 /// \~english @par Change of internal status
190 /// \~english @par Conditions of processing failure
191 /// - If f_cNotification is empty or m_hSyncThreadAppHandle is NULL.[eFrameworkunifiedStatusFail]
192 /// \~english @par Detail
193 /// - API to subscribe to a synchronization notification data.\n
194 /// application will get the synchronization notification data at run-time.
195 /// \~english @par Classification
198 /// - eFrameworkunifiedStatus:Result
199 /// - eFrameworkunifiedStatusOK:Success
200 /// - eFrameworkunifiedStatusFail:Failure
201 /// \~english @see None
202 ///////////////////////////////////////////////////////////////////////////////////////////
203 EFrameworkunifiedStatus FrameworkunifiedSubscribeNotificationWithDataSync(const std::string &f_cNotification);
205 ///////////////////////////////////////////////////////////////////////////////////////////
206 /// \ingroup CFrameworkunifiedSyncData
207 /// \~english @par Brief
208 /// - API to unsubscribe to a synchronization notification data.
209 /// \~english @param [in] f_cNotification
210 /// std::string - Notification to be subscribed.
211 /// \~english @retval eFrameworkunifiedStatusOK - On Success
212 /// \~english @retval eFrameworkunifiedStatusFail - On failure
213 /// \~english @par Preconditons
214 /// - the FrameworkunifiedSubscribeNotificationWithDataSync result is success.
215 /// \~english @par Change of internal status
216 /// - The synchronization data's pointor of the special notification will be remove and delete.
217 /// - The synchronization data of the special notification will delete from m_mSyncDataMap.
218 /// \~english @par Conditions of processing failure
219 /// - If f_cNotification is empty or m_hSyncThreadAppHandle is NULL.[eFrameworkunifiedStatusFail]
220 /// \~english @par Detail
221 /// - API to unsubscribe to a synchronization notification data.\n
222 /// After unsubscribing,notification synchronization data of application will be freed.
223 /// \~english @par Classification
226 /// - eFrameworkunifiedStatus:Result
227 /// - eFrameworkunifiedStatusOK:Success
228 /// - eFrameworkunifiedStatusFail:Failure
229 /// \~english @see None
230 ///////////////////////////////////////////////////////////////////////////////////////////
231 EFrameworkunifiedStatus FrameworkunifiedUnSubscribeNotificationWithDataSync(const std::string &f_cNotification);
233 ///////////////////////////////////////////////////////////////////////////////////////////
234 /// \ingroup CFrameworkunifiedSyncData
235 /// \~english @par Brief
236 /// - This function is used to get the synchronization notification data for a particular notification.
237 /// \~english @param [in] f_cNotification
238 /// std::string - Notification for which data is required
239 /// \~english @param [in] f_pBuffer
240 /// PVOID - Buffer for the synchronization data
241 /// \~english @param [in] f_nBufferSize
242 /// UI_16 - size of notification data buffer
243 /// \~english @retval eFrameworkunifiedStatusOK - Success
244 /// \~english @retval eFrameworkunifiedStatusNullPointer - Null pointor
245 /// \~english @retval eFrameworkunifiedStatusFail - failure
246 /// \~english @par Preconditons
248 /// \~english @par Change of internal status
250 /// \~english @par Conditions of processing failure
251 /// - If f_cNotification is empty or m_hSyncThreadAppHandle is NULL or f_nBufferSize is 0.[eFrameworkunifiedStatusFail]
252 /// - If l_itSyncDataPacketItr is not in m_mSyncDataMap.[eFrameworkunifiedStatusNullPointer]
253 /// \~english @par Detail
254 /// - This function is used to get the synchronization notification data for a particular notification.
255 /// f_cNotification is the iterator to the map containing the synchronization data of notification,\n
256 /// using this iterator to get data from m_mSyncDataMap.
257 /// \~english @par Classification
260 /// - eFrameworkunifiedStatus:Result
261 /// - eFrameworkunifiedStatusOK:Success
262 /// - Except eFrameworkunifiedStatusOK:Failure
263 /// \~english @see None
264 ///////////////////////////////////////////////////////////////////////////////////////////
265 EFrameworkunifiedStatus FrameworkunifiedGetSyncNotificationData(const std::string &f_cNotification, PVOID f_pBuffer, UI_16 f_nBufferSize);
267 ///////////////////////////////////////////////////////////////////////////////////////////
268 /// \ingroup CFrameworkunifiedSyncData
269 /// \~english @par Brief
270 /// - API to get the size of synchronization notification data.
271 /// \~english @param [in] f_cNotification
272 /// const std::string - Notification to be subscribed.
273 /// \~english @retval UI_32 - size of notification data
274 /// \~english @par Preconditons
275 /// -Instance is created successfully.
276 /// \~english @par Change of internal status
278 /// \~english @par Conditions of processing failure
280 /// \~english @par Detail
281 /// - This function is used to get the size of the synchronization data.
282 /// if f_cNotification is null or l_itSyncDataPacketItr is not in m_mSyncDataMap\n
283 /// the function will return 0.
284 /// \~english @par Classification
286 /// \~english @see None
287 ///////////////////////////////////////////////////////////////////////////////////////////
288 UI_32 FrameworkunifiedGetSyncDataSize(const std::string &f_cNotification);
291 ////////////////////////////////////////////////////////////////////////////////////////////////
292 /// CFrameworkunifiedSyncData
293 /// Constructor of CFrameworkunifiedSyncData class
299 ////////////////////////////////////////////////////////////////////////////////////////////////
300 CFrameworkunifiedSyncData();
302 ////////////////////////////////////////////////////////////////////////////////////////////////
303 /// ~CFrameworkunifiedSyncData
304 /// Destructor of CFrameworkunifiedSyncData class
310 ////////////////////////////////////////////////////////////////////////////////////////////////
311 ~CFrameworkunifiedSyncData();
313 ////////////////////////////////////////////////////////////////////////////////////////////////
314 /// FrameworkunifiedSyncDataThreadStart
315 /// Callback on the start of the sync thread.
317 /// \param [in] hThread
318 /// HANDLE - Thread Application Handle.
321 /// EFrameworkunifiedStatus - success or error
322 ////////////////////////////////////////////////////////////////////////////////////////////////
323 EFrameworkunifiedStatus FrameworkunifiedSyncDataThreadStart(HANDLE hThread);
325 ////////////////////////////////////////////////////////////////////////////////////////////////
326 /// FrameworkunifiedSyncDataThreadStop
327 /// Callback on the stop of the sync thread.
329 /// \param [in] hThread
330 /// HANDLE - Thread Application Handle.
333 /// EFrameworkunifiedStatus - success or error
334 ////////////////////////////////////////////////////////////////////////////////////////////////
335 EFrameworkunifiedStatus FrameworkunifiedSyncDataThreadStop(HANDLE hThread);
337 ////////////////////////////////////////////////////////////////////////////////////////////////
338 /// FrameworkunifiedSyncDataNotifCallback
339 /// Callback on the receiving the published notification.
341 /// \param [in] hThread
342 /// HANDLE - Thread Application Handle.
345 /// EFrameworkunifiedStatus - success or error
346 ////////////////////////////////////////////////////////////////////////////////////////////////
347 EFrameworkunifiedStatus FrameworkunifiedSyncDataNotifCallback(HANDLE hThread);
349 static CFrameworkunifiedSyncData *m_psSyncData; ///< singleton instance of class
351 BOOL m_bSyncThreadStarted; /// Check to verify if thread started
354 *m_mSyncDataMap; /// Pointer to the map containing the synchronization data as per the notification
356 HANDLE m_hSyncThreadAppHandle; /// S ynchronization thread Application Handle
358 HANDLE m_hAppHandle; /// Application Handle
360 HANDLE m_hSyncThreadMsgQHandle; /// Synchronization thread message queue handle
362 static pthread_spinlock_t m_pSyncLock; /// Synchronization Spinlock
365 #endif /* __FRAMEWORKUNIFIED_NATIVESERVICES_NATIVESERVICES_INC_FRAMEWORK_FRAMEWORKUNIFIED_FRAMEWORK_SYNC_H__ */ // NOLINT (build/header_guard)