2 * @copyright Copyright (c) 2016-2020 TOYOTA MOTOR CORPORATION.
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
17 ///////////////////////////////////////////////////////////////////////////////
18 /// \ingroup tag_NSFramework
19 /// \brief Application dispatch interface functions
23 ///////////////////////////////////////////////////////////////////////////////
26 * @file frameworkunified_sm_dispatcher.h
27 * @brief \~english Application dispatch interface functions
30 /** @addtogroup BaseSystem
33 /** @addtogroup native_service
37 /** @addtogroup framework_unified
38 * @ingroup native_service
41 /** @addtogroup framework
42 * @ingroup framework_unified
45 /** @addtogroup statemachine
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>
54 class CFrameworkunifiedHSMFramework;
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
69 /// \~english @par Detail
71 /// \~english @par Classification
73 /// \~english @par Type
77 ////////////////////////////////////////////////////////////////////////////////////////////
78 EFrameworkunifiedStatus FrameworkunifiedHSMDispatcher(PCSTR cAppName);
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.)
97 /// FrameworkunifiedDefaultCallbackHandler Structure
99 /// typedef struct _FrameworkunifiedDefaultCallbackHandler
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;
115 /// CustomCommandLineOptions Structure
117 /// typedef struct _CustomCommandLineOptions
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;
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.
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
191 /// \~english @par Type
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);
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
207 /// typedef enum _EUserChangeOptions {
208 /// eUserchangeIgnore = 0,
209 /// eUserchangeReInit,
210 /// eUserchangeRetPrevState
211 /// } EUserChangeOptions;
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
220 /// \~english @par Detail
222 /// \~english @par Classification
224 /// \~english @par Type
228 ////////////////////////////////////////////////////////////////////////////////////////////
229 void FrameworkunifiedSetHSMType(EUserChangeOptions f_eHSMType);
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
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
249 /// \~english @par Type
253 ////////////////////////////////////////////////////////////////////////////////////////////
254 void FrameworkunifiedEnableAutoPublishServiceAvailable();
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
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
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
281 void FrameworkunifiedDisableAutoPublishServiceAvailable();
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.
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
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
306 /// \~english @par Type
308 /// \~english @see FrameworkunifiedHSMDisableWaitInStoppingState
309 VOID FrameworkunifiedHSMEnableWaitInStoppingState();
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
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
327 /// \~english @par Type
329 /// \~english @see FrameworkunifiedHSMEnableWaitInStoppingState
330 VOID FrameworkunifiedHSMDisableWaitInStoppingState();
332 #endif // __NATIVESERVICES_FRAMEWORK_FRAMEWORKUNIFIED_SM_DISPATCHER_H__ // NOLINT (build/header_guard)