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 /// brief This file supports a generic timer abstraction.
19 ///////////////////////////////////////////////////////////////////////////////
22 * @file ss_system_timer.h
25 /** @addtogroup BaseSystem
28 /** @addtogroup system_service
32 /** @addtogroup system_manager
33 * @ingroup system_service
38 #ifndef SS_SYSTEM_TIMER_H_ // NOLINT (build/header_guard)
39 #define SS_SYSTEM_TIMER_H_
41 #include <native_service/frameworkunified_types.h>
42 #include <native_service/frameworkunified_framework_if.h>
47 const PCSTR TIMER_SERVICE_NAME = "TIMER";
52 * \~english @brief Timer
53 * \~english @par Brief Introduction
54 * Class to provide Timer function
59 /////////////////////////////////////////////////////////////////////////////////////
61 /// \~english @par Summary
62 /// Default constructor of Timer class.
63 /// \~english @param None
64 /// \~english @retval None
65 /// \~english @par Preconditions
67 /// \~english @par Change of the internal state
68 /// - The internal state is not changed.
69 /// \~english @par Causes of failures
71 /// \~english @par Classification
73 /// \~english @par Type
75 /// \~english @par Detail
76 /// To generate a Timer class, and initialize member variables. \n
77 /// After the constructor, be sure to call the Initialize. \n
78 /// \~english @see ~Timer, Initialize
79 ////////////////////////////////////////////////////////////////////////////////////
82 /////////////////////////////////////////////////////////////////////////////////////
84 /// \~english @par Summary
85 /// Constructor of Timer class.
86 /// \~english @param [in] hdl
87 /// HANDLE - HANDLE for Application
88 /// \~english @param [in] id
89 /// UI_32 - Timer ID corresponding to the callback function
90 /// \~english @param [in] CbFn
91 /// CbFuncPtr - Pointer to a callback function to be called when the timer expires
92 /// \~english @retval None
93 /// \~english @par Preconditions
94 /// - Generation/initialization of Dispatcher for the Application (FrameworkunifiedCreateDispatcherWithoutLoop etc) has been
96 /// \~english @par Change of the internal state
97 /// - The internal state is not changed.
98 /// \~english @par Causes of failures
100 /// \~english @par Classification
102 /// \~english @par Type
104 /// \~english @par Detail
105 /// To generate a Timer class. \n
106 /// To initialize timer information structure of the member variables. \n
107 /// To initialize the member variables of the class with an argument. Therefore, there is no need to call the
108 /// Initialize() function when using this constructor.
109 /// \~english @see ~Timer, Initialize
110 ////////////////////////////////////////////////////////////////////////////////////
111 Timer(HANDLE hdl, UI_32 id, CbFuncPtr CbFn);
113 /////////////////////////////////////////////////////////////////////////////////////
115 /// \~english @par Summary
116 /// Destructor of Timer class.
117 /// \~english @param None
118 /// \~english @retval None
119 /// \~english @par Preconditions
121 /// \~english @par Change of the internal state
122 /// - The internal state is not changed.
123 /// \~english @par Causes of failures
125 /// \~english @par Classification
127 /// \~english @par Type
129 /// \~english @par Detail
130 /// To delete a Timer class. \n
131 /// If the initialization is complete state, to end by calling the Shutdown().
132 /// \~english @see Timer
133 ////////////////////////////////////////////////////////////////////////////////////
136 /////////////////////////////////////////////////////////////////////////////////////
137 /// \ingroup Initialize
138 /// \~english @par Summary
139 /// Initialization of the Timer class.
140 /// \~english @param [in] hApp
141 /// HANDLE - HANDLE for Application
142 /// \~english @param [in] id
143 /// UI_32 - Timer ID corresponding to the callback function
144 /// \~english @param [in] CbFn
145 /// CbFuncPtr - Pointer to a callback function to be called when the timer expires
146 /// \~english @retval TRUE Initialization success
147 /// \~english @retval FALSE Initialization failed
148 /// \~english @par Preconditions
149 /// - Generation/initialization of Dispatcher for the Application (FrameworkunifiedCreateDispatcherWithoutLoop etc) has been
151 /// \~english @par Change of the internal state
152 /// - The internal state is not changed.
153 /// \~english @par Causes of failures
154 /// - Handle(hApp) that has been specified by the argument is NULL. [FALSE]
155 /// - Timer ID(id) that has been specified by the argument is 0. [FALSE]
156 /// - Pointer to a callback function that has been specified by the argument is NULL. [FALSE]
157 /// \~english @par Classification
159 /// \~english @par Type
160 /// Sync only(None communication)
161 /// \~english @par Detail
162 /// To initialize the member variables of the following.
163 /// - HANDLE for Application
164 /// - Timer information structure
165 /// - Pointer to a callback function
166 /// - HANDLE of message queue
169 /// A timer class to initialization completion state.
170 /// \~english @see ~Timer, Shutdown
171 ////////////////////////////////////////////////////////////////////////////////////
172 BOOL Initialize(HANDLE hApp, UI_32 id, CbFuncPtr CbFn);
174 /////////////////////////////////////////////////////////////////////////////////////
175 /// \ingroup Reinitialize
176 /// \~english @par Summary
177 /// - Reinitialize the timer by specifying a timer value information
178 /// \~english @param [in] id
179 /// UI_32 - timer id that you want to reinitialize
180 /// \~english @retval None
181 /// \~english @par Preconditions
182 /// - That has been initialized in the Initialize().
183 /// \~english @par Change of the internal state
184 /// - set m_tTi.iCmd with id
185 /// - using the result of function McOpenSender(FrameworkunifiedGetAppName(m_hApp)) to set m_hSnd
186 /// - create a timer and give the handle to m_hTmr
187 /// - set m_bInit with TRUE
188 /// \~english @par Causes of failures
190 /// \~english @par Classification
192 /// \~english @par Type
194 /// \~english @par Detail
195 /// Reinitialize the timer by specifying a timer value information, \n
196 /// create a new timer if it is not initialize.
197 /// \~english @see Initialize
198 ////////////////////////////////////////////////////////////////////////////////////
199 void Reinitialize(UI_32 id);
201 /////////////////////////////////////////////////////////////////////////////////////
202 /// \ingroup Shutdown
203 /// \~english @par Summary
204 /// The end of the Timer class.
205 /// \~english @param None
206 /// \~english @retval None
207 /// \~english @par Preconditions
208 /// - That has been initialized in the Initialize().
209 /// \~english @par Change of the internal state
210 /// - The internal state is not changed.
211 /// \~english @par Causes of failures
213 /// \~english @par Classification
215 /// \~english @par Type
216 /// Sync only(None communication)
217 /// \~english @par Detail
218 /// In the case of initialization completion state, it is completed by the following process.\n
220 /// - Delete Timer Object
221 /// - Set NULL to a timer object variable
222 /// - Close message queue
223 /// - Set NULL to a message queue HANDLE variable
224 /// - The timer class to uninitialized.
226 /// \nIf you want to re-use this timer, call again Initialize() function.
227 /// \~english @see Timer, Initialize
228 ////////////////////////////////////////////////////////////////////////////////////
231 /////////////////////////////////////////////////////////////////////////////////////
233 /// \~english @par Summary
234 /// Set the timer value information.
235 /// \~english @param [in] ss
236 /// UI_32 - Timeout expiration time(sec)
237 /// \~english @param [in] sms
238 /// UI_32 - Timeout expiration time(nano sec)
239 /// \~english @param [in] rs
240 /// UI_32 - Timeout expiration time at the time of repeat(sec)
241 /// \~english @param [in] rms
242 /// UI_32 - Timeout expiration time at the time of repeat(nano sec)
243 /// \~english @retval TRUE Setting success
244 /// \~english @retval FALSE Setting failed
245 /// \~english @par Preconditions
246 /// - That has been initialized in the Initialize().
247 /// \~english @par Change of the internal state
248 /// - The internal state is not changed.
249 /// \~english @par Causes of failures
250 /// - Not been initialized. [FALSE]
251 /// \~english @par Classification
253 /// \~english @par Type
254 /// Sync only(None communication)
255 /// \~english @par Detail
256 /// Set a timer value information specified by the argument to the timer information structure.
257 /// \~english @see Timer
258 ////////////////////////////////////////////////////////////////////////////////////
259 BOOL SetTime(UI_32 ss, UI_32 sms, UI_32 rs, UI_32 rms);
261 /////////////////////////////////////////////////////////////////////////////////////
263 /// \~english @par Summary
264 /// The start of the timer by specifying a timer value information.
265 /// \~english @param [in] ss
266 /// UI_32 - Timeout expiration time(sec)
267 /// \~english @param [in] sms
268 /// UI_32 - Timeout expiration time(nano sec)
269 /// \~english @param [in] rs
270 /// UI_32 - Timeout expiration time at the time of repeat(sec)
271 /// \~english @param [in] rms
272 /// UI_32 - Timeout expiration time at the time of repeat(nano sec)
273 /// \~english @retval TRUE Stop success
274 /// \~english @retval FALSE Stop failed
275 /// \~english @par Preconditions
276 /// - That has been initialized in the Initialize().
277 /// \~english @par Change of the internal state
278 /// - The internal state is not changed.
279 /// \~english @par Causes of failures
280 /// - Not been initialized. [FALSE]
281 /// \~english @par Classification
283 /// \~english @par Type
285 /// \~english @par Detail
286 /// In the case of initialization completion state, start the timer. \n
287 /// After timer start, again, if you start the timer, it does not work guarantee.
288 /// \~english @see Stop
289 ////////////////////////////////////////////////////////////////////////////////////
290 BOOL Start(UI_32 ss, UI_32 sms, UI_32 rs, UI_32 rms);
292 /////////////////////////////////////////////////////////////////////////////////////
294 /// \~english @par Summary
296 /// \~english @param None
297 /// \~english @retval TRUE Stop success
298 /// \~english @retval FALSE Stop failed
299 /// \~english @par Preconditions
300 /// - That has been initialized in the Initialize().
301 /// - Set the timeout value in SetTime().
302 /// \~english @par Change of the internal state
303 /// - The internal state is not changed.
304 /// \~english @par Causes of failures
305 /// - Not been initialized. [FALSE]
306 /// \~english @par Classification
308 /// \~english @par Type
310 /// \~english @par Detail
311 /// In the case of initialization completion state, start the timer. \n
312 /// After timer start, again, if you start the timer, it does not work guarantee.
313 /// \~english @see SetTime, Stop
314 ////////////////////////////////////////////////////////////////////////////////////
317 /////////////////////////////////////////////////////////////////////////////////////
319 /// \~english @par Summary
321 /// \~english @param None
322 /// \~english @retval TRUE Stop success
323 /// \~english @retval FALSE Stop failed
324 /// \~english @par Preconditions
325 /// - That has been initialized in the Initialize().
326 /// - The timer has been started
327 /// \~english @par Change of the internal state
328 /// - The internal state is not changed.
329 /// \~english @par Causes of failures
330 /// - Not been initialized. [FALSE]
331 /// \~english @par Classification
333 /// \~english @par Type
335 /// \~english @par Detail
336 /// In the case of initialization completion state, stop the timer. \n
337 /// After the timer has stopped, again, if you stop the timer, it does not do anything to just processing
338 /// Internal error occurs.
339 /// \~english @see Start
340 ////////////////////////////////////////////////////////////////////////////////////
344 BOOL m_bInit; /// flag that indicated if the class has been initialized or not
345 HANDLE m_hApp; /// refs to an applications hApp handle
346 HANDLE m_hSnd; /// refs to applications message queue
347 HANDLE m_hTmr; /// refs to a timer handle
348 NSTimerInfo m_tTi; /// timer parameters
349 CbFuncPtr m_CbFn; /// pointer to the callback method
352 /** @}*/ // end of Timer
353 /** @}*/ // end of system_manager
354 /** @}*/ // end of SystemService
355 /** @}*/ // end of BaseSystem
359 * \~english @brief TimerCtrl
360 * \~english @par Brief Introduction
361 * Class to provide TimerCtrl function
366 /////////////////////////////////////////////////////////////////////////////////////
367 /// \ingroup TimerCtrl
368 /// \~english @par Summary
369 /// Default Constructor, called when the class is instantiated.
370 /// \~english @param None
371 /// \~english @retval None
372 /// \~english @par Preconditions
374 /// \~english @par Change of the internal state
375 /// - set m_hApp as NULL,m_nTimersMax as DEFAULT_NTIMERS
376 /// \~english @par Causes of failures
378 /// \~english @par Classification
380 /// \~english @par Type
382 /// \~english @par Detail
383 /// To generate a TimerCtrl class. \n
384 /// After the constructor, be sure to call the Initialize. \n
385 /// \~english @see ~TimerCtrl, Initialize
386 ////////////////////////////////////////////////////////////////////////////////////
389 /////////////////////////////////////////////////////////////////////////////////////
390 /// \ingroup TimerCtrl
391 /// \~english @par Summary
392 /// Constructor, called when the class is instantiated.
393 /// \~english @param [in] ntimers
394 /// UI_32 - number of timers objects in the pool
395 /// \~english @retval None
396 /// \~english @par Preconditions
398 /// \~english @par Change of the internal state
399 /// - initialize var m_hApp and m_nTimersMax
400 /// \~english @par Causes of failures
402 /// \~english @par Classification
404 /// \~english @par Type
406 /// \~english @par Detail
407 /// To generate a TimerCtrl class. \n
408 /// After the constructor, be sure to call the Initialize. \n
409 /// \~english @see ~TimerCtrl, Initialize
410 ////////////////////////////////////////////////////////////////////////////////////
411 TimerCtrl(UI_32 ntimers); // NOLINT (runtime/explicit)
413 /////////////////////////////////////////////////////////////////////////////////////
414 /// \ingroup Initialize
415 /// \~english @par Summary
416 /// Initialize the class after instantiation.
417 /// \~english @param [in] hApp
418 /// HANDLE - HANDLE to you applications hApp.
419 /// \~english @retval None
420 /// \~english @par Preconditions
422 /// \~english @par Change of the internal state
423 /// - initialize var m_hApp and m_aTimers
424 /// \~english @par Causes of failures
426 /// \~english @par Classification
428 /// \~english @par Type
430 /// \~english @par Detail
431 /// The function is to initialize the member val of the class with param hApp,\n
432 /// if hApp is not null, then set m_hApp with hApp and initialize m_aTimers.
433 /// \~english @see ~TimerCtrl, Initialize
434 ////////////////////////////////////////////////////////////////////////////////////
435 VOID Initialize(HANDLE hApp);
437 /////////////////////////////////////////////////////////////////////////////////////
438 /// \ingroup Shutdown
439 /// \~english @par Summary
440 /// handle something when shut down timer control.
441 /// \~english @param None
442 /// \~english @retval None
443 /// \~english @par Preconditions
444 /// - That has been initialized in the Initialize()..
445 /// \~english @par Change of the internal state
446 /// - Clear m_aTimer,shut down timer in m_rTimer and delete it.clear m_rTimer.
447 /// \~english @par Causes of failures
449 /// \~english @par Classification
451 /// \~english @par Type
453 /// \~english @par Detail
454 /// Completely shuts down the timer control, this method calls Stop, cleans up. You must call
455 /// Initialize again if you want reuse this class.
456 /// \~english @see ~TimerCtrl, Initialize
457 ////////////////////////////////////////////////////////////////////////////////////
460 /////////////////////////////////////////////////////////////////////////////////////
461 /// \ingroup CreateTimer
462 /// \~english @par Summary
463 /// get a timer control from pool
464 /// \~english @param [in] CbFn
465 /// CbFn - Pointer to a callback function to be called when the timer expires
466 /// \~english @retval Timer id - If id is in m_aTimers
467 /// \~english @retval 0 - If id is not in m_aTimers
468 /// \~english @par Preconditions
469 /// - That has been initialized in the Initialize().
470 /// \~english @par Change of the internal state
471 /// - insert one Timer to m_rTimers
472 /// \~english @par Causes of failures
474 /// \~english @par Classification
476 /// \~english @par Type
478 /// \~english @par Detail
479 /// gets a the first id from m_aTimers if m_aTimer is not empty, using this id to create a timer,\n
480 /// put this timer into m_rTimers,and return the id.
481 /// \~english @see DeleteTimer
482 ////////////////////////////////////////////////////////////////////////////////////
483 UI_32 CreateTimer(CbFuncPtr CbFn);
485 /////////////////////////////////////////////////////////////////////////////////////
486 /// \ingroup DeleteTimer
487 /// \~english @par Summary
488 /// delete a timer from m_rTimers using the param.
489 /// \~english @param [in] id
490 /// UI_32 - timer id that you want to delete
491 /// \~english @retval Timer id -If id is in m_aTimers
492 /// \~english @retval 0 - If id is not in m_aTimers
493 /// \~english @par Preconditions
494 /// - That has been initialized in the Initialize().
495 /// \~english @par Change of the internal state
496 /// - delete one Timer to m_rTimers that id is the param.\n
497 /// and put id of the timer into m_aTimers.
498 /// \~english @par Causes of failures
500 /// \~english @par Classification
502 /// \~english @par Type
504 /// \~english @par Detail
505 /// delete your timer and returns it's id to the pool of timers.
506 /// \~english @see CreateTimer
507 ////////////////////////////////////////////////////////////////////////////////////
508 UI_32 DeleteTimer(UI_32 id);
510 /////////////////////////////////////////////////////////////////////////////////////
511 /// \ingroup SetTimer
512 /// \~english @par Summary
513 /// Sets the timer timeout values
514 /// \~english @param [in] id
515 /// UI_32 - timer id that you want to set
516 /// \~english @param [in] ss
517 /// UI_32 - Start time in seconds
518 /// \~english @param [in] sms
519 /// UI_32 - Start time in milliseconds
520 /// \~english @param [in] rs
521 /// UI_32 - Repeat time in seconds
522 /// \~english @param [in] rms
523 /// UI_32 - Repeat time in milliseconds
524 /// \~english @retval Timer id - If id is in m_aTimers
525 /// \~english @retval 0 - If id is not in m_aTimers
526 /// \~english @par Preconditions
527 /// - That has been initialized in the Initialize().
528 /// \~english @par Change of the internal state
529 /// - set the timer infomation in m_rTimers with ss, sms, rs, rms
530 /// \~english @par Causes of failures
532 /// \~english @par Classification
534 /// \~english @par Type
536 /// \~english @par Detail
537 /// using ss, sms, rs, rms to set the timer infomation, timer'is is param.
538 /// \~english @see None
539 ////////////////////////////////////////////////////////////////////////////////////
540 UI_32 SetTimer(UI_32 id, UI_32 ss, UI_32 sms, UI_32 rs, UI_32 rms);
542 /////////////////////////////////////////////////////////////////////////////////////
543 /// \ingroup StartTimer
544 /// \~english @par Summary
545 /// Sets the timer timeout values and starts the timer.
546 /// \~english @param [in] id
547 /// UI_32 - timer id that you want to start
548 /// \~english @param [in] ss
549 /// UI_32 - Timeout expiration time(sec)
550 /// \~english @param [in] sms
551 /// UI_32 - Timeout expiration time(nano sec)
552 /// \~english @param [in] rs
553 /// UI_32 - Timeout expiration time at the time of repeat(sec)
554 /// \~english @param [in] rms
555 /// UI_32 - Timeout expiration time at the time of repeat(nano sec)
556 /// \~english @retval Timer id - If id is in m_aTimers
557 /// \~english @retval 0 - If id is not in m_aTimers
558 /// \~english @par Preconditions
559 /// - That has been initialized in the Initialize().
560 /// \~english @par Change of the internal state
562 /// \~english @par Causes of failures
564 /// \~english @par Classification
566 /// \~english @par Type
568 /// \~english @par Detail
569 /// In the case of initialization completion state, start the timer that id is the first param. \n
570 /// After timer start, again, if you start the timer, it does not work guarantee.
571 /// \~english @see Stop
572 ////////////////////////////////////////////////////////////////////////////////////
573 UI_32 StartTimer(UI_32 id, UI_32 ss, UI_32 sms, UI_32 rs, UI_32 rms);
575 /////////////////////////////////////////////////////////////////////////////////////
576 /// \ingroup StartTimerMulti
577 /// \~english @par Summary
578 /// The start of the timer by specifying a timer value information and reinitialize timer id.
579 /// \~english @param [in] id
580 /// UI_32 - timer id that you want to start
581 /// \~english @param [in] ss
582 /// UI_32 - Timeout expiration time(sec)
583 /// \~english @param [in] sms
584 /// UI_32 - Timeout expiration time(nano sec)
585 /// \~english @param [in] rs
586 /// UI_32 - Timeout expiration time at the time of repeat(sec)
587 /// \~english @param [in] rms
588 /// UI_32 - Timeout expiration time at the time of repeat(nano sec)
589 /// \~english @param [in] subId
590 /// UI_32 - using subId to reinitialize timer id
591 /// \~english @retval Timer id - If id is in m_aTimers
592 /// \~english @retval 0 - If id is not in m_aTimers
593 /// \~english @par Preconditions
594 /// - That has been initialized in the Initialize().
595 /// \~english @par Change of the internal state
597 /// \~english @par Causes of failures
599 /// \~english @par Classification
601 /// \~english @par Type
603 /// \~english @par Detail
604 /// Finds the timer by specifying, shut down the timer, \n
605 /// and reinitialize it using new id of this timer and starts the timer
606 /// \~english @see Stop
607 ////////////////////////////////////////////////////////////////////////////////////
608 UI_32 StartTimerMulti(UI_32 id, UI_32 ss, UI_32 sms, UI_32 rs, UI_32 rms, UI_32 subId);
610 /////////////////////////////////////////////////////////////////////////////////////
611 /// \ingroup StartTimer
612 /// \~english @par Summary
614 /// \~english @param [in] id
615 /// UI_32 - timer id that you want to start
616 /// \~english @retval Timer id - If id is in m_aTimers
617 /// \~english @retval 0 - If id is in not m_aTimers
618 /// \~english @par Preconditions
619 /// - That has been initialized in the Initialize().
620 /// - Set the timeout value in SetTimer().
621 /// \~english @par Change of the internal state
623 /// \~english @par Causes of failures
625 /// \~english @par Classification
627 /// \~english @par Type
629 /// \~english @par Detail
630 /// In the case of initialization completion state, \n
631 /// start of the timer by specifying a timer value information.
632 /// \~english @see SetTime, Stop
633 ////////////////////////////////////////////////////////////////////////////////////
634 UI_32 StartTimer(UI_32 id);
636 /////////////////////////////////////////////////////////////////////////////////////
637 /// \ingroup StopTimer
638 /// \~english @par Summary
640 /// \~english @param [in] id
641 /// UI_32 - timer id that you want to stop
642 /// \~english @retval Timer id - If id is in m_aTimers
643 /// \~english @retval 0 - If id is not in m_aTimers
644 /// \~english @par Preconditions
645 /// - That has been initialized in the Initialize().
646 /// - Set the timeout value in SetTimer().
647 /// \~english @par Change of the internal state
649 /// \~english @par Causes of failures
651 /// \~english @par Classification
653 /// \~english @par Type
655 /// \~english @par Detail
656 /// In the case of start completion state, \n
657 /// stop of the timer by specifying a timer value information
658 /// \~english @see SetTimer, StartTimer
659 ////////////////////////////////////////////////////////////////////////////////////
660 UI_32 StopTimer(UI_32 id);
664 UI_32 m_nTimersMax; ///
665 std::list<UI_32> m_aTimers; ///
666 std::map<UI_32, Timer*> m_rTimers; ///
670 #endif /* SS_SYSTEM_TIMER_H_ */ // NOLINT (build/header_guard)