1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
|
/*
* @copyright Copyright (c) 2016-2020 TOYOTA MOTOR CORPORATION.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
///////////////////////////////////////////////////////////////////////////////
/// \ingroup tag_NSFramework
/// \brief Application framework's core structures and data types.
///////////////////////////////////////////////////////////////////////////////
//@{
/**
* @file frameworkunified_timer.h
* @brief \~english Application framework's core structures and data types.
*
*/
/** @addtogroup BaseSystem
* @{
*/
/** @addtogroup native_service
* @ingroup BaseSystem
* @{
*/
/** @addtogroup framework_unified
* @ingroup native_service
* @{
*/
/** @addtogroup framework
* @ingroup native_service
* @{
*/
#ifndef __NSFRAMEWORK_NFRAMEWORKCORE_FRAMEWORKUNIFIEDTIMER__ // NOLINT (build/header_guard)
#define __NSFRAMEWORK_NFRAMEWORKCORE_FRAMEWORKUNIFIEDTIMER__
#include <native_service/frameworkunified_types.h>
#include <native_service/frameworkunified_framework_if.h>
////////////////////////////////////////////////////////////////////////////////////////////
/// \ingroup FrameworkunifiedAttachTimerCallback
/// \~english @par Brief
/// Attach a callback to hApp dispatcher that will get called initially at initNS nanoseconds,
/// and then repeatedly at repeatNS nanoseconds
/// \~english @param[in] hApp
/// HANDLE - hApp parent framework HANDLE
/// \~english @param[in] initMS
/// UI_32 - milliseconds to begin triggering callback(0 to 4294967295)
/// \~english @param[in] repeatMS
/// UI_32 - milliseconds between repeated triggerings of callback(0 to 4294967295)
/// \~english @param[in] CbFn
/// CbFuncPtr - Callback to be triggered
/// \~english @retval Handle to the timer object or NULL on failure
/// \~english @par Preconditons
/// - hApp has already gotten the dispatcher(return NULL)
/// \~english @par Change of internal status
/// - The internal state is not changed.
/// \~english @par Conditions of processing failure
/// - hApp is not application HNADLE(return NULL)
/// - eFrameworkunifiedStatusFail if the hApp specified in the arguments is not appropriate (not valid) [NULL]
/// - CbFn is NULL(return NULL))
/// - If the send message queue handle specified in the argument (hApp) to itself is NULL [NULL]
/// - Failed to create epoll instances (epoll_create1/eventfd) for timer event monitoring [NULL]
/// - Failed to create a timer event monitor thread (pthread_create) [NULL]
/// - When acquisition (malloc) of the timer-management-information area fails [NULL]
/// - If the send message queue type to the handle (hApp) specified in the parameter is neither send nor receive, [NULL]
/// - Failed to generate timers (timerfd_create) [NULL]
/// - Failed to register file descriptors for timer notification to epoll instances (epoll_ctl) [NULL]
/// - Failed to start/stop timer (timerfd_settime) [NULL]
/// \~english @par Detail
/// After registering the callback functions for timer events in the Dispatcher specified by the hApp arguments,
/// it creates and starts a timer and returns its handles.\n
/// Dispatcher executes callback functions when the timers generated by the APIs fire.\n
/// The application shall use this API when there is a process to be executed once or repeatedly in response to a specified time elapsed.
/// \~english @par
/// Please note the following points when using this API for application.\n
/// - If the application specifies a initMS of 0, a timer is created and handles are returned, but the callback is not executed because the timer is stopped.
/// - If the application specifies a repeatMS of zero, the callback is executed only once.
/// - Since the timer handle is a FrameworkunifiedAttachTimerCallback return value, the callback cannot be set twice with the same timer handle.
/// - If multiple calls are made with the same application handle, the second and subsequent callbacks are not set,
/// and the first registered callback function is started at the last registered timer interval.
/// - Create a thread for sending messages, but do not make dynamic calls because the thread is not destroyed even if FrameworkunifiedDetachTimerCallback is executed.
/// \~english @par Classification
/// \~english @par Type
/// Open Close
/// \~english @see FrameworkunifiedDetachTimerCallback
/// \~english @todo needs to clarify this API require initMS except 0
////////////////////////////////////////////////////////////////////////////////////////////
HANDLE FrameworkunifiedAttachTimerCallback(HANDLE hApp, UI_32 initMS, UI_32 repeatMS, CbFuncPtr CbFn);
////////////////////////////////////////////////////////////////////////////////////////////
/// \ingroup FrameworkunifiedDetachTimerCallback
/// \~english @par Brief
/// Detach callback and deallocate a timer previous created with FrameworkunifiedAttachTimerCallback
/// \~english @param[in] hApp
/// HANDLE - hApp parent framework HANDLE
/// \~english @param[in] hTimer
/// HANDLE - timer HANDLE
/// \~english @retval HANDLE HANDLE used to communicate with child. NULL...failure, otherwize...success
/// \~english @retval eFrameworkunifiedStatusOK
/// \~english @retval eFrameworkunifiedStatusFail(not happened)
/// \~english @retval eFrameworkunifiedStatusInvldParam
/// \~englsih @par Preconditions
/// - Timer is dispatched for hApp Callback
/// \~englsih @par Change of internal state
/// - The internal state is not changed.
/// \~english @par Conditions of processing failure
/// - hApp is not application HNADLE(eFrameworkunifiedStatusInvldParam)
/// - eFrameworkunifiedStatusFail if the hApp specified in the arguments is not appropriate (not valid) [eFrameworkunifiedStatusInvldParam]
/// - hTimer is NULL(eFrameworkunifiedStatusInvldParam)
/// - When the timer has been stopped by the timer administrative info of the timer handle specified by the arguments, [eFrameworkunifiedStatusFail]
/// - When the timer administrative information of the timer handle specified by the arguments is NULL, [eFrameworkunifiedStatusFail]
/// - Failed to stop the timer (timerfd_settime) [eFrameworkunifiedStatusFail]
/// - If a callback for the timer event is not registered in the Dispatcher specified by the hApp, [eFrameworkunifiedStatusFail]
/// \~english @par Detail
/// Stops the timer (hTimer) specified by the argument and registrations the callback functions
/// for timer events from the Dispacther specified by the argument hApp.
/// \~english @par
/// Please note the following points when using this API for application.\n
/// - Operation is not guaranteed if a different handle is set for the timer handle.
/// - If a normal timer handle and an invalid application handle are set, only the timer information is deleted, resulting in an inconsistent state.
/// \~english @par Classification
/// \~english @par Type
/// Open Close
/// \~english @see FrameworkunifiedAttachTimerCallback
////////////////////////////////////////////////////////////////////////////////////////////
EFrameworkunifiedStatus FrameworkunifiedDetachTimerCallback(HANDLE hApp, HANDLE hTimer);
#endif // NOLINT (build/header_guard)
/** @}*/
/** @}*/
/** @}*/
/** @}*/
//@}
|
