diff options
Diffstat (limited to 'nsframework/framework_unified/client/include/native_service/frameworkunified_sm_dispatcher.h')
| -rw-r--r-- | nsframework/framework_unified/client/include/native_service/frameworkunified_sm_dispatcher.h | 338 |
1 files changed, 338 insertions, 0 deletions
diff --git a/nsframework/framework_unified/client/include/native_service/frameworkunified_sm_dispatcher.h b/nsframework/framework_unified/client/include/native_service/frameworkunified_sm_dispatcher.h new file mode 100644 index 00000000..2f392bab --- /dev/null +++ b/nsframework/framework_unified/client/include/native_service/frameworkunified_sm_dispatcher.h @@ -0,0 +1,338 @@ +/* + * @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 dispatch interface functions +/// +/// +/// +/////////////////////////////////////////////////////////////////////////////// +//@{ +/** + * @file frameworkunified_sm_dispatcher.h + * @brief \~english Application dispatch interface functions + * + */ +/** @addtogroup BaseSystem + * @{ + */ +/** @addtogroup native_service + * @ingroup BaseSystem + * @{ + */ +/** @addtogroup framework_unified + * @ingroup native_service + * @{ + */ +/** @addtogroup framework + * @ingroup framework_unified + * @{ + */ +/** @addtogroup statemachine + * @ingroup framework + * @{ + */ +#ifndef __NATIVESERVICES_FRAMEWORK_FRAMEWORKUNIFIED_SM_DISPATCHER_H__ // NOLINT (build/header_guard) +#define __NATIVESERVICES_FRAMEWORK_FRAMEWORKUNIFIED_SM_DISPATCHER_H__ +#include <native_service/frameworkunified_framework_types.h> +#include <native_service/frameworkunified_sm_framework_types.h> + +class CFrameworkunifiedHSMFramework; + +//////////////////////////////////////////////////////////////////////////////////////////// +/// \ingroup FrameworkunifiedHSMDispatcher +/// \~english @par Brief +/// Creates, initializes and runs the HSM dispatcher. +/// \~english @param [in] cAppName +/// PCSTR - pointer of Application/ thread name +/// \~english @retval EFrameworkunifiedStatus +/// \~english @par Prerequisite +/// - Prerequisites are nothing. +/// \~english @par Change of internal state +/// - Change of internal state according to the API does not occur. +/// \~english @par Conditions of processing failure +/// - none +/// \~english @par Detail +/// - none +/// \~english @par Classification +/// Public +/// \~english @par Type +/// none +/// \~english @see +/// +//////////////////////////////////////////////////////////////////////////////////////////// +EFrameworkunifiedStatus FrameworkunifiedHSMDispatcher(PCSTR cAppName); + +///////////////////////////////////////////////////////////////////////////////////// +/// \ingroup FrameworkunifiedHSMDispatcherWithArguments +/// \~english @par Brief +/// This API creates, initializes the dispatcher and runs loop with command-line options. +/// \~english @param [in] cAppName +/// PCSTR - Pointer to application thread name +/// \~english @param [in] argc +/// int - Number of command-line options +/// \~english @param [in] argv +/// char *[] - Array of pointer to command-line options +/// \~english @param [in] CbHandler +/// const FrameworkunifiedDefaultCallbackHandler* - Pointer to default callback functions. +/// \~english @param [in] f_pFrameworkunifiedHSM +/// CFrameworkunifiedHSMFramework* - state machine object pointer(default NULL) +/// \~english @param [in] cmdLineOptions +/// CustomCommandLineOptions* - Parser setting of command-line options(Optional. When don't use, set NULL.) +/// \~english @par +/// FrameworkunifiedDefaultCallbackHandler Structure +/// \~english @code +/// typedef struct _FrameworkunifiedDefaultCallbackHandler +/// { +/// CbFuncPtr onInitilization; /* Function is called when a Dispatcher is created. */ +/// CbFuncPtr onDestroy; /* Function is called when the Dispatcher is released. */ +/// CbFuncPtr onStart; /* Function is called when the Dispatcher is started. */ +/// CbFuncPtr onStop; /* Function is called when the Dispatcher is stopped. */ +/// CbFuncPtr onPreStart; /* Function is called when the Dispatcher is pre started. */ +/// CbFuncPtr onPreStop; /* Function is called when the Dispatcher is pre stoped. */ +/// CbFuncPtr onBackgroundStart; /* Function is called when the Dispatcher is Background started. */ +/// CbFuncPtr onBackgroundStop; /* Function is called when the Dispatcher is Background stopped. */ +/// CbFuncPtr onDebugDump; /* Function is called when the Dispatcher detects abnormal state. */ +/// CbFuncPtr createStateMachine; /* Set dummy function that does nothing. */ +/// CbFuncPtr ssFrameworkInterface; /* Function to connect to SystemManager */ +/// } FrameworkunifiedDefaultCallbackHandler; +/// @endcode +/// \~english @par +/// CustomCommandLineOptions Structure +/// \~english @code +/// typedef struct _CustomCommandLineOptions +/// { +/// PCSTR cShortOptions; /* Short options list. */ +/// PCHAR cLongOptions; /* Reserved. Set to NULL. */ +/// CbArgumentParser callback; /* Pointer to callback function to parse command-line options. */ +/// } CustomCommandLineOptions; +/// @endcode +/// \~english @par +/// About setting of default callback functions(FrameworkunifiedDefaultCallbackHandler) +/// - Use FRAMEWORKUNIFIED_MAKE_DEFAULT_CALLBACK when initialize of FrameworkunifiedDefaultCallbackHandler structure as argument CbHandler. +/// - Application that run this API need to define functions below.(allow to dummy function that does nothing.) +/// - EFrameworkunifiedStatus FrameworkunifiedOnInitialization(HANDLE hApp) +/// - EFrameworkunifiedStatus FrameworkunifiedOnStart(HANDLE hApp) +/// - EFrameworkunifiedStatus FrameworkunifiedOnStop(HANDLE hApp) +/// - EFrameworkunifiedStatus FrameworkunifiedOnPreStart(HANDLE hApp) +/// - EFrameworkunifiedStatus FrameworkunifiedOnPreStop(HANDLE hApp) +/// - EFrameworkunifiedStatus FrameworkunifiedOnBackgroundStart(HANDLE hApp) +/// - EFrameworkunifiedStatus FrameworkunifiedOnBackgroundStop(HANDLE hApp) +/// - EFrameworkunifiedStatus FrameworkunifiedOnDebugDump(HANDLE hApp) +/// - EFrameworkunifiedStatus FrameworkunifiedOnDestroy(HANDLE hApp) +/// - EFrameworkunifiedStatus FrameworkunifiedCreateStateMachine(HANDLE hApp) +/// - If application is resident service, link library libSS_SystemIfUnified +/// (This library provides the function FrameworkunifiedSSFrameworkInterface to connect to SystemManager.). +/// - If application is nonresident service, define function that does nothing below. +/// - EFrameworkunifiedStatus FrameworkunifiedSSFrameworkInterface(HANDLE hApp) +/// \~english @retval eFrameworkunifiedStatusNullPointer NULL pointer specified +/// \~english @retval eFrameworkunifiedStatusInvldParam Invalid parameter +/// \~english @retval eFrameworkunifiedStatusFail Some sort of error occurred +/// \~english @retval eFrameworkunifiedStatusDuplicate Duplication error of entry +/// \~english @retval eFrameworkunifiedStatusInvldHandle Invalid handle +/// \~english @retval eFrameworkunifiedStatusErrOther Other error has occurred(Cannot access shared memory, etc.) +/// \~english @retval eFrameworkunifiedStatusMsgQFull Message queue is full +/// \~english @retval eFrameworkunifiedStatusErrNoEBADF Invalid File-Descriptor +/// \~english @retval eFrameworkunifiedStatusErrNoEINTR An interrupt is generated by the system call (signal) +/// \~english @retval eFrameworkunifiedStatusInvldBufSize Invalid buffer-size +/// \~english @par Prerequisite +/// - Prerequisites are nothing. +/// \~english @par Change of internal state +/// - Change of internal state according to the API does not occur. +/// \~english @par Conditions of processing failure +/// - Application thread name specified in the argument (cAppName) is NULL. [eFrameworkunifiedStatusNullPointer] +/// - Pointer to default callback functions specified in the argument (CbHandler) is NULL. [eFrameworkunifiedStatusNullPointer] +/// - One of members in default callback functions specified in the argument (CbHandler) is NULL. +/// [eFrameworkunifiedStatusInvldParam] +/// - Application thread name specified in the argument (cAppName) is not appropriate(The name is more than +/// 15byte). [eFrameworkunifiedStatusNullPointer] +/// - Failed to open message queue (mq_open). [eFrameworkunifiedStatusNullPointer] +/// - Failed to get memory (malloc) of message queue info area. [eFrameworkunifiedStatusNullPointer] +/// - Failed to initialize socket for monitoring abnormal state (socket, bind, listen). [eFrameworkunifiedStatusFail] +/// - Session message queue is full to the NPP Service. [eFrameworkunifiedStatusMsgQFull] +/// - It is invalid transmission file descriptor of the session message to the NPP Service. [eFrameworkunifiedStatusErrNoEBADF] +/// - Interruption by the system call (signal) has occurred during the transmission of the session message for the +/// NPP Service. [eFrameworkunifiedStatusErrNoEINTR] +/// - Incorrect size of the transmit buffer of the session message to the NPP Service. [eFrameworkunifiedStatusInvldBufSize] +/// - Any errors occur during the transmission of a session message to the NPP Service. [eFrameworkunifiedStatusFail] +/// - Failed to create of epoll instance (epoll_create1). [eFrameworkunifiedStatusInvldHandle] +/// - Failed to register of a descriptor of the message queue to the epoll instance (epoll_ctl). +/// [eFrameworkunifiedStatusInvldHandle] +/// - Failed to create file descriptor for receive event (eventfd). [eFrameworkunifiedStatusFail] +/// - Failed to register of a descriptor for receive event to the epoll instance (epoll_ctl). [eFrameworkunifiedStatusFail] +/// - Failed to register of a socket for detect abnormal state to the epoll instance (epoll_ctl). [eFrameworkunifiedStatusFail] +/// - The result of FrameworkunifiedOnInitialization is not eFrameworkunifiedStatusOK. [eFrameworkunifiedStatusNullPointer] +/// \~english @par Detail +/// This API creates and initializes the dispatcher with command-line options.\n +/// It starts to mainloop that receives request or notification, and runs registered callback to dispatcher. +/// When success starting mainloop, never return. +/// Use this API to take over a command-line options to the dispatcher. +/// \~english @par +/// Please note the following points when using this API for application. +/// - Error handling is not performed when the state machine event registration process (CFrameworkunifiedHSMFramework::FrameworkunifiedCreate) fails.\n +/// The behavior of state machine objects must be guaranteed by the application implementation. +/// - When an exception occurs during Dispatcher generating, an error log is output and eFrameworkunifiedStatusOK is returned. +/// \~english @par Classification +/// Public +/// \~english @par Type +/// No match +/// \~english @see none +//////////////////////////////////////////////////////////////////////////////////////////// +EFrameworkunifiedStatus FrameworkunifiedHSMDispatcherWithArguments(PCSTR cAppName, int argc, char *argv[], + const FrameworkunifiedDefaultCallbackHandler *CbHandler, + CFrameworkunifiedHSMFramework *f_pFrameworkunifiedHSM = NULL, + CustomCommandLineOptions *cmdLineOptions = NULL); + +//////////////////////////////////////////////////////////////////////////////////////////// +/// \ingroup FrameworkunifiedSetHSMType +/// \~english @par Brief +/// Set the Application Statemachine Type +/// \~english @param [in] cAppName +/// PCSTR - pointer of Application/ thread name +/// \~english @code +/// typedef enum _EUserChangeOptions { +/// eUserchangeIgnore = 0, +/// eUserchangeReInit, +/// eUserchangeRetPrevState +/// } EUserChangeOptions; +/// @endcode +/// \~english @retval EFrameworkunifiedStatus +/// \~english @par Prerequisite +/// - Prerequisites are nothing. +/// \~english @par Change of internal state +/// - Change of internal state according to the API does not occur. +/// \~english @par Conditions of processing failure +/// - none +/// \~english @par Detail +/// - none +/// \~english @par Classification +/// Public +/// \~english @par Type +/// none +/// \~english @see +/// +//////////////////////////////////////////////////////////////////////////////////////////// +void FrameworkunifiedSetHSMType(EUserChangeOptions f_eHSMType); + +//////////////////////////////////////////////////////////////////////////////////////////// +/// \ingroup FrameworkunifiedEnableAutoPublishServiceAvailable +/// \~english @par Brief +/// Enables the AutoPublishServiceAvailability Feature +/// \~english @param none +/// \~english @retval EFrameworkunifiedStatus +/// \~english @par Prerequisite +/// - Prerequisites are nothing. +/// \~english @par Change of internal state +/// - Change of internal state according to the API does not occur. +/// \~english @par Conditions of processing failure +/// - none +/// \~english @par Detail +/// Enables the AutoPublishServiceAvailability Feature that publishes the service +/// availability on entry of sFrameworkunifiedReady state and publishes the service unavailability +/// on exit of sFrameworkunifiedReady state. +/// \~english @par Classification +/// Public +/// \~english @par Type +/// none +/// \~english @see +/// +//////////////////////////////////////////////////////////////////////////////////////////// +void FrameworkunifiedEnableAutoPublishServiceAvailable(); + +//////////////////////////////////////////////////////////////////////////////////////////// +/// \ingroup FrameworkunifiedDisableAutoPublishServiceAvailable +/// \~english @par Brief +/// Disable to the AutoPublishServiceAvailability Feature. +/// \~english @retval None +/// \~english @par Prerequisite +/// - Prerequisite is nothing. +/// \~english @par Change of internal state +/// - Change of internal state according to the API does not occur. +/// \~english @par Conditions of processing failure +/// None. +/// \~english @par Detail +/// This API disable feature that notify automatically service availability to clients +/// at the timing of changing of internal state.\n +/// If you disable this feature, the application needs to publish service availability state explicitly +/// using FrameworkunifiedPublishServiceAvailability. +/// \~english @par Classification +/// Forbidden +/// \~english @see FrameworkunifiedHSMDispatcherWithArguments FrameworkunifiedPublishServiceAvailability +//////////////////////////////////////////////////////////////////////////////////////////// +/// FrameworkunifiedDisableAutoPublishServiceAvailable +/// Disables the AutoPublishServiceAvailability Feature that publishes the service +/// availability on entry of sFrameworkunifiedReady state and publishes the service unavailability +/// on exit of sFrameworkunifiedReady state. Applications are responsible for publishing the service +/// availability. +void FrameworkunifiedDisableAutoPublishServiceAvailable(); + +//////////////////////////////////////////////////////////////////////////////////////////// +/// \ingroup FrameworkunifiedHSMEnableWaitInStoppingState +//////////////////////////////////////////////////////////////////////////////////////////// +/// FrameworkunifiedHSMEnableWaitInStoppingState +/// If HSM application should wait in sStoppingState until user explicitly publishes evFrameworkunifiedStopComplete, +/// then call this function before FrameworkunifiedHSMDispatcher APIs. +/// Default behavior is application will not wait is sStoppingState. +/// +/// \~english @par Brief +/// Change state application when call FrameworkunifiedOnStop(). +/// \~english @retval None +/// \~english @par Prerequisite +/// - Prerequisite is nothing. +/// \~english @par Change of internal state +/// - Change of internal state according to the API does not occur. +/// \~english @par Conditions of processing failure +/// None. +/// \~english @par Detail +/// If HSM application should wait in sStoppingState until user explicitly publishes evFrameworkunifiedStopComplete, +/// then call this function before FrameworkunifiedHSMDispatcher APIs. +/// Default behavior is application will not wait in sStoppingState. +/// \~english @par Classification +/// Public +/// \~english @par Type +/// none +/// \~english @see FrameworkunifiedHSMDisableWaitInStoppingState +VOID FrameworkunifiedHSMEnableWaitInStoppingState(); + +//////////////////////////////////////////////////////////////////////////////////////////// +/// \ingroup FrameworkunifiedHSMDisableWaitInStoppingState +/// \~english @par Brief +/// Chanage state to not wait in sStoppingState. +/// \~english @retval None +/// \~english @par Prerequisite +/// - Prerequisite is nothing. +/// \~english @par Change of internal state +/// - Change of internal state according to the API does not occur. +/// \~english @par Conditions of processing failure +/// None. +/// \~english @par Detail +/// If HSM application should not wait in sStoppingState, then call this function before FrameworkunifiedHSMDispatcher APIs.\n +/// Default behavior is application will not wait is sStoppingState. So, it's not mandatory to use it.\n +/// \~english @par Classification +/// Public +/// \~english @par Type +/// none +/// \~english @see FrameworkunifiedHSMEnableWaitInStoppingState +VOID FrameworkunifiedHSMDisableWaitInStoppingState(); + +#endif // __NATIVESERVICES_FRAMEWORK_FRAMEWORKUNIFIED_SM_DISPATCHER_H__ // NOLINT (build/header_guard) +/** @}*/ +/** @}*/ +/** @}*/ +/** @}*/ +/** @}*/ +//@} |