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 /// \ingroup tag_NSFramework
19 /// \brief Application framework's core structures and data types.
20 ///////////////////////////////////////////////////////////////////////////////
23 * @file frameworkunified_timer.h
24 * @brief \~english Application framework's core structures and data types.
27 /** @addtogroup BaseSystem
30 /** @addtogroup native_service
34 /** @addtogroup framework_unified
35 * @ingroup native_service
38 /** @addtogroup framework
39 * @ingroup native_service
42 #ifndef __NSFRAMEWORK_NFRAMEWORKCORE_FRAMEWORKUNIFIEDTIMER__ // NOLINT (build/header_guard)
43 #define __NSFRAMEWORK_NFRAMEWORKCORE_FRAMEWORKUNIFIEDTIMER__
45 #include <native_service/frameworkunified_types.h>
46 #include <native_service/frameworkunified_framework_if.h>
48 ////////////////////////////////////////////////////////////////////////////////////////////
49 /// \ingroup FrameworkunifiedAttachTimerCallback
50 /// \~english @par Brief
51 /// Attach a callback to hApp dispatcher that will get called initially at initNS nanoseconds,
52 /// and then repeatedly at repeatNS nanoseconds
53 /// \~english @param[in] hApp
54 /// HANDLE - hApp parent framework HANDLE
55 /// \~english @param[in] initMS
56 /// UI_32 - milliseconds to begin triggering callback(0 to 4294967295)
57 /// \~english @param[in] repeatMS
58 /// UI_32 - milliseconds between repeated triggerings of callback(0 to 4294967295)
59 /// \~english @param[in] CbFn
60 /// CbFuncPtr - Callback to be triggered
61 /// \~english @retval Handle to the timer object or NULL on failure
62 /// \~english @par Preconditons
63 /// - hApp has already gotten the dispatcher(return NULL)
64 /// \~english @par Change of internal status
65 /// - The internal state is not changed.
66 /// \~english @par Conditions of processing failure
67 /// - hApp is not application HNADLE(return NULL)
68 /// - eFrameworkunifiedStatusFail if the hApp specified in the arguments is not appropriate (not valid) [NULL]
69 /// - CbFn is NULL(return NULL))
70 /// - If the send message queue handle specified in the argument (hApp) to itself is NULL [NULL]
71 /// - Failed to create epoll instances (epoll_create1/eventfd) for timer event monitoring [NULL]
72 /// - Failed to create a timer event monitor thread (pthread_create) [NULL]
73 /// - When acquisition (malloc) of the timer-management-information area fails [NULL]
74 /// - If the send message queue type to the handle (hApp) specified in the parameter is neither send nor receive, [NULL]
75 /// - Failed to generate timers (timerfd_create) [NULL]
76 /// - Failed to register file descriptors for timer notification to epoll instances (epoll_ctl) [NULL]
77 /// - Failed to start/stop timer (timerfd_settime) [NULL]
78 /// \~english @par Detail
79 /// After registering the callback functions for timer events in the Dispatcher specified by the hApp arguments,
80 /// it creates and starts a timer and returns its handles.\n
81 /// Dispatcher executes callback functions when the timers generated by the APIs fire.\n
82 /// The application shall use this API when there is a process to be executed once or repeatedly in response to a specified time elapsed.
84 /// Please note the following points when using this API for application.\n
85 /// - 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.
86 /// - If the application specifies a repeatMS of zero, the callback is executed only once.
87 /// - Since the timer handle is a FrameworkunifiedAttachTimerCallback return value, the callback cannot be set twice with the same timer handle.
88 /// - If multiple calls are made with the same application handle, the second and subsequent callbacks are not set,
89 /// and the first registered callback function is started at the last registered timer interval.
90 /// - Create a thread for sending messages, but do not make dynamic calls because the thread is not destroyed even if FrameworkunifiedDetachTimerCallback is executed.
91 /// \~english @par Classification
92 /// \~english @par Type
94 /// \~english @see FrameworkunifiedDetachTimerCallback
95 /// \~english @todo needs to clarify this API require initMS except 0
96 ////////////////////////////////////////////////////////////////////////////////////////////
97 HANDLE FrameworkunifiedAttachTimerCallback(HANDLE hApp, UI_32 initMS, UI_32 repeatMS, CbFuncPtr CbFn);
100 ////////////////////////////////////////////////////////////////////////////////////////////
101 /// \ingroup FrameworkunifiedDetachTimerCallback
102 /// \~english @par Brief
103 /// Detach callback and deallocate a timer previous created with FrameworkunifiedAttachTimerCallback
104 /// \~english @param[in] hApp
105 /// HANDLE - hApp parent framework HANDLE
106 /// \~english @param[in] hTimer
107 /// HANDLE - timer HANDLE
108 /// \~english @retval HANDLE HANDLE used to communicate with child. NULL...failure, otherwize...success
109 /// \~english @retval eFrameworkunifiedStatusOK
110 /// \~english @retval eFrameworkunifiedStatusFail(not happened)
111 /// \~english @retval eFrameworkunifiedStatusInvldParam
112 /// \~englsih @par Preconditions
113 /// - Timer is dispatched for hApp Callback
114 /// \~englsih @par Change of internal state
115 /// - The internal state is not changed.
116 /// \~english @par Conditions of processing failure
117 /// - hApp is not application HNADLE(eFrameworkunifiedStatusInvldParam)
118 /// - eFrameworkunifiedStatusFail if the hApp specified in the arguments is not appropriate (not valid) [eFrameworkunifiedStatusInvldParam]
119 /// - hTimer is NULL(eFrameworkunifiedStatusInvldParam)
120 /// - When the timer has been stopped by the timer administrative info of the timer handle specified by the arguments, [eFrameworkunifiedStatusFail]
121 /// - When the timer administrative information of the timer handle specified by the arguments is NULL, [eFrameworkunifiedStatusFail]
122 /// - Failed to stop the timer (timerfd_settime) [eFrameworkunifiedStatusFail]
123 /// - If a callback for the timer event is not registered in the Dispatcher specified by the hApp, [eFrameworkunifiedStatusFail]
124 /// \~english @par Detail
125 /// Stops the timer (hTimer) specified by the argument and registrations the callback functions
126 /// for timer events from the Dispacther specified by the argument hApp.
128 /// Please note the following points when using this API for application.\n
129 /// - Operation is not guaranteed if a different handle is set for the timer handle.
130 /// - If a normal timer handle and an invalid application handle are set, only the timer information is deleted, resulting in an inconsistent state.
131 /// \~english @par Classification
132 /// \~english @par Type
134 /// \~english @see FrameworkunifiedAttachTimerCallback
135 ////////////////////////////////////////////////////////////////////////////////////////////
136 EFrameworkunifiedStatus FrameworkunifiedDetachTimerCallback(HANDLE hApp, HANDLE hTimer);
138 #endif // NOLINT (build/header_guard)