nsframework/framework_unified/client/include/native_service/frameworkunified_sm_dispatcher.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 dispatch interface functions
  20 ///
  21 ///
  22 ///
  23 ///////////////////////////////////////////////////////////////////////////////
  24 //@{
  25 /**
  26  * @file frameworkunified_sm_dispatcher.h
  27  * @brief \~english Application dispatch interface functions
  28  *
  29  */
  30 /** @addtogroup BaseSystem
  31  *  @{
  32  */
  33 /** @addtogroup native_service
  34  *  @ingroup BaseSystem
  35  *  @{
  36  */
  37 /** @addtogroup framework_unified
  38  *  @ingroup native_service
  39  *  @{
  40  */
  41 /** @addtogroup framework
  42  *  @ingroup framework_unified
  43  *  @{
  44  */
  45 /** @addtogroup statemachine
  46  *  @ingroup framework
  47  *  @{
  48  */
  49 #ifndef __NATIVESERVICES_FRAMEWORK_FRAMEWORKUNIFIED_SM_DISPATCHER_H__  // NOLINT  (build/header_guard)
  50 #define __NATIVESERVICES_FRAMEWORK_FRAMEWORKUNIFIED_SM_DISPATCHER_H__
  51 #include <native_service/frameworkunified_framework_types.h>
  52 #include <native_service/frameworkunified_sm_framework_types.h>
  53
  54 class CFrameworkunifiedHSMFramework;
  55
  56 ////////////////////////////////////////////////////////////////////////////////////////////
  57 /// \ingroup FrameworkunifiedHSMDispatcher
  58 /// \~english @par Brief
  59 ///        Creates, initializes and runs the HSM dispatcher.
  60 /// \~english @param [in] cAppName
  61 ///        PCSTR - pointer of Application/ thread name
  62 /// \~english @retval EFrameworkunifiedStatus
  63 /// \~english @par Prerequisite
  64 ///        - Prerequisites are nothing.
  65 /// \~english @par Change of internal state
  66 ///        - Change of internal state according to the API does not occur.
  67 /// \~english @par Conditions of processing failure
  68 ///        - none
  69 /// \~english @par Detail
  70 ///        - none
  71 /// \~english @par Classification
  72 ///        Public
  73 /// \~english @par Type
  74 ///        none
  75 /// \~english @see
  76 ///
  77 ////////////////////////////////////////////////////////////////////////////////////////////
  78 EFrameworkunifiedStatus FrameworkunifiedHSMDispatcher(PCSTR cAppName);
  79
  80 /////////////////////////////////////////////////////////////////////////////////////
  81 /// \ingroup FrameworkunifiedHSMDispatcherWithArguments
  82 /// \~english @par Brief
  83 ///        This API creates, initializes the dispatcher and runs loop with command-line options.
  84 /// \~english @param [in] cAppName
  85 ///        PCSTR   - Pointer to application thread name
  86 /// \~english @param [in] argc
  87 ///        int   - Number of command-line options
  88 /// \~english @param [in] argv
  89 ///        char *[]   - Array of pointer to command-line options
  90 /// \~english @param [in] CbHandler
  91 ///        const FrameworkunifiedDefaultCallbackHandler*   - Pointer to default callback functions.
  92 /// \~english @param [in] f_pFrameworkunifiedHSM
  93 ///        CFrameworkunifiedHSMFramework* - state machine object pointer(default NULL)
  94 /// \~english @param [in] cmdLineOptions
  95 ///        CustomCommandLineOptions*   - Parser setting of command-line options(Optional. When don't use, set NULL.)
  96 /// \~english @par
  97 ///        FrameworkunifiedDefaultCallbackHandler Structure
  98 /// \~english @code
  99 ///                 typedef struct _FrameworkunifiedDefaultCallbackHandler
 100 ///                 {
 101 ///                       CbFuncPtr onInitilization;      /* Function is called when a Dispatcher is created.      */
 102 ///                       CbFuncPtr onDestroy;            /* Function is called when the Dispatcher is released.   */
 103 ///                       CbFuncPtr onStart;              /* Function is called when the Dispatcher is started.    */
 104 ///                       CbFuncPtr onStop;               /* Function is called when the Dispatcher is stopped.    */
 105 ///                       CbFuncPtr onPreStart;           /* Function is called when the Dispatcher is pre started. */
 106 ///                       CbFuncPtr onPreStop;            /* Function is called when the Dispatcher is pre stoped. */
 107 ///                       CbFuncPtr onBackgroundStart;    /* Function is called when the Dispatcher is Background started. */
 108 ///                       CbFuncPtr onBackgroundStop;     /* Function is called when the Dispatcher is Background stopped. */
 109 ///                       CbFuncPtr onDebugDump;  /* Function is called when the Dispatcher detects abnormal state. */
 110 ///                       CbFuncPtr createStateMachine;      /* Set dummy function that does nothing.               */
 111 ///                       CbFuncPtr ssFrameworkInterface;     /* Function to connect to SystemManager               */
 112 ///                 } FrameworkunifiedDefaultCallbackHandler;
 113 ///            @endcode
 114 /// \~english @par
 115 ///        CustomCommandLineOptions Structure
 116 /// \~english @code
 117 ///                 typedef struct _CustomCommandLineOptions
 118 ///                 {
 119 ///                     PCSTR            cShortOptions;          /* Short options list. */
 120 ///                     PCHAR            cLongOptions;           /* Reserved. Set to NULL. */
 121 ///                     CbArgumentParser callback;  /* Pointer to callback function to parse command-line options. */
 122 ///                 } CustomCommandLineOptions;
 123 ///            @endcode
 124 /// \~english @par
 125 ///        About setting of default callback functions(FrameworkunifiedDefaultCallbackHandler)
 126 ///        - Use FRAMEWORKUNIFIED_MAKE_DEFAULT_CALLBACK when initialize of FrameworkunifiedDefaultCallbackHandler structure as argument CbHandler.
 127 ///        - Application that run this API need to define functions below.(allow to dummy function that does nothing.)
 128 ///            - EFrameworkunifiedStatus FrameworkunifiedOnInitialization(HANDLE hApp)
 129 ///            - EFrameworkunifiedStatus FrameworkunifiedOnStart(HANDLE hApp)
 130 ///            - EFrameworkunifiedStatus FrameworkunifiedOnStop(HANDLE hApp)
 131 ///            - EFrameworkunifiedStatus FrameworkunifiedOnPreStart(HANDLE hApp)
 132 ///            - EFrameworkunifiedStatus FrameworkunifiedOnPreStop(HANDLE hApp)
 133 ///            - EFrameworkunifiedStatus FrameworkunifiedOnBackgroundStart(HANDLE hApp)
 134 ///            - EFrameworkunifiedStatus FrameworkunifiedOnBackgroundStop(HANDLE hApp)
 135 ///            - EFrameworkunifiedStatus FrameworkunifiedOnDebugDump(HANDLE hApp)
 136 ///            - EFrameworkunifiedStatus FrameworkunifiedOnDestroy(HANDLE hApp)
 137 ///            - EFrameworkunifiedStatus FrameworkunifiedCreateStateMachine(HANDLE hApp)
 138 ///        - If application is resident service, link library libSS_SystemIfUnified
 139 ///          (This library provides the function FrameworkunifiedSSFrameworkInterface to connect to SystemManager.).
 140 ///        - If application is nonresident service, define function that does nothing below.
 141 ///            - EFrameworkunifiedStatus FrameworkunifiedSSFrameworkInterface(HANDLE hApp)
 142 /// \~english @retval eFrameworkunifiedStatusNullPointer NULL pointer specified
 143 /// \~english @retval eFrameworkunifiedStatusInvldParam Invalid parameter
 144 /// \~english @retval eFrameworkunifiedStatusFail Some sort of error occurred
 145 /// \~english @retval eFrameworkunifiedStatusDuplicate Duplication error of entry
 146 /// \~english @retval eFrameworkunifiedStatusInvldHandle Invalid handle
 147 /// \~english @retval eFrameworkunifiedStatusErrOther Other error has occurred(Cannot access shared memory, etc.)
 148 /// \~english @retval eFrameworkunifiedStatusMsgQFull Message queue is full
 149 /// \~english @retval eFrameworkunifiedStatusErrNoEBADF Invalid File-Descriptor
 150 /// \~english @retval eFrameworkunifiedStatusErrNoEINTR An interrupt is generated by the system call (signal)
 151 /// \~english @retval eFrameworkunifiedStatusInvldBufSize Invalid buffer-size
 152 /// \~english @par Prerequisite
 153 ///       - Prerequisites are nothing.
 154 /// \~english @par Change of internal state
 155 ///       - Change of internal state according to the API does not occur.
 156 /// \~english @par Conditions of processing failure
 157 ///       - Application thread name specified in the argument (cAppName) is NULL. [eFrameworkunifiedStatusNullPointer]
 158 ///       - Pointer to default callback functions specified in the argument (CbHandler) is NULL. [eFrameworkunifiedStatusNullPointer]
 159 ///       - One of members in default callback functions specified in the argument (CbHandler) is NULL.
 160 ///       [eFrameworkunifiedStatusInvldParam]
 161 ///       - Application thread name specified in the argument (cAppName) is not appropriate(The name is more than
 162 ///       15byte). [eFrameworkunifiedStatusNullPointer]
 163 ///       - Failed to open message queue (mq_open). [eFrameworkunifiedStatusNullPointer]
 164 ///       - Failed to get memory (malloc) of message queue info area. [eFrameworkunifiedStatusNullPointer]
 165 ///       - Failed to initialize socket for monitoring abnormal state (socket, bind, listen). [eFrameworkunifiedStatusFail]
 166 ///       - Session message queue is full to the NPP Service. [eFrameworkunifiedStatusMsgQFull]
 167 ///       - It is invalid transmission file descriptor of the session message to the NPP Service. [eFrameworkunifiedStatusErrNoEBADF]
 168 ///       - Interruption by the system call (signal) has occurred during the transmission of the session message for the
 169 ///       NPP Service. [eFrameworkunifiedStatusErrNoEINTR]
 170 ///       - Incorrect size of the transmit buffer of the session message to the NPP Service. [eFrameworkunifiedStatusInvldBufSize]
 171 ///       - Any errors occur during the transmission of a session message to the NPP Service. [eFrameworkunifiedStatusFail]
 172 ///       - Failed to create of epoll instance (epoll_create1). [eFrameworkunifiedStatusInvldHandle]
 173 ///       - Failed to register of a descriptor of the message queue to the epoll instance (epoll_ctl).
 174 ///       [eFrameworkunifiedStatusInvldHandle]
 175 ///       - Failed to create file descriptor for receive event (eventfd). [eFrameworkunifiedStatusFail]
 176 ///       - Failed to register of a descriptor for receive event to the epoll instance (epoll_ctl). [eFrameworkunifiedStatusFail]
 177 ///       - Failed to register of a socket for detect abnormal state to the epoll instance (epoll_ctl). [eFrameworkunifiedStatusFail]
 178 ///       - The result of FrameworkunifiedOnInitialization is not eFrameworkunifiedStatusOK. [eFrameworkunifiedStatusNullPointer]
 179 /// \~english @par Detail
 180 ///        This API creates and initializes the dispatcher with command-line options.\n
 181 ///        It starts to mainloop that receives request or notification, and runs registered callback to dispatcher.
 182 ///        When success starting mainloop, never return.
 183 ///        Use this API to take over a command-line options to the dispatcher.
 184 /// \~english @par
 185 ///        Please note the following points when using this API for application.
 186 ///        - Error handling is not performed when the state machine event registration process (CFrameworkunifiedHSMFramework::FrameworkunifiedCreate) fails.\n
 187 ///          The behavior of state machine objects must be guaranteed by the application implementation.
 188 ///        - When an exception occurs during Dispatcher generating, an error log is output and eFrameworkunifiedStatusOK is returned.
 189 /// \~english @par Classification
 190 ///          Public
 191 /// \~english @par Type
 192 ///        No match
 193 /// \~english @see none
 194 ////////////////////////////////////////////////////////////////////////////////////////////
 195 EFrameworkunifiedStatus FrameworkunifiedHSMDispatcherWithArguments(PCSTR cAppName, int argc, char *argv[],
 196                                          const FrameworkunifiedDefaultCallbackHandler *CbHandler,
 197                                          CFrameworkunifiedHSMFramework *f_pFrameworkunifiedHSM = NULL,
 198                                          CustomCommandLineOptions *cmdLineOptions = NULL);
 199
 200 ////////////////////////////////////////////////////////////////////////////////////////////
 201 /// \ingroup FrameworkunifiedSetHSMType
 202 /// \~english @par Brief
 203 ///        Set the Application Statemachine Type
 204 /// \~english @param [in] cAppName
 205 ///        PCSTR - pointer of Application/ thread name
 206 /// \~english @code
 207 ///     typedef enum _EUserChangeOptions {
 208 ///       eUserchangeIgnore = 0,
 209 ///       eUserchangeReInit,
 210 ///       eUserchangeRetPrevState
 211 ///     } EUserChangeOptions;
 212 ///            @endcode
 213 /// \~english @retval EFrameworkunifiedStatus
 214 /// \~english @par Prerequisite
 215 ///        - Prerequisites are nothing.
 216 /// \~english @par Change of internal state
 217 ///        - Change of internal state according to the API does not occur.
 218 /// \~english @par Conditions of processing failure
 219 ///        - none
 220 /// \~english @par Detail
 221 ///        - none
 222 /// \~english @par Classification
 223 ///        Public
 224 /// \~english @par Type
 225 ///        none
 226 /// \~english @see
 227 ///
 228 ////////////////////////////////////////////////////////////////////////////////////////////
 229 void FrameworkunifiedSetHSMType(EUserChangeOptions f_eHSMType);
 230
 231 ////////////////////////////////////////////////////////////////////////////////////////////
 232 /// \ingroup FrameworkunifiedEnableAutoPublishServiceAvailable
 233 /// \~english @par Brief
 234 ///        Enables the AutoPublishServiceAvailability Feature
 235 /// \~english @param none
 236 /// \~english @retval EFrameworkunifiedStatus
 237 /// \~english @par Prerequisite
 238 ///        - Prerequisites are nothing.
 239 /// \~english @par Change of internal state
 240 ///        - Change of internal state according to the API does not occur.
 241 /// \~english @par Conditions of processing failure
 242 ///        - none
 243 /// \~english @par Detail
 244 ///           Enables the AutoPublishServiceAvailability Feature that publishes the service
 245 ///           availability on entry of sFrameworkunifiedReady state and publishes the service unavailability
 246 ///           on exit of sFrameworkunifiedReady state.
 247 /// \~english @par Classification
 248 ///        Public
 249 /// \~english @par Type
 250 ///        none
 251 /// \~english @see
 252 ///
 253 ////////////////////////////////////////////////////////////////////////////////////////////
 254 void FrameworkunifiedEnableAutoPublishServiceAvailable();
 255
 256 ////////////////////////////////////////////////////////////////////////////////////////////
 257 /// \ingroup FrameworkunifiedDisableAutoPublishServiceAvailable
 258 /// \~english @par Brief
 259 ///        Disable to the AutoPublishServiceAvailability Feature.
 260 /// \~english @retval None
 261 /// \~english @par Prerequisite
 262 ///       - Prerequisite is nothing.
 263 /// \~english @par Change of internal state
 264 ///       - Change of internal state according to the API does not occur.
 265 /// \~english @par Conditions of processing failure
 266 ///       None.
 267 /// \~english @par Detail
 268 ///        This API disable feature that notify automatically service availability to clients
 269 ///        at the timing of changing of internal state.\n
 270 ///        If you disable this feature, the application needs to publish service availability state explicitly
 271 ///        using FrameworkunifiedPublishServiceAvailability.
 272 /// \~english @par Classification
 273 ///          Forbidden
 274 /// \~english @see FrameworkunifiedHSMDispatcherWithArguments FrameworkunifiedPublishServiceAvailability
 275 ////////////////////////////////////////////////////////////////////////////////////////////
 276 /// FrameworkunifiedDisableAutoPublishServiceAvailable
 277 /// Disables the AutoPublishServiceAvailability Feature that publishes the service
 278 /// availability on entry of sFrameworkunifiedReady state and publishes the service unavailability
 279 /// on exit of sFrameworkunifiedReady state. Applications are responsible for publishing the service
 280 /// availability.
 281 void FrameworkunifiedDisableAutoPublishServiceAvailable();
 282
 283 ////////////////////////////////////////////////////////////////////////////////////////////
 284 /// \ingroup FrameworkunifiedHSMEnableWaitInStoppingState
 285 ////////////////////////////////////////////////////////////////////////////////////////////
 286 /// FrameworkunifiedHSMEnableWaitInStoppingState
 287 /// If HSM application should wait in sStoppingState until user explicitly publishes evFrameworkunifiedStopComplete,
 288 /// then call this function before FrameworkunifiedHSMDispatcher APIs.
 289 /// Default behavior is application will not wait is sStoppingState.
 290 ///
 291 /// \~english @par Brief
 292 ///         Change state application when call FrameworkunifiedOnStop().
 293 /// \~english @retval None
 294 /// \~english @par Prerequisite
 295 ///       - Prerequisite is nothing.
 296 /// \~english @par Change of internal state
 297 ///       - Change of internal state according to the API does not occur.
 298 /// \~english @par Conditions of processing failure
 299 ///       None.
 300 /// \~english @par Detail
 301 ///            If HSM application should wait in sStoppingState until user explicitly publishes evFrameworkunifiedStopComplete,
 302 ///            then call this function before FrameworkunifiedHSMDispatcher APIs.
 303 ///            Default behavior is application will not wait in sStoppingState.
 304 /// \~english @par Classification
 305 ///        Public
 306 /// \~english @par Type
 307 ///        none
 308 /// \~english @see FrameworkunifiedHSMDisableWaitInStoppingState
 309 VOID FrameworkunifiedHSMEnableWaitInStoppingState();
 310
 311 ////////////////////////////////////////////////////////////////////////////////////////////
 312 /// \ingroup FrameworkunifiedHSMDisableWaitInStoppingState
 313 /// \~english @par Brief
 314 ///         Chanage state to not wait in sStoppingState.
 315 /// \~english @retval None
 316 /// \~english @par Prerequisite
 317 ///       - Prerequisite is nothing.
 318 /// \~english @par Change of internal state
 319 ///       - Change of internal state according to the API does not occur.
 320 /// \~english @par Conditions of processing failure
 321 ///       None.
 322 /// \~english @par Detail
 323 ///       If HSM application should not wait in sStoppingState, then call this function before FrameworkunifiedHSMDispatcher APIs.\n
 324 ///       Default behavior is application will not wait is sStoppingState. So, it's not mandatory to use it.\n
 325 /// \~english @par Classification
 326 ///        Public
 327 /// \~english @par Type
 328 ///        none
 329 /// \~english @see FrameworkunifiedHSMEnableWaitInStoppingState
 330 VOID FrameworkunifiedHSMDisableWaitInStoppingState();
 331
 332 #endif  // __NATIVESERVICES_FRAMEWORK_FRAMEWORKUNIFIED_SM_DISPATCHER_H__  // NOLINT  (build/header_guard)
 333 /** @}*/
 334 /** @}*/
 335 /** @}*/
 336 /** @}*/
 337 /** @}*/
 338 //@}