diff options
Diffstat (limited to 'nsframework/framework_unified/client/include/native_service/frameworkunified_timer.h')
| -rw-r--r-- | nsframework/framework_unified/client/include/native_service/frameworkunified_timer.h | 143 |
1 files changed, 143 insertions, 0 deletions
diff --git a/nsframework/framework_unified/client/include/native_service/frameworkunified_timer.h b/nsframework/framework_unified/client/include/native_service/frameworkunified_timer.h new file mode 100644 index 00000000..7a3c762e --- /dev/null +++ b/nsframework/framework_unified/client/include/native_service/frameworkunified_timer.h @@ -0,0 +1,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) +/** @}*/ +/** @}*/ +/** @}*/ +/** @}*/ +//@} |