nsframework/framework_unified/client/include/native_service/ns_timer_if.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  * @file ns_timer_if.h
  19  * @brief \~english APIs to create, delete and use Native Service timers .
  20  *
  21  */
  22 /** @addtogroup BaseSystem
  23  *  @{
  24  */
  25 /** @addtogroup native_service
  26  *  @ingroup BaseSystem
  27  *  @{
  28  */
  29 /** @addtogroup framework_unified
  30  *  @ingroup native_service
  31  *  @{
  32  */
  33 /** @addtogroup native
  34  *  @ingroup framework_unified
  35  *  @{
  36  */
  37 #ifndef __NATIVESERVICES_TIMER_H__  // NOLINT  (build/header_guard)
  38 #define __NATIVESERVICES_TIMER_H__
  39
  40 #include <native_service/frameworkunified_types.h>
  41
  42
  43 #ifdef __cplusplus
  44 extern "C" {
  45 #endif
  46
  47 #define TIMER_QUE "TIMER"
  48
  49 #define MAX_SERVICE_NAME 15
  50
  51 /// \brief Timer Function Pointer definition
  52 /// Detailed description of the class
  53 typedef void (*TimerCb)(UI_16 cmd);
  54
  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 {
  59
  60 //  UI_32 t_sec;
  61   time_t t_sec;
  62   UI_64 t_nsec;
  63   UI_16 iCmd;
  64
  65 //  UI_32 rpt_sec;
  66   time_t rpt_sec;
  67   UI_64 rpt_nsec;
  68 } NSTimerInfo;
  69
  70 /// \brief Enum Types for valid Callback Mechanisms for
  71 /// a NS_Timer
  72 typedef enum _NSTimerCallbackMechanism {
  73   CALLBACK_MESSAGE
  74 } eNSTimerCallbackMechanism;
  75
  76 /// \brief Helper methods that convert time provided in MS.
  77 /// mseconds
  78
  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
  87 ///       - none
  88 /// \~english @par Change of internal status
  89 ///       - The internal state is not changed.
  90 /// \~english @par Conditions of processing failure
  91 ///       - none
  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
  96 ///          Public
  97 /// \~english @par Type
  98 ///          Not applicable
  99 /// \~english @see
 100 ///          none
 101 ///
 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
 113 /// \~english @see
 114 ///         none
 115 /////////////////////////////////////////////////////////////////////////////////////
 116
 117 //UI_32 WholeSeconds(UI_32 ms);
 118 time_t WholeSeconds(UI_32 ms);
 119
 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
 128 ///         none
 129 /// \~english @par Change of internal status
 130 ///       - The internal state is not changed.
 131 /// \~english @par Conditions of processing failure
 132 ///         none
 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
 138 /// \~english @see
 139 ///         none
 140 /////////////////////////////////////////////////////////////////////////////////////
 141 UI_32 RemainderMs(UI_32 ms);
 142
 143 /////////////////////////////////////////////////////////////////////////////////////
 144 /// \ingroup MSToNS
 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
 151 ///         none
 152 /// \~english @par Change of internal status
 153 ///       - The internal state is not changed.
 154 /// \~english @par Conditions of processing failure
 155 ///         none
 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
 161 /// \~english @see
 162 ///         none
 163 /////////////////////////////////////////////////////////////////////////////////////
 164 UI_64 MSToNS(UI_32 ms);
 165
 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
 174 ///        timer\n
 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
 180 ///         none
 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);
 199
 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);
 227
 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);
 258
 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);
 287
 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
 296 ///     none
 297 /// \~english @par Change of internal status
 298 ///     - The internal state is not changed.
 299 /// \~english @par Conditions of processing failure
 300 ///     none
 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);
 309
 310 #ifdef __cplusplus
 311 }
 312 #endif
 313 #endif /* __NATIVESERVICES_TIMER_H__ */  // NOLINT  (build/header_guard)
 314 /** @}*/
 315 /** @}*/
 316 /** @}*/
 317 /** @}*/