video_in_hal/nsframework/framework_unified/client/include/native_service/ns_timer_if.hpp

   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 NSTimer
  19 /// \brief   Header file for Timer class.
  20 ///
  21 //////////////////////////////////////////////////////////////////////////////////////////////////
  22 //@{
  23 /**
  24  * @file ns_timer_if.hpp
  25  * @brief \~english Header file for Timer class.
  26  *
  27  */
  28 /** @addtogroup BaseSystem
  29  *  @{
  30  */
  31 /** @addtogroup native_service
  32  *  @ingroup BaseSystem
  33  *  @{
  34  */
  35 /** @addtogroup framework_unified
  36  *  @ingroup native_service
  37  *  @{
  38  */
  39 /** @addtogroup native
  40  *  @ingroup framework_unified
  41  *  @{
  42  */
  43 #ifndef NS_TIMER_IF_HPP_  // NOLINT  (build/header_guard)
  44 #define NS_TIMER_IF_HPP_
  45
  46 #include <native_service/frameworkunified_types.h>
  47 #include <native_service/ns_timer_if.h>
  48
  49 /**
  50  * @class NSTimer
  51  * \~english @brief Handle Timer
  52  * \~english @par   Brief Introduction
  53  *        Timer class is using to handle the timer.creating, starting, stopping,and so on.
  54  *
  55  */
  56 class NSTimer {
  57  public:
  58   /////////////////////////////////////////////////////////////////////////////////////
  59   /// \ingroup NSTimer
  60   /// \~english @par Brief
  61   ///        Creates a timer object with default behavior as single timeout timer.
  62   /// \~english @retval none
  63   /// \~english @par Preconditons
  64   ///           -None
  65   /// \~english @par Change of internal status
  66   ///           None
  67   /// \~english @par Conditions of processing failure
  68   ///           -None
  69   /// \~english @par Detail
  70   ///           -To create the instance of this class.init the member var using m_hTimer, m_u64TimeInterval,
  71   ///           m_bRepeatTimer.\n
  72   ///            Default status,all time will be set 0.
  73   /// \~english @par Classification
  74   ///           Public
  75   /// \~english @par Type
  76   ///           -
  77   /// \~english @see ~NSTimer
  78   ////////////////////////////////////////////////////////////////////////////////////
  79   NSTimer();
  80
  81   /////////////////////////////////////////////////////////////////////////////////////
  82   /// \ingroup NSTimer
  83   /// \~english @par Brief
  84   ///        Deletes a timer object.
  85   /// \~english @retval none
  86   /// \~english @par Preconditons
  87   ///           -Instance of this class is created successfully.
  88   /// \~english @par Change of internal status
  89   ///           None
  90   /// \~english @par Conditions of processing failure
  91   ///           -None
  92   /// \~english @par Detail
  93   ///           -Destruct the instance of this class.
  94   /// \~english @par Classification
  95   ///           Public
  96   /// \~english @par Type
  97   ///           -None
  98   /// \~english @see NSTimer
  99   ////////////////////////////////////////////////////////////////////////////////////
 100   ~NSTimer();
 101
 102   /////////////////////////////////////////////////////////////////////////////////////
 103   /// \ingroup NSTimer
 104   /// \~english @par Brief
 105   ///        This function overloads \ref SetNotifyMethod().
 106   ///        On timeout, sends the command id  to the message queue of specified application.
 107   ///        Resets previous notify method if any.
 108   /// \~english @param[in] notifyCmdId
 109   ///        UI_16 - command id.
 110   /// \~english @param[in] notifyToAppName
 111   ///        PCSTR - Send command id to the message queue of this application
 112   /// \~english @retval EFrameworkunifiedStatus - Returns eFrameworkunifiedStatusOK if the action is set otherwise eFrameworkunifiedStatusFail
 113   /// \~english @retval eFrameworkunifiedStatusOK - Success
 114   /// \~english @retval eFrameworkunifiedStatusInvldParam - Invalid parameter
 115   /// \~english @retval eFrameworkunifiedStatusFail - process error
 116   /// \~english @par Preconditons
 117   ///           -None
 118   /// \~english @par Change of internal status
 119   ///           None
 120   /// \~english @par Conditions of processing failure
 121   ///       - Pointer of AppName specified by argument(notifyToAppName) is NULL [eFrameworkunifiedStatusInvldParam]
 122   ///       - Bytes of AppName specified by argument(notifyToAppName) are larger then MAX_SERVICE_NAME(15byte)
 123   ///       [eFrameworkunifiedStatusInvldParam]
 124   ///       - There isn't enough buffer(malloc) to storage message queue name, when getting(McOpenSender) message queue
 125   ///       handle [eFrameworkunifiedStatusFail]
 126   ///       - Bytes of message queue name are larger then LIMIT_QUEUE_NAME_SIZE(16byte), when getting(McOpenSender)
 127   ///       message queue handle [eFrameworkunifiedStatusFail]
 128   ///       - Failed to get message queue(mq_open), when getting(McOpenSender) message queue handle [eFrameworkunifiedStatusFail]
 129   ///       - There isn't enough buffer(malloc) to storage message queue information, when getting(McOpenSender) message
 130   ///       queue handle [eFrameworkunifiedStatusFail]
 131   ///       - Failed to create(epoll_create1) file descriptor for epoll, when creating timer handle(NS_TimerCreate)
 132   ///       [eFrameworkunifiedStatusFail]
 133   ///       - Failed to create(eventfd) file descriptor for event notification, when creating timer
 134   ///       handle(NS_TimerCreate) [eFrameworkunifiedStatusFail]
 135   ///       - Failed to connect(epoll_ctl) file descriptors for epoll and event notification, when creating timer
 136   ///       handle(NS_TimerCreate) [eFrameworkunifiedStatusFail]
 137   ///       - Failed to create(pthread_create) timer thread for event notification, when creating timer
 138   ///       handle(NS_TimerCreate) [eFrameworkunifiedStatusFail]
 139   ///       - There isn't enough buffer(malloc) to storage timer handle structure, when creating timer
 140   ///       handle(NS_TimerCreate) [eFrameworkunifiedStatusFail]
 141   ///       - There isn't enough buffer(malloc) to storage timer information structure,, when creating timer
 142   ///       handle(NS_TimerCreate) [eFrameworkunifiedStatusFail]
 143   ///       - Message queue handle is INVALID_HANDLE(-1), when creating timer handle(NS_TimerCreate) [eFrameworkunifiedStatusFail]
 144   ///       - Checking code of message queue handle is not MQ_CHECK_CODE, when creating timer handle(NS_TimerCreate)
 145   ///       [eFrameworkunifiedStatusFail]
 146   ///       - Type of message queue handle is not send/receive, when creating timer handle(NS_TimerCreate)
 147   ///       [eFrameworkunifiedStatusFail]
 148   ///       - Failed to create(timerfd_create) file descriptor for timer, when creating timer handle(NS_TimerCreate)
 149   ///       [eFrameworkunifiedStatusFail]
 150   ///       - Failed to connect(epoll_ctl) file descriptors for epoll and timer, when creating timer
 151   ///       handle(NS_TimerCreate) [eFrameworkunifiedStatusFail]
 152   ///       - Timer handle state of instance has been deleted(DELETED_STATE), when creating timer handle(NS_TimerCreate)
 153   ///       [eFrameworkunifiedStatusFail]
 154   ///       - Failed to start/stop(timerfd_settime) timer, when creating timer handle(NS_TimerCreate) [eFrameworkunifiedStatusFail]
 155   /// \~english @par Detail
 156   ///        This function overloads \ref SetNotifyMethod().
 157   ///        On timeout, sends the command id  to the message queue of specified application.
 158   ///        Create a timer handle(m_hTimer) of instance, if the time handle already exits, delete it then create a new
 159   ///        one.
 160   ///        If there is resource for timer notification before, reset it.
 161   /// \~english @par Classification
 162   ///           Public
 163   /// \~english @par Type
 164   ///           -None
 165   /// \~english @see McOpenSender, McClose, NS_TimerCreate
 166   ////////////////////////////////////////////////////////////////////////////////////
 167   EFrameworkunifiedStatus SetNotifyMethod(UI_16 notifyCmdId, PCSTR notifyToAppName);
 168
 169   /////////////////////////////////////////////////////////////////////////////////////
 170   /// \ingroup NSTimer
 171   /// \~english @par Brief
 172   ///        Sets the timer as a repeat timer. Timer timeouts repeatedly as per the interval set.
 173   ///        Default timer fires only once.
 174   ///        Not effective, if the timer is running. Effective on next \ref Start() or \ref Start(seconds, msecs) call.
 175   /// \~english @param[in] repeatTimer
 176   ///        BOOL - TRUE -  set repeat timer
 177   ///          FALSE - set single timeout timer. (Default behavior)
 178   /// \~english @retval none
 179   /// \~english @par Preconditons
 180   ///           -None
 181   /// \~english @par Change of internal status
 182   ///           -None
 183   /// \~english @par Conditions of processing failure
 184   ///           -None
 185   /// \~english @par Detail
 186   ///        Sets the timer as a repeat timer. Timer timeouts repeatedly as per the interval set.
 187   ///        Default timer fires only once.
 188   ///        Not effective, if the timer is running. Effective on next \ref Start() or \ref Start(seconds, msecs) call.
 189   /// \~english @par Classification
 190   ///           Public
 191   /// \~english @par Type
 192   ///           -None
 193   /// \~english @see none
 194   ////////////////////////////////////////////////////////////////////////////////////
 195   VOID SetRepeatTimer(BOOL repeatTimer);
 196
 197   /////////////////////////////////////////////////////////////////////////////////////
 198   /// \ingroup NSTimer
 199   /// \~english @par Brief
 200   ///        Set the interval of timeout. Interval is addition of seconds and milliseconds passed as an arguments.
 201   /// \~english @param[in] seconds
 202   ///        UI_32 - Time in seconds
 203   /// \~english @param[in] msecs
 204   ///        UI_64 - Time in milliseconds
 205   /// \~english @retval none
 206   /// \~english @par Preconditons
 207   ///           -None
 208   /// \~english @par Change of internal status
 209   ///           None
 210   /// \~english @par Conditions of processing failure
 211   ///           -None
 212   /// \~english @par Detail
 213   ///           Set the interval of timeout. Interval is addition of seconds and milliseconds passed as an arguments.
 214   ///           The default value of interval time is 0.
 215   ///           If interval time is 0, stop timer.
 216   /// \~english @par Classification
 217   ///           Public
 218   /// \~english @par Type
 219   ///           -None
 220   /// \~english @see none
 221   ////////////////////////////////////////////////////////////////////////////////////
 222   VOID SetTime(UI_32 seconds, UI_64 msecs);
 223
 224   ////////////////////////////////////////////////////////////////////////////////////////////////
 225   /// \ingroup NSTimer
 226   /// \~english @par Brief
 227   ///        This function overloads SetTime(). Set the interval of timeout. Interval is addition of hrs,
 228   ///        mins, seconds and milliseconds passed as an arguments.
 229   /// \~english @param[in] hrs
 230   ///        UI_32 - Time in hours
 231   /// \~english @param[in] mins
 232   ///        UI_64 - Time in minutes
 233   /// \~english @param[in] seconds
 234   ///        UI_32 - Time in seconds
 235   /// \~english @param[in] msecs
 236   ///        UI_64 - Time in milliseconds
 237   /// \~english @retval none
 238   /// \~english @par Preconditons
 239   ///           -None
 240   /// \~english @par Change of internal status
 241   ///           None
 242   /// \~english @par Conditions of processing failure
 243   ///           -None
 244   /// \~english @par Detail
 245   ///        This function overloads SetTime(). Set the interval of timeout. Interval is addition of hrs,
 246   ///        mins, seconds and milliseconds passed as an arguments.
 247   ///        The default value of interval time is 0.
 248   ///        If interval time is 0, stop timer.
 249   /// \~english @par Classification
 250   ///           Public
 251   /// \~english @par Type
 252   ///           -None
 253   /// \~english @see none
 254   ////////////////////////////////////////////////////////////////////////////////////////////////
 255   VOID SetTime(UI_32 hrs, UI_32 mins, UI_32 seconds, UI_64 msecs);
 256
 257   /////////////////////////////////////////////////////////////////////////////////////
 258   /// \ingroup NSTimer
 259   /// \~english @par Brief
 260   ///        Starts or restarts timer with specified time interval. Interval is addition of seconds and
 261   ///        milliseconds passed as an arguments.
 262   /// \~english @param[in] seconds
 263   ///        UI_32 - Time in seconds
 264   /// \~english @param[in] msecs
 265   ///        UI_64 - Time in milliseconds
 266   /// \~english @retval EFrameworkunifiedStatus - Returns eFrameworkunifiedStatusOK on success otherwise eFrameworkunifiedStatusFail
 267   /// \~english @par Preconditons
 268   ///           - Create a timer handle of instance by SetNotifyMethod()
 269   /// \~english @par Change of internal status
 270   ///           None
 271   /// \~english @par Conditions of processing failure
 272   ///       - Timer handle of instance is NULL [eFrameworkunifiedStatusFail]
 273   ///       - Timer handle state of instance has been deleted(DELETED_STATE) [eFrameworkunifiedStatusFail]
 274   ///       - Failed to start/stop(timerfd_settime) timer [eFrameworkunifiedStatusFail]
 275   /// \~english @par Detail
 276   ///        Starts or restarts timer with specified time interval. Interval is addition of seconds and
 277   ///        milliseconds passed as an arguments.
 278   ///        Interval time setted by this method will overwrite interval time setted by SetTime(UI_32, UI_64).
 279   ///        If interval time is 0, stop timer.
 280   /// \~english @par Classification
 281   ///           Public
 282   /// \~english @par Type
 283   ///           - None
 284   /// \~english @see SetTime(UI_32, UI_64), Start, Stop, SetNotifyMethod
 285   ////////////////////////////////////////////////////////////////////////////////////
 286   EFrameworkunifiedStatus Start(UI_32 seconds, UI_64 msecs);
 287
 288   /////////////////////////////////////////////////////////////////////////////////////
 289   /// \ingroup NSTimer
 290   /// \~english @par Brief
 291   ///        This function overloads Start(). Starts or restarts timer with interval specified using SetTime()
 292   ///        or last interval (if the timer was started before using Start(seconds, msecs)).
 293   /// \~english @retval EFrameworkunifiedStatus - Returns eFrameworkunifiedStatusOK on success otherwise eFrameworkunifiedStatusFail
 294   /// \~english @par Preconditons
 295   ///           - Create a timer handle of instance by SetNotifyMethod()
 296   /// \~english @par Change of internal status
 297   ///           None
 298   /// \~english @par Conditions of processing failure
 299   ///       - Timer handle of instance is NULL [eFrameworkunifiedStatusFail]
 300   ///       - Timer handle state of instance has been deleted(DELETED_STATE) [eFrameworkunifiedStatusFail]
 301   ///       - Failed to start/stop(timerfd_settime) timer [eFrameworkunifiedStatusFail]
 302   /// \~english @par Detail
 303   ///       - Starts or restarts timer with interval specified using SetTime(UI_32, UI_64) or Start(UI_32, UI_64).
 304   ///         If interval time is not setted, default value is 0. If interval time is 0, stop timer.
 305   /// \~english @par Classification
 306   ///           Public
 307   /// \~english @par Type
 308   ///           - None
 309   /// \~english @see SetTime(UI_32, UI_64), Stop, SetNotifyMethod, WholeSeconds, MSToNS, NS_TimerSetTime
 310   ////////////////////////////////////////////////////////////////////////////////////
 311   EFrameworkunifiedStatus Start();
 312
 313   /////////////////////////////////////////////////////////////////////////////////////
 314   /// \ingroup NSTimer
 315   /// \~english @par Brief
 316   ///        Stops the timer
 317   /// \~english @retval EFrameworkunifiedStatus - Returns eFrameworkunifiedStatusOK on success otherwise eFrameworkunifiedStatusFail
 318   /// \~english @par Preconditons
 319   ///           - Create a timer handle of instance by SetNotifyMethod()
 320   /// \~english @par Change of internal status
 321   ///           None
 322   /// \~english @par Conditions of processing failure
 323   ///       - Timer handle of instance is NULL [eFrameworkunifiedStatusFail]
 324   ///       - Timer handle state of instance has been deleted(DELETED_STATE) [eFrameworkunifiedStatusFail]
 325   ///       - Failed to stop(timerfd_settime) timer [eFrameworkunifiedStatusFail]
 326   /// \~english @par Detail
 327   ///           - Stops the timer
 328   /// \~english @par Classification
 329   ///           Public
 330   /// \~english @par Type
 331   ///           - None
 332   /// \~english @see Start, Start(UI_32, UI_64), SetNotifyMethod, NS_TimerSetTime
 333   ////////////////////////////////////////////////////////////////////////////////////
 334   EFrameworkunifiedStatus Stop();
 335
 336   ////////////////////////////////////////////////////////////////////////////////////////////////
 337   /// \ingroup NSTimer
 338   /// \~english @par Brief
 339   ///        Returns timer running status
 340   /// \~english @retval BOOL - TRUE if timer is running else FALSE
 341   /// \~english @par Preconditons
 342   ///           -None
 343   /// \~english @par Change of internal status
 344   ///           None
 345   /// \~english @par Conditions of processing failure
 346   ///           -None
 347   /// \~english @par Detail
 348   ///           -Returns timer running status
 349   /// \~english @par Classification
 350   ///           Public
 351   /// \~english @par Type
 352   ///           -None
 353   /// \~english @see Start, Start(UI_32, UI_64), SetNotifyMethod, NS_TimerSetTime
 354   ////////////////////////////////////////////////////////////////////////////////////////////////
 355   BOOL IsRunning();
 356
 357   ////////////////////////////////////////////////////////////////////////////////////////////////
 358   /// \ingroup NSTimer
 359   /// \~english @par Brief
 360   ///           Returns timeout interval in milliseconds
 361   /// \~english @retval UI_64 - Timeout interval in milliseconds
 362   /// \~english @par Preconditons
 363   ///           -None
 364   /// \~english @par Change of internal status
 365   ///           None
 366   /// \~english @par Conditions of processing failure
 367   ///           -None
 368   /// \~english @par Detail
 369   ///           - Returns timeout interval in milliseconds
 370   /// \~english @par Classification
 371   ///           Public
 372   /// \~english @par Type
 373   ///           -None
 374   /// \~english @see None
 375   ////////////////////////////////////////////////////////////////////////////////////////////////
 376   UI_64 GetInterval();
 377
 378  private:
 379
 380   HANDLE  m_hTimer;  ///< Corresponding NS timer handle
 381
 382   UI_64   m_u64TimeInterval; ///< time interval in milliseconds
 383
 384   BOOL    m_bRepeatTimer; ///< if it is a repeat timer. Default value is false.
 385 };
 386
 387
 388 #endif  // NS_TIMER_IF_HPP_  // NOLINT  (build/header_guard)
 389 /** @}*/
 390 /** @}*/
 391 /** @}*/
 392 /** @}*/
 393 //@}