/* * @copyright Copyright (c) 2016-2019 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 #include //////////////////////////////////////////////////////////////////////////////////////////// /// \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) /** @}*/ /** @}*/ /** @}*/ /** @}*/ //@}