nsframework/framework_unified/client/include/native_service/frameworkunified_timer.h

   1 /*
   2  * @copyright Copyright (c) 2016-2020 TOYOTA MOTOR CORPORATION.
   3  *
   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
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  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.
  15  */
  16
  17 ///////////////////////////////////////////////////////////////////////////////
  18 /// \ingroup  tag_NSFramework
  19 /// \brief    Application framework's core structures and data types.
  20 ///////////////////////////////////////////////////////////////////////////////
  21 //@{
  22 /**
  23  * @file frameworkunified_timer.h
  24  * @brief \~english Application framework's core structures and data types.
  25  *
  26  */
  27 /** @addtogroup BaseSystem
  28  *  @{
  29  */
  30 /** @addtogroup native_service
  31  *  @ingroup BaseSystem
  32  *  @{
  33  */
  34 /** @addtogroup framework_unified
  35  *  @ingroup native_service
  36  *  @{
  37  */
  38 /** @addtogroup framework
  39  *  @ingroup native_service
  40  *  @{
  41  */
  42 #ifndef __NSFRAMEWORK_NFRAMEWORKCORE_FRAMEWORKUNIFIEDTIMER__  // NOLINT  (build/header_guard)
  43 #define __NSFRAMEWORK_NFRAMEWORKCORE_FRAMEWORKUNIFIEDTIMER__
  44
  45 #include <native_service/frameworkunified_types.h>
  46 #include <native_service/frameworkunified_framework_if.h>
  47
  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.
  83 /// \~english @par
  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
  93 ///          Open Close
  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);
  98
  99
 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.
 127 /// \~english @par
 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
 133 ///          Open Close
 134 /// \~english @see FrameworkunifiedAttachTimerCallback
 135 ////////////////////////////////////////////////////////////////////////////////////////////
 136 EFrameworkunifiedStatus FrameworkunifiedDetachTimerCallback(HANDLE hApp, HANDLE hTimer);
 137
 138 #endif  // NOLINT  (build/header_guard)
 139 /** @}*/
 140 /** @}*/
 141 /** @}*/
 142 /** @}*/
 143 //@}