nsframework/framework_unified/client/include/native_service/frameworkunified_framework_sync.h

   1 /*
   2  *
   3  * @copyright Copyright (c) 2016-2020 TOYOTA MOTOR CORPORATION.
   4  *
   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
   8  *
   9  *      http://www.apache.org/licenses/LICENSE-2.0
  10  *
  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.
  16  */
  17
  18 ///////////////////////////////////////////////////////////////////////////////
  19 /// \ingroup  tag_NativeService
  20 /// \brief    This file contains the class declaration for synchronization
  21 ///       API's.
  22 ///
  23 ///////////////////////////////////////////////////////////////////////////////
  24 //@{
  25 /**
  26  * @file frameworkunified_framework_sync.h
  27  * @brief \~english This file contains the class declaration for synchronization
  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 framework
  42  *  @ingroup native_service
  43  *  @{
  44  */
  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__
  47
  48 #include <pthread.h>
  49 #include <native_service/frameworkunified_framework_types.h>
  50 #include <time.h>
  51 #include <map>
  52 #include <string>
  53
  54 struct SFrameworkunifiedSyncDataPacket;
  55
  56 // Map containing the synchronization data as per the notification
  57 typedef std::map<std::string, SFrameworkunifiedSyncDataPacket *> TSyncDataPacketList;
  58
  59 // Iterator to the map containing the synchronization data as per the notification
  60 typedef TSyncDataPacketList::iterator TSyncDataPacketItr;
  61
  62 /**
  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.
  67  *
  68  */
  69 class CFrameworkunifiedSyncData {
  70  public:
  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
  78   ///       - None
  79   /// \~english @par Change of internal status
  80   ///       - None
  81   /// \~english @par Conditions of processing failure
  82   ///       - None
  83   /// \~english @par Detail
  84   ///       - If m_psSyncData is NULL,will create a new object,otherwise, will return m_psSyncData.
  85   /// \~english @par Classification
  86   ///          Public
  87   /// \~english @see CFrameworkunifiedSyncData::CFrameworkunifiedSyncData
  88   ///////////////////////////////////////////////////////////////////////////////////////////
  89   static CFrameworkunifiedSyncData *FrameworkunifiedGetSyncDataInstance();
  90
  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
  99   ///       - None
 100   /// \~english @par Change of internal status
 101   ///       - None
 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
 107   ///          Public
 108   /// \~english @par
 109   ///           - eFrameworkunifiedStatus:Result
 110   ///               - eFrameworkunifiedStatusOK:Success
 111   ///               - Except eFrameworkunifiedStatusOK:Failure
 112   /// \~english @see CFrameworkunifiedSyncData::CFrameworkunifiedSyncData
 113   ///////////////////////////////////////////////////////////////////////////////////////////
 114   static EFrameworkunifiedStatus FrameworkunifiedReleaseSyncDataInstance();
 115
 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
 138   ///          Public
 139   /// \~english @par
 140   ///           - eFrameworkunifiedStatus:Result
 141   ///               - eFrameworkunifiedStatusOK:Success
 142   ///               - Except eFrameworkunifiedStatusOK:Failure
 143   /// \~english @see None
 144   ///////////////////////////////////////////////////////////////////////////////////////////
 145   EFrameworkunifiedStatus FrameworkunifiedStartNotificationSync(HANDLE hApp);
 146
 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
 169   ///          Public
 170   /// \~english @par
 171   ///           - eFrameworkunifiedStatus:Result
 172   ///               - eFrameworkunifiedStatusOK:Success
 173   ///               - Except eFrameworkunifiedStatusOK:Failure
 174   /// \~english @see None
 175   ///////////////////////////////////////////////////////////////////////////////////////////
 176   EFrameworkunifiedStatus FrameworkunifiedStopNotificationSync(HANDLE hApp);
 177
 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
 187   ///       - none
 188   /// \~english @par Change of internal status
 189   ///       - none
 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
 196   ///          Public
 197   /// \~english @par
 198   ///           - eFrameworkunifiedStatus:Result
 199   ///               - eFrameworkunifiedStatusOK:Success
 200   ///               - eFrameworkunifiedStatusFail:Failure
 201   /// \~english @see None
 202   ///////////////////////////////////////////////////////////////////////////////////////////
 203   EFrameworkunifiedStatus FrameworkunifiedSubscribeNotificationWithDataSync(const std::string &f_cNotification);
 204
 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
 224   ///          Public
 225   /// \~english @par
 226   ///           - eFrameworkunifiedStatus:Result
 227   ///               - eFrameworkunifiedStatusOK:Success
 228   ///               - eFrameworkunifiedStatusFail:Failure
 229   /// \~english @see None
 230   ///////////////////////////////////////////////////////////////////////////////////////////
 231   EFrameworkunifiedStatus FrameworkunifiedUnSubscribeNotificationWithDataSync(const std::string &f_cNotification);
 232
 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
 247   ///       - none
 248   /// \~english @par Change of internal status
 249   ///       - none
 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
 258   ///          Public
 259   /// \~english @par
 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);
 266
 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
 277   ///       -None
 278   /// \~english @par Conditions of processing failure
 279   ///       - None
 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
 285   ///       - Public
 286   /// \~english @see None
 287   ///////////////////////////////////////////////////////////////////////////////////////////
 288   UI_32 FrameworkunifiedGetSyncDataSize(const std::string &f_cNotification);
 289
 290  private:
 291   ////////////////////////////////////////////////////////////////////////////////////////////////
 292   /// CFrameworkunifiedSyncData
 293   /// Constructor of CFrameworkunifiedSyncData class
 294   ///
 295   /// \param
 296   ///
 297   /// \return
 298   ///
 299   ////////////////////////////////////////////////////////////////////////////////////////////////
 300   CFrameworkunifiedSyncData();
 301
 302   ////////////////////////////////////////////////////////////////////////////////////////////////
 303   /// ~CFrameworkunifiedSyncData
 304   /// Destructor of CFrameworkunifiedSyncData class
 305   ///
 306   /// \param
 307   ///
 308   /// \return
 309   ///
 310   ////////////////////////////////////////////////////////////////////////////////////////////////
 311   ~CFrameworkunifiedSyncData();
 312
 313   ////////////////////////////////////////////////////////////////////////////////////////////////
 314   /// FrameworkunifiedSyncDataThreadStart
 315   /// Callback on the start of the sync thread.
 316   ///
 317   /// \param [in] hThread
 318   ///         HANDLE - Thread Application Handle.
 319   ///
 320   /// \return status
 321   ///         EFrameworkunifiedStatus - success or error
 322   ////////////////////////////////////////////////////////////////////////////////////////////////
 323   EFrameworkunifiedStatus FrameworkunifiedSyncDataThreadStart(HANDLE hThread);
 324
 325   ////////////////////////////////////////////////////////////////////////////////////////////////
 326   /// FrameworkunifiedSyncDataThreadStop
 327   /// Callback on the stop of the sync thread.
 328   ///
 329   /// \param [in] hThread
 330   ///         HANDLE - Thread Application Handle.
 331   ///
 332   /// \return status
 333   ///         EFrameworkunifiedStatus - success or error
 334   ////////////////////////////////////////////////////////////////////////////////////////////////
 335   EFrameworkunifiedStatus FrameworkunifiedSyncDataThreadStop(HANDLE hThread);
 336
 337   ////////////////////////////////////////////////////////////////////////////////////////////////
 338   /// FrameworkunifiedSyncDataNotifCallback
 339   /// Callback on the receiving the published notification.
 340   ///
 341   /// \param [in] hThread
 342   ///         HANDLE - Thread Application Handle.
 343   ///
 344   /// \return status
 345   ///         EFrameworkunifiedStatus - success or error
 346   ////////////////////////////////////////////////////////////////////////////////////////////////
 347   EFrameworkunifiedStatus FrameworkunifiedSyncDataNotifCallback(HANDLE hThread);
 348
 349   static CFrameworkunifiedSyncData *m_psSyncData;    ///< singleton instance of class
 350
 351   BOOL m_bSyncThreadStarted;        /// Check to verify if thread started
 352
 353   TSyncDataPacketList
 354   *m_mSyncDataMap;    /// Pointer to the map containing the synchronization data as per the notification
 355
 356   HANDLE m_hSyncThreadAppHandle;      /// S ynchronization thread Application Handle
 357
 358   HANDLE m_hAppHandle;          /// Application Handle
 359
 360   HANDLE m_hSyncThreadMsgQHandle;     /// Synchronization thread message queue handle
 361
 362   static pthread_spinlock_t m_pSyncLock;      /// Synchronization Spinlock
 363 };
 364
 365 #endif /* __FRAMEWORKUNIFIED_NATIVESERVICES_NATIVESERVICES_INC_FRAMEWORK_FRAMEWORKUNIFIED_FRAMEWORK_SYNC_H__ */  // NOLINT  (build/header_guard)
 366 /** @}*/
 367 /** @}*/
 368 /** @}*/
 369 /** @}*/
 370 //@}