diff options
Diffstat (limited to 'nsframework/framework_unified/client/include/native_service/ns_timer_if.h')
| -rw-r--r-- | nsframework/framework_unified/client/include/native_service/ns_timer_if.h | 317 |
1 files changed, 317 insertions, 0 deletions
diff --git a/nsframework/framework_unified/client/include/native_service/ns_timer_if.h b/nsframework/framework_unified/client/include/native_service/ns_timer_if.h new file mode 100644 index 00000000..549fc4c3 --- /dev/null +++ b/nsframework/framework_unified/client/include/native_service/ns_timer_if.h @@ -0,0 +1,317 @@ +/* + * @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. + */ + +/** + * @file ns_timer_if.h + * @brief \~english APIs to create, delete and use Native Service timers . + * + */ +/** @addtogroup BaseSystem + * @{ + */ +/** @addtogroup native_service + * @ingroup BaseSystem + * @{ + */ +/** @addtogroup framework_unified + * @ingroup native_service + * @{ + */ +/** @addtogroup native + * @ingroup framework_unified + * @{ + */ +#ifndef __NATIVESERVICES_TIMER_H__ // NOLINT (build/header_guard) +#define __NATIVESERVICES_TIMER_H__ + +#include <native_service/frameworkunified_types.h> + + +#ifdef __cplusplus +extern "C" { +#endif + +#define TIMER_QUE "TIMER" + +#define MAX_SERVICE_NAME 15 + +/// \brief Timer Function Pointer definition +/// Detailed description of the class +typedef void (*TimerCb)(UI_16 cmd); + +/// \brief Timer info, defines the initial +/// start of a timer, the repeat timer +/// values and the cmd id for a timer +typedef struct _NSTimerInfo { + +// UI_32 t_sec; + time_t t_sec; + UI_64 t_nsec; + UI_16 iCmd; + +// UI_32 rpt_sec; + time_t rpt_sec; + UI_64 rpt_nsec; +} NSTimerInfo; + +/// \brief Enum Types for valid Callback Mechanisms for +/// a NS_Timer +typedef enum _NSTimerCallbackMechanism { + CALLBACK_MESSAGE +} eNSTimerCallbackMechanism; + +/// \brief Helper methods that convert time provided in MS. +/// mseconds + +///////////////////////////////////////////////////////////////////////////////////// +/// \ingroup WholeSeconds +/// \~english @par Brief +/// Converts a time value in milliseconds (ms) to a time value in secods (s). +/// \~english @param [in] ms +/// UI_32 - Time value in milliseconds(0 to ULONG_MAX) +/// \~english @retval Time value in seconds +/// \~english @par Preconditons +/// - none +/// \~english @par Change of internal status +/// - The internal state is not changed. +/// \~english @par Conditions of processing failure +/// - none +/// \~english @par Detail +/// This function converts a time value in ms to a time value in s and returns it.\n +/// For example, 12345ms obtains 12s as the conversion result. +/// \~english @par Classification +/// Public +/// \~english @par Type +/// Not applicable +/// \~english @see +/// none +/// +/// \~english @par Brief +/// Get the number of whole seconds in the milsecond number that was passed. +/// \~english @param[in] ms +/// UI_32 - time value in mil seconds +/// \~english @retval Number of whole seconds in the number passed. +/// \~english @par Preconditons +/// \~english @par Change of internal status +/// \~english @par Conditions of processing failure +/// \~english @par Detail +/// \~english @par Classification +/// \~english @par Type +/// \~english @see +/// none +///////////////////////////////////////////////////////////////////////////////////// + +//UI_32 WholeSeconds(UI_32 ms); +time_t WholeSeconds(UI_32 ms); + +///////////////////////////////////////////////////////////////////////////////////// +/// \ingroup RemainderMs +/// \~english @par Brief +/// Get the number of remaining milseconds out of whole second for the number passed. +/// \~english @param[in] ms +/// UI_32 - time value in mil seconds +/// \~english @retval Number of remaining mil seconds in the number passed. +/// \~english @par Preconditons +/// none +/// \~english @par Change of internal status +/// - The internal state is not changed. +/// \~english @par Conditions of processing failure +/// none +/// \~english @par Detail +/// 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 +/// For example, 12345ms obtains 345ms as the conversion result. +/// \~english @par Classification +/// \~english @par Type +/// \~english @see +/// none +///////////////////////////////////////////////////////////////////////////////////// +UI_32 RemainderMs(UI_32 ms); + +///////////////////////////////////////////////////////////////////////////////////// +/// \ingroup MSToNS +/// \~english @par Brief +/// Converts mil seconds to nano seconds. +/// \~english @param[in] ms +/// UI_32 - time value in mil seconds +/// \~english @retval Number of nano seconds there are in mil seconds in the number passed. +/// \~english @par Preconditons +/// none +/// \~english @par Change of internal status +/// - The internal state is not changed. +/// \~english @par Conditions of processing failure +/// none +/// \~english @par Detail +/// This function converts a time value in ms to a time value in ns and returns it.\n +/// For example, 1234ms obtains 1234000000ns as the conversion result. +/// \~english @par Classification +/// \~english @par Type +/// \~english @see +/// none +///////////////////////////////////////////////////////////////////////////////////// +UI_64 MSToNS(UI_32 ms); + +//////////////////////////////////////////////////////////////////////////////////////////// +/// \ingroup NS_TimerCreate +/// \~english @par Brief +/// to create an instance of a timer object, and start it +/// \~english @param[in] timer_info +/// NSTimerInfo - timer value represents an absolute expiration timeout +/// \~english @param[in] cbMech +/// eNSTimerCallbackMechanism - CALLBACKMECHANISM_ENUM - specifies the callback mechanism associated with the +/// timer\n +/// CALLBACK_MESSAGE will send a message to a message queue +/// \~english @param[in] sndMqHndl +/// HANDLE - implies a MESSAGE QUE HANDLE generated by McOpenSender() is specified +/// \~english @retval Handle to the timer object or NULL on failure +/// \~english @par Preconditons +/// none +/// \~english @par Change of internal status +/// - The internal state is not changed. +/// \~english @par Conditions of processing failure +/// - If HANDLE(sndMqHndl) is NULL, [NULL] +/// - If the Callback mechanism (cbMech) specified in the arguments is not CALLBACK_MESSAGE [NULL] +/// - If thread creation fails (reateTimerMonitoringThread(); returns eFrameworkunifiedStatusFail) [NULL] +/// - Unable to allocate memory for timer handle structures [NULL] +/// - Memory cannot be allocated for the timer-information struct. [NULL] +/// - When the message queue name of the handle (sndMqHndl) specified in the arguments is NULL,[NULL] +/// - If a system call (such as epoll_ctl()) is in error,[NULL] +/// \~english @par Detail +/// Creates an instance of a timer object, sends a CALLBACK_MESSAGE message to the message queue, and starts the timer.\n +/// When McOpenSender() is executed to execute NS_TimerCreate, the handles should be closed if not needed. +/// \~english @par Classification +/// \~english @par Type +/// \~english @see NS_TimerDelete,NS_TimerSetTime +//////////////////////////////////////////////////////////////////////////////////////////// +HANDLE NS_TimerCreate(NSTimerInfo timer_info, eNSTimerCallbackMechanism cbMech, HANDLE sndMqHndl); + +//////////////////////////////////////////////////////////////////////////////////////////// +/// \ingroup NS_TimerDelete +/// \~english @par Brief +/// to delete an instance of a timer object +/// \~english @param[in] hTimer +/// HANDLE - a timer handle that was created via NS_TimerCreate +/// \~english @retval EFrameworkunifiedStatus indicates if the timer handle was delete successfully +/// \~english @retval eFrameworkunifiedStatusOK +/// \~english @retval eFrameworkunifiedStatusFail +/// \~english @retval eFrameworkunifiedStatusInvldParam +/// \~english @par Preconditons +/// - NS_TimerCreate has generated a HANDLE of timers +/// \~english @par Change of internal status +/// - The internal state is not changed. +/// \~english @par Conditions of processing failure +/// - If HANDLE(hTimer) is NULL,[eFrameworkunifiedStatusInvldParam] +/// - Initializes the state. [eFrameworkunifiedStatusFail] +/// - Invalid timed objects for HANDLE(hTimer specified by arguments:[eFrameworkunifiedStatusInvldParam] +/// - If semaphoring fails, [eFrameworkunifiedStatusFail] +/// \~english @par Detail +/// If the timer is set, the timer is stopped.\n +/// Delete an instance of a timer object. +/// \~english @par Classification +/// \~english @par Type +/// \~english @see NS_TimerCreate, NS_TimerSetTime +//////////////////////////////////////////////////////////////////////////////////////////// +EFrameworkunifiedStatus NS_TimerDelete(HANDLE hTimer); + +//////////////////////////////////////////////////////////////////////////////////////////// +/// \ingroup NS_TimerSetTime +/// \~english @par Brief +/// to start or stop a timer by setting the time interval associated +/// with a timer, value of 0 in t_sec & t_nsec, will stop the timer. +/// \~english @param[in] hTimer +/// HANDLE - handle to timer that your specifying the timer to be set +/// \~english @param[in] timer_info +/// NSTimerInfo - timer value represents an absolute expiration timeout +/// \~english @retval EFrameworkunifiedStatus indicates if the timer info was set successfully +/// \~english @retval eFrameworkunifiedStatusOK +/// \~english @retval eFrameworkunifiedStatusInvldHandle +/// \~english @retval eFrameworkunifiedStatusFail +/// \~english @par Preconditons +/// the timer must have already been created with NS_TimerCreate +/// \~english @par Change of internal status +/// - The internal state is not changed. +/// \~english @par Conditions of processing failure +/// - If HANDLE(hTimer) is NULL,[eFrameworkunifiedStatusInvldHandle] +/// - Initializes the state. [eFrameworkunifiedStatusFail] +/// - Retrieving timers fails [eFrameworkunifiedStatusFail] +/// \~english @par Detail +/// When the timer information (t_sec and t_nsec) is 0, the timer is stopped.\n +/// If it is not 0, the timer is started based on the timer information.\n +/// The hTimer must have been created with NS_TimerCreate. +/// \~english @par Classification +/// \~english @par Type +/// \~english @see NS_TimerCreate, NS_TimerGetTime +//////////////////////////////////////////////////////////////////////////////////////////// +EFrameworkunifiedStatus NS_TimerSetTime(HANDLE hTimer, NSTimerInfo timer_info); + +//////////////////////////////////////////////////////////////////////////////////////////// +/// \ingroup NS_TimerGetTime +/// \~english @par Brief +/// to retrieve the time until a timer expires +/// \~english @param[in] hTimer +/// HANDLE - handle to timer that your trying to get information about +/// \~english @param[out] timer_info +/// NSTimerInfo* - a structure to store the delay time until the timer expires +/// \~english @retval EFrameworkunifiedStatus indicates if the timer info was get successfully +/// \~english @retval eFrameworkunifiedStatusOK +/// \~english @retval eFrameworkunifiedStatusInvldHandle +/// \~english @retval eFrameworkunifiedStatusFail +/// \~english @par Preconditons +/// - NS_TimerCreate has generated a HANDLE of timers +/// \~english @par Change of internal status +/// - The internal state is not changed. +/// \~english @par Conditions of processing failure +/// - If HANDLE(hTimer) is NULL,[eFrameworkunifiedStatusInvldHandle] +/// - If the timer_info specified in the arguments is NULL,... [eFrameworkunifiedStatusInvldHandle] +/// - Initializes the state. [eFrameworkunifiedStatusFail] +/// - If the timerdelete fails.... [eFrameworkunifiedStatusFail] +/// \~english @par Detail +/// Gets the time until the timer expires. +/// \~english @par Classification +/// \~english @par Type +/// \~english @see NS_TimerCreate, NS_TimerSetTime +//////////////////////////////////////////////////////////////////////////////////////////// +EFrameworkunifiedStatus NS_TimerGetTime(HANDLE hTimer, NSTimerInfo *timer_info); + +//////////////////////////////////////////////////////////////////////////////////////////// +/// \ingroup NS_TimerDebugOn +/// \~english @par Brief +/// to make a flag for the debugging process. for debug. +/// \~english @param[in] FlagState +/// BOOL - DebugFlag state +/// \~english @retval none +/// \~english @par Preconditons +/// none +/// \~english @par Change of internal status +/// - The internal state is not changed. +/// \~english @par Conditions of processing failure +/// none +/// \~english @par Detail +/// Sets the debug flag specified by the argument.\n +/// However, if the set flag is the same as the flag specified in the argument, no operation is performed. +/// \~english @par Classification +/// \~english @par Type +/// \~english @see none +//////////////////////////////////////////////////////////////////////////////////////////// +void NS_TimerDebugOn(BOOL FlagState); + +#ifdef __cplusplus +} +#endif +#endif /* __NATIVESERVICES_TIMER_H__ */ // NOLINT (build/header_guard) +/** @}*/ +/** @}*/ +/** @}*/ +/** @}*/ |