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.
19 * @brief \~english APIs to create, delete and use Native Service timers .
22 /** @addtogroup BaseSystem
25 /** @addtogroup native_service
29 /** @addtogroup framework_unified
30 * @ingroup native_service
33 /** @addtogroup native
34 * @ingroup framework_unified
37 #ifndef __NATIVESERVICES_TIMER_H__ // NOLINT (build/header_guard)
38 #define __NATIVESERVICES_TIMER_H__
40 #include <native_service/frameworkunified_types.h>
47 #define TIMER_QUE "TIMER"
49 #define MAX_SERVICE_NAME 15
51 /// \brief Timer Function Pointer definition
52 /// Detailed description of the class
53 typedef void (*TimerCb)(UI_16 cmd);
55 /// \brief Timer info, defines the initial
56 /// start of a timer, the repeat timer
57 /// values and the cmd id for a timer
58 typedef struct _NSTimerInfo {
70 /// \brief Enum Types for valid Callback Mechanisms for
72 typedef enum _NSTimerCallbackMechanism {
74 } eNSTimerCallbackMechanism;
76 /// \brief Helper methods that convert time provided in MS.
79 /////////////////////////////////////////////////////////////////////////////////////
80 /// \ingroup WholeSeconds
81 /// \~english @par Brief
82 /// Converts a time value in milliseconds (ms) to a time value in secods (s).
83 /// \~english @param [in] ms
84 /// UI_32 - Time value in milliseconds(0 to ULONG_MAX)
85 /// \~english @retval Time value in seconds
86 /// \~english @par Preconditons
88 /// \~english @par Change of internal status
89 /// - The internal state is not changed.
90 /// \~english @par Conditions of processing failure
92 /// \~english @par Detail
93 /// This function converts a time value in ms to a time value in s and returns it.\n
94 /// For example, 12345ms obtains 12s as the conversion result.
95 /// \~english @par Classification
97 /// \~english @par Type
102 /// \~english @par Brief
103 /// Get the number of whole seconds in the milsecond number that was passed.
104 /// \~english @param[in] ms
105 /// UI_32 - time value in mil seconds
106 /// \~english @retval Number of whole seconds in the number passed.
107 /// \~english @par Preconditons
108 /// \~english @par Change of internal status
109 /// \~english @par Conditions of processing failure
110 /// \~english @par Detail
111 /// \~english @par Classification
112 /// \~english @par Type
115 /////////////////////////////////////////////////////////////////////////////////////
117 //UI_32 WholeSeconds(UI_32 ms);
118 time_t WholeSeconds(UI_32 ms);
120 /////////////////////////////////////////////////////////////////////////////////////
121 /// \ingroup RemainderMs
122 /// \~english @par Brief
123 /// Get the number of remaining milseconds out of whole second for the number passed.
124 /// \~english @param[in] ms
125 /// UI_32 - time value in mil seconds
126 /// \~english @retval Number of remaining mil seconds in the number passed.
127 /// \~english @par Preconditons
129 /// \~english @par Change of internal status
130 /// - The internal state is not changed.
131 /// \~english @par Conditions of processing failure
133 /// \~english @par Detail
134 /// This function returns the time value in ms of the remainder from converting the time value in ms to the time value in s.\n
135 /// For example, 12345ms obtains 345ms as the conversion result.
136 /// \~english @par Classification
137 /// \~english @par Type
140 /////////////////////////////////////////////////////////////////////////////////////
141 UI_32 RemainderMs(UI_32 ms);
143 /////////////////////////////////////////////////////////////////////////////////////
145 /// \~english @par Brief
146 /// Converts mil seconds to nano seconds.
147 /// \~english @param[in] ms
148 /// UI_32 - time value in mil seconds
149 /// \~english @retval Number of nano seconds there are in mil seconds in the number passed.
150 /// \~english @par Preconditons
152 /// \~english @par Change of internal status
153 /// - The internal state is not changed.
154 /// \~english @par Conditions of processing failure
156 /// \~english @par Detail
157 /// This function converts a time value in ms to a time value in ns and returns it.\n
158 /// For example, 1234ms obtains 1234000000ns as the conversion result.
159 /// \~english @par Classification
160 /// \~english @par Type
163 /////////////////////////////////////////////////////////////////////////////////////
164 UI_64 MSToNS(UI_32 ms);
166 ////////////////////////////////////////////////////////////////////////////////////////////
167 /// \ingroup NS_TimerCreate
168 /// \~english @par Brief
169 /// to create an instance of a timer object, and start it
170 /// \~english @param[in] timer_info
171 /// NSTimerInfo - timer value represents an absolute expiration timeout
172 /// \~english @param[in] cbMech
173 /// eNSTimerCallbackMechanism - CALLBACKMECHANISM_ENUM - specifies the callback mechanism associated with the
175 /// CALLBACK_MESSAGE will send a message to a message queue
176 /// \~english @param[in] sndMqHndl
177 /// HANDLE - implies a MESSAGE QUE HANDLE generated by McOpenSender() is specified
178 /// \~english @retval Handle to the timer object or NULL on failure
179 /// \~english @par Preconditons
181 /// \~english @par Change of internal status
182 /// - The internal state is not changed.
183 /// \~english @par Conditions of processing failure
184 /// - If HANDLE(sndMqHndl) is NULL, [NULL]
185 /// - If the Callback mechanism (cbMech) specified in the arguments is not CALLBACK_MESSAGE [NULL]
186 /// - If thread creation fails (reateTimerMonitoringThread(); returns eFrameworkunifiedStatusFail) [NULL]
187 /// - Unable to allocate memory for timer handle structures [NULL]
188 /// - Memory cannot be allocated for the timer-information struct. [NULL]
189 /// - When the message queue name of the handle (sndMqHndl) specified in the arguments is NULL,[NULL]
190 /// - If a system call (such as epoll_ctl()) is in error,[NULL]
191 /// \~english @par Detail
192 /// Creates an instance of a timer object, sends a CALLBACK_MESSAGE message to the message queue, and starts the timer.\n
193 /// When McOpenSender() is executed to execute NS_TimerCreate, the handles should be closed if not needed.
194 /// \~english @par Classification
195 /// \~english @par Type
196 /// \~english @see NS_TimerDelete,NS_TimerSetTime
197 ////////////////////////////////////////////////////////////////////////////////////////////
198 HANDLE NS_TimerCreate(NSTimerInfo timer_info, eNSTimerCallbackMechanism cbMech, HANDLE sndMqHndl);
200 ////////////////////////////////////////////////////////////////////////////////////////////
201 /// \ingroup NS_TimerDelete
202 /// \~english @par Brief
203 /// to delete an instance of a timer object
204 /// \~english @param[in] hTimer
205 /// HANDLE - a timer handle that was created via NS_TimerCreate
206 /// \~english @retval EFrameworkunifiedStatus indicates if the timer handle was delete successfully
207 /// \~english @retval eFrameworkunifiedStatusOK
208 /// \~english @retval eFrameworkunifiedStatusFail
209 /// \~english @retval eFrameworkunifiedStatusInvldParam
210 /// \~english @par Preconditons
211 /// - NS_TimerCreate has generated a HANDLE of timers
212 /// \~english @par Change of internal status
213 /// - The internal state is not changed.
214 /// \~english @par Conditions of processing failure
215 /// - If HANDLE(hTimer) is NULL,[eFrameworkunifiedStatusInvldParam]
216 /// - Initializes the state. [eFrameworkunifiedStatusFail]
217 /// - Invalid timed objects for HANDLE(hTimer specified by arguments:[eFrameworkunifiedStatusInvldParam]
218 /// - If semaphoring fails, [eFrameworkunifiedStatusFail]
219 /// \~english @par Detail
220 /// If the timer is set, the timer is stopped.\n
221 /// Delete an instance of a timer object.
222 /// \~english @par Classification
223 /// \~english @par Type
224 /// \~english @see NS_TimerCreate, NS_TimerSetTime
225 ////////////////////////////////////////////////////////////////////////////////////////////
226 EFrameworkunifiedStatus NS_TimerDelete(HANDLE hTimer);
228 ////////////////////////////////////////////////////////////////////////////////////////////
229 /// \ingroup NS_TimerSetTime
230 /// \~english @par Brief
231 /// to start or stop a timer by setting the time interval associated
232 /// with a timer, value of 0 in t_sec & t_nsec, will stop the timer.
233 /// \~english @param[in] hTimer
234 /// HANDLE - handle to timer that your specifying the timer to be set
235 /// \~english @param[in] timer_info
236 /// NSTimerInfo - timer value represents an absolute expiration timeout
237 /// \~english @retval EFrameworkunifiedStatus indicates if the timer info was set successfully
238 /// \~english @retval eFrameworkunifiedStatusOK
239 /// \~english @retval eFrameworkunifiedStatusInvldHandle
240 /// \~english @retval eFrameworkunifiedStatusFail
241 /// \~english @par Preconditons
242 /// the timer must have already been created with NS_TimerCreate
243 /// \~english @par Change of internal status
244 /// - The internal state is not changed.
245 /// \~english @par Conditions of processing failure
246 /// - If HANDLE(hTimer) is NULL,[eFrameworkunifiedStatusInvldHandle]
247 /// - Initializes the state. [eFrameworkunifiedStatusFail]
248 /// - Retrieving timers fails [eFrameworkunifiedStatusFail]
249 /// \~english @par Detail
250 /// When the timer information (t_sec and t_nsec) is 0, the timer is stopped.\n
251 /// If it is not 0, the timer is started based on the timer information.\n
252 /// The hTimer must have been created with NS_TimerCreate.
253 /// \~english @par Classification
254 /// \~english @par Type
255 /// \~english @see NS_TimerCreate, NS_TimerGetTime
256 ////////////////////////////////////////////////////////////////////////////////////////////
257 EFrameworkunifiedStatus NS_TimerSetTime(HANDLE hTimer, NSTimerInfo timer_info);
259 ////////////////////////////////////////////////////////////////////////////////////////////
260 /// \ingroup NS_TimerGetTime
261 /// \~english @par Brief
262 /// to retrieve the time until a timer expires
263 /// \~english @param[in] hTimer
264 /// HANDLE - handle to timer that your trying to get information about
265 /// \~english @param[out] timer_info
266 /// NSTimerInfo* - a structure to store the delay time until the timer expires
267 /// \~english @retval EFrameworkunifiedStatus indicates if the timer info was get successfully
268 /// \~english @retval eFrameworkunifiedStatusOK
269 /// \~english @retval eFrameworkunifiedStatusInvldHandle
270 /// \~english @retval eFrameworkunifiedStatusFail
271 /// \~english @par Preconditons
272 /// - NS_TimerCreate has generated a HANDLE of timers
273 /// \~english @par Change of internal status
274 /// - The internal state is not changed.
275 /// \~english @par Conditions of processing failure
276 /// - If HANDLE(hTimer) is NULL,[eFrameworkunifiedStatusInvldHandle]
277 /// - If the timer_info specified in the arguments is NULL,... [eFrameworkunifiedStatusInvldHandle]
278 /// - Initializes the state. [eFrameworkunifiedStatusFail]
279 /// - If the timerdelete fails.... [eFrameworkunifiedStatusFail]
280 /// \~english @par Detail
281 /// Gets the time until the timer expires.
282 /// \~english @par Classification
283 /// \~english @par Type
284 /// \~english @see NS_TimerCreate, NS_TimerSetTime
285 ////////////////////////////////////////////////////////////////////////////////////////////
286 EFrameworkunifiedStatus NS_TimerGetTime(HANDLE hTimer, NSTimerInfo *timer_info);
288 ////////////////////////////////////////////////////////////////////////////////////////////
289 /// \ingroup NS_TimerDebugOn
290 /// \~english @par Brief
291 /// to make a flag for the debugging process. for debug.
292 /// \~english @param[in] FlagState
293 /// BOOL - DebugFlag state
294 /// \~english @retval none
295 /// \~english @par Preconditons
297 /// \~english @par Change of internal status
298 /// - The internal state is not changed.
299 /// \~english @par Conditions of processing failure
301 /// \~english @par Detail
302 /// Sets the debug flag specified by the argument.\n
303 /// However, if the set flag is the same as the flag specified in the argument, no operation is performed.
304 /// \~english @par Classification
305 /// \~english @par Type
306 /// \~english @see none
307 ////////////////////////////////////////////////////////////////////////////////////////////
308 void NS_TimerDebugOn(BOOL FlagState);
313 #endif /* __NATIVESERVICES_TIMER_H__ */ // NOLINT (build/header_guard)