nsframework/framework_unified/client/include/native_service/frameworkunified_sm_framework_types.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_StateMachine
  19 /// \brief
  20 ///
  21 /// This File has public Macro definition that simplifies the statemachine implementation
  22 ///
  23 ///////////////////////////////////////////////////////////////////////////////
  24 //@{
  25 /**
  26  * @file frameworkunified_sm_framework_types.h
  27  * @brief \~english This File has public Macro definition that simplifies the statemachine implementation
  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 __FRAMEWORKUNIFIED_NATIVESERVICES_NATIVESERVICES_INC_FRAMEWORK_STATEMACHINE_FRAMEWORKUNIFIED_FRAMEWORKUNIFIED_SM_FRAMEWORK_TYPES_H__  // NOLINT  (build/header_guard)
  50 #define __FRAMEWORKUNIFIED_NATIVESERVICES_NATIVESERVICES_INC_FRAMEWORK_STATEMACHINE_FRAMEWORKUNIFIED_FRAMEWORKUNIFIED_SM_FRAMEWORK_TYPES_H__
  51
  52 ///////////////////////////////////////////////////////////////////////////////////////////////////
  53 // Include Files
  54 ///////////////////////////////////////////////////////////////////////////////////////////////////
  55
  56 #include <native_service/frameworkunified_sm_leafstate.h>
  57 #include <native_service/frameworkunified_sm_internaltransition.h>
  58 #include <native_service/frameworkunified_sm_compositestate.h>
  59 #include <native_service/frameworkunified_sm_eventfactory.h>
  60 #include <native_service/frameworkunified_sm_externaltransition.h>
  61 #include <native_service/frameworkunified_sm_localtransition.h>
  62 #include <native_service/frameworkunified_sm_orthogonalstate.h>
  63 #include <native_service/frameworkunified_sm_shallowhistorystate.h>
  64 #include <native_service/frameworkunified_sm_deephistorystate.h>
  65 #include <native_service/frameworkunified_sm_guard.h>
  66 #include <native_service/frameworkunified_sm_conditionconnector.h>
  67 #include <native_service/frameworkunified_sm_action.h>
  68 #include <native_service/frameworkunified_sm_eventdata.h>
  69 #include <exception>
  70 #include <string>
  71
  72 class CFrameworkunifiedState;
  73
  74
  75 ///////////////////////////////////////////////////////////////////////////////////////////////////
  76 /// Defines the null pointer exception
  77 ///////////////////////////////////////////////////////////////////////////////////////////////////
  78 class CNullPointerException: public std::exception {
  79   virtual const char *what() const throw() {
  80     return "Null pointer exception";
  81   }
  82 };
  83
  84
  85 /// Macro to check pointer for null value and throw null pointer exception
  86 #define CHKNULL(x) if (NULL == x) throw CNullPointerException();
  87
  88 #define SHALLOWHISTORYSTATE   "ShallowHistory"
  89 #define DEEPHISTORYSTATE    "DeepHistory"
  90
  91 /// Defines the state machine class
  92 #define DEFINE_STATEMACHINE(class_name) \
  93     class C## class_name : public CFrameworkunifiedHSM{ \
  94      public: \
  95       C## class_name(); \
  96       virtual ~C## class_name(); \
  97       EFrameworkunifiedStatus FrameworkunifiedCreate(PVOID f_pEventData = NULL); \
  98     };
  99
 100 /// Defines the leafstate class that does not override entry and exit of base state
 101 #define DEFINE_LEAFSTATE(class_name) \
 102     class C## class_name : public CFrameworkunifiedLeafState { \
 103      public: \
 104       C## class_name(std::string f_pName):CFrameworkunifiedLeafState(f_pName) {} };
 105
 106 /// Defines the Composite state that does not override entry and exit of base state
 107 #define DEFINE_COMPOSITESTATE(class_name) \
 108     class C## class_name : public CFrameworkunifiedCompositeState { \
 109      public: \
 110       C## class_name(std::string f_pName):CFrameworkunifiedCompositeState(f_pName) {} };
 111
 112 /// Defines the Orthogonal state that does not override entry and exit of base state
 113 #define DEFINE_ORTHOGONALSTATE(class_name) \
 114     class C## class_name : public CFrameworkunifiedOrthogonalState { \
 115      public: \
 116       C## class_name(std::string f_pName):CFrameworkunifiedOrthogonalState(f_pName) {} };
 117
 118
 119 ///////////////////////////////////////////////////////////////////////////////////////////
 120 /// \ingroup StateMachine_Macro
 121 /// \~english @par Brief
 122 ///        Macros that inherit CFrameworkunifiedLeafState classes.
 123 /// \~english @param [in] class_name Class name
 124 /// \~english @retval None
 125 /// \~english @par Prerequisite
 126 ///       - None
 127 /// \~english @par Change of internal state
 128 ///       - The internal state is not changed.
 129 /// \~english @par Conditions of processing failure
 130 ///       - None
 131 /// \~english @par Detail
 132 ///       Macros that inherit from CFrameworkunifiedLeafState classes and override the following methods:
 133 ///       The following overriding methods should be implemented by the user.
 134 ///       - FrameworkunifiedOnEntry
 135 ///       - FrameworkunifiedOnExit
 136 /// \~english @par Classification
 137 ///          Public
 138 /// \~english @see  None
 139 ///////////////////////////////////////////////////////////////////////////////////////////
 140 /// Defines the leafstate that overrides entry and exit of base state
 141 #define DEFINE_LEAFSTATE_OVERRIDE(class_name) \
 142     class C## class_name : public CFrameworkunifiedLeafState{ \
 143      public: \
 144       C## class_name(std::string f_pName); \
 145       virtual ~C## class_name(); \
 146       EFrameworkunifiedStatus FrameworkunifiedOnEntry(CEventDataPtr f_pEventData); \
 147       EFrameworkunifiedStatus FrameworkunifiedOnExit(CEventDataPtr f_pEventData); \
 148     };
 149
 150 ///////////////////////////////////////////////////////////////////////////////////////////
 151 /// \ingroup StateMachine_Macro
 152 /// \~english @par Brief
 153 ///        Macros that inherit CFrameworkunifiedCompositeState classes.
 154 /// \~english @param [in] class_name Class name
 155 /// \~english @retval None
 156 /// \~english @par Prerequisite
 157 ///       - None
 158 /// \~english @par Change of internal state
 159 ///       - The internal state is not changed.
 160 /// \~english @par Conditions of processing failure
 161 ///       - None
 162 /// \~english @par Detail
 163 ///       Macros that inherit from CFrameworkunifiedCompositeState classes and override the following methods:
 164 ///       The following overriding methods should be implemented by the user.
 165 ///       - FrameworkunifiedOnEntry
 166 ///       - FrameworkunifiedOnExit
 167 /// \~english @par Classification
 168 ///          Public
 169 /// \~english @see  None
 170 ///////////////////////////////////////////////////////////////////////////////////////////
 171 /// Defines the Composite state class that overrides entry and exit of base state
 172 #define DEFINE_COMPOSITESTATE_OVERRIDE(class_name) \
 173     class C## class_name : public CFrameworkunifiedCompositeState{ \
 174      public: \
 175       C## class_name(std::string f_pName); \
 176       virtual ~C## class_name(); \
 177       EFrameworkunifiedStatus FrameworkunifiedOnEntry(CEventDataPtr f_pEventData); \
 178       EFrameworkunifiedStatus FrameworkunifiedOnExit(CEventDataPtr f_pEventData); \
 179     };
 180
 181 ///////////////////////////////////////////////////////////////////////////////////////////
 182 /// \ingroup StateMachine_Macro
 183 /// \~english @par Brief
 184 ///        Macros that inherit CFrameworkunifiedOrthogonalState classes.
 185 /// \~english @param [in] class_name Class name
 186 /// \~english @retval None
 187 /// \~english @par Prerequisite
 188 ///       - None
 189 /// \~english @par Change of internal state
 190 ///       - The internal state is not changed.
 191 /// \~english @par Conditions of processing failure
 192 ///       - None
 193 /// \~english @par Detail
 194 ///       Macros that inherit from CFrameworkunifiedOrthogonalState classes and override the following methods:
 195 ///       The following overriding methods should be implemented by the user.
 196 ///       - FrameworkunifiedOnEntry
 197 ///       - FrameworkunifiedOnExit
 198 /// \~english @par Classification
 199 ///          Public
 200 /// \~english @see  None
 201 ///////////////////////////////////////////////////////////////////////////////////////////
 202 /// Defines the Orthogonal state that overrides entry and exit of base state
 203 #define DEFINE_ORTHOGONALSTATE_OVERRIDE(class_name) \
 204     class C## class_name : public CFrameworkunifiedOrthogonalState{ \
 205      public: \
 206       C## class_name(std::string f_pName); \
 207       virtual ~C## class_name(); \
 208       EFrameworkunifiedStatus FrameworkunifiedOnEntry(CEventDataPtr f_pEventData); \
 209       EFrameworkunifiedStatus FrameworkunifiedOnExit(CEventDataPtr f_pEventData); \
 210     };
 211
 212 ///////////////////////////////////////////////////////////////////////////////////////////
 213 /// \ingroup StateMachine_Macro
 214 /// \~english @par Brief
 215 ///        Macros that inherit CFrameworkunifiedInternalTransition classes.
 216 /// \~english @param [in] class_name Class name
 217 /// \~english @retval None
 218 /// \~english @par Prerequisite
 219 ///       - None
 220 /// \~english @par Change of internal state
 221 ///       - The internal state is not changed.
 222 /// \~english @par Conditions of processing failure
 223 ///       - None
 224 /// \~english @par Detail
 225 ///       Macros that inherit from CFrameworkunifiedInternalTransition classes and override the following methods:
 226 ///       The following overriding methods should be implemented by the user.
 227 ///       - FrameworkunifiedReaction
 228 /// \~english @par Classification
 229 ///          Public
 230 /// \~english @see  None
 231 ///////////////////////////////////////////////////////////////////////////////////////////
 232 /// Defines the InternalTransition class
 233 #define DEFINE_INTERNALTRANSITION(class_name) \
 234     class C## class_name : public CFrameworkunifiedInternalTransition{ \
 235      public: \
 236         virtual CFrameworkunifiedState* FrameworkunifiedReaction(CFrameworkunifiedState* f_pSourceState, CEventDataPtr f_pData); \
 237     };
 238
 239 ///////////////////////////////////////////////////////////////////////////////////////////
 240 /// \ingroup StateMachine_Macro
 241 /// \~english @par Brief
 242 ///        Macros that define application events.
 243 /// \~english @param [in] event_name Event name
 244 /// \~english @param [in] value Event value
 245 /// \~english @retval UI_32  Event value for the application
 246 /// \~english @par Prerequisite
 247 ///       - None
 248 /// \~english @par Change of internal state
 249 ///       - The internal state is not changed.
 250 /// \~english @par Conditions of processing failure
 251 ///       - None
 252 /// \~english @par Detail
 253 ///       Values of events defined in CFrameworkunifiedEventFactory classes (evFrameworkunifiedEventLimit:10) are specifiedMacros that define events for an application by adding event values (value).
 254 /// \~english @par Classification
 255 ///          Public
 256 /// \~english @see  None
 257 ///////////////////////////////////////////////////////////////////////////////////////////
 258 /// Defines the application event
 259 #define DEFINE_EVENT(event_name, value) \
 260     static const UI_32 _## event_name = CFrameworkunifiedEventFactory::evFrameworkunifiedEventLimit + value;
 261
 262 #define DEFINE_ACTION(class_name) \
 263     class C## class_name: public CFrameworkunifiedAction{ \
 264      public: \
 265         C## class_name(std::string f_strName):CFrameworkunifiedAction(f_strName) {} \
 266         VOID FrameworkunifiedAction(CFrameworkunifiedState *f_pSourceState, CFrameworkunifiedState *f_pTargetState, CEventDataPtr f_pEventData); \
 267     };
 268
 269 ///////////////////////////////////////////////////////////////////////////////////////////
 270 /// \ingroup StateMachine_Macro
 271 /// \~english @par Brief
 272 ///        This macro creates an instance for an internal transition.
 273 /// \~english @param [in] class_name Class name
 274 /// \~english @retval None
 275 /// \~english @par Prerequisite
 276 ///       - None
 277 /// \~english @par Change of internal state
 278 ///       - The internal state is not changed.
 279 /// \~english @par Conditions of processing failure
 280 ///       - None
 281 /// \~english @par Detail
 282 ///       This macro creates an instance for an internal transition of a class with the specified name.\n
 283 ///       Otherwise, the CNullPointerException objects are excepted.
 284 /// \~english @par Classification
 285 ///          Public
 286 /// \~english @see  None
 287 ///////////////////////////////////////////////////////////////////////////////////////////
 288 /// creates the instance of the internal transition
 289 #define CREATE_INTERNALTRANSITION(class_name) \
 290     C## class_name *l_pTrn## class_name = new C## class_name(); \
 291     CHKNULL(l_pTrn## class_name);
 292
 293 ///////////////////////////////////////////////////////////////////////////////////////////
 294 /// \ingroup StateMachine_Macro
 295 /// \~english @par Brief
 296 ///        This macro creates an instance for an external transition.
 297 /// \~english @param [in] target_state State name for external transition
 298 /// \~english @retval None
 299 /// \~english @par Prerequisite
 300 ///       - None
 301 /// \~english @par Change of internal state
 302 ///       - The internal state is not changed.
 303 /// \~english @par Conditions of processing failure
 304 ///       - None
 305 /// \~english @par Detail
 306 ///       Macros that instantiate CFrameworkunifiedExternalTransition classes for external transitions.\n
 307 ///       Otherwise, the CNullPointerException objects are excepted.
 308 /// \~english @par Classification
 309 ///          Public
 310 /// \~english @see  None
 311 ///////////////////////////////////////////////////////////////////////////////////////////
 312 /// creates the instance of the external transition
 313 #define CREATE_EXTERNALTRANSITION(target_state) \
 314     CFrameworkunifiedExternalTransition *l_pTrn## target_state  = new CFrameworkunifiedExternalTransition(l_p## target_state); \
 315     CHKNULL(l_pTrn## target_state);
 316
 317 /// creates the instance of the external transition
 318 #define CREATE_CONDITIONCONNECTOR(connector_name) \
 319     CFrameworkunifiedConditionConnector *l_pTrn## connector_name = new CFrameworkunifiedConditionConnector( #connector_name); \
 320     CHKNULL(l_pTrn## connector_name);
 321
 322
 323 /// creates the instance of the local transition
 324 #define CREATE_LOCALTRANSITION(target_state) \
 325     CFrameworkunifiedLocalTransition *l_pLocalTrn## target_state  = new CFrameworkunifiedLocalTransition(l_p## target_state); \
 326     CHKNULL(l_pLocalTrn## target_state);
 327
 328 ///////////////////////////////////////////////////////////////////////////////////////////
 329 /// \ingroup StateMachine_Macro
 330 /// \~english @par Brief
 331 ///        A macro that instantiates an orthographic region.
 332 /// \~english @param [in] target_state State name for external transition
 333 /// \~english @retval None
 334 /// \~english @par Prerequisite
 335 ///       - None
 336 /// \~english @par Change of internal state
 337 ///       - The internal state is not changed.
 338 /// \~english @par Conditions of processing failure
 339 ///       - None
 340 /// \~english @par Detail
 341 ///       Macros that create instances of compound states (CFrameworkunifiedCompositeState classes) as instances of orthographic regions.\n
 342 /// \~english @par Classification
 343 ///          Public
 344 /// \~english @see  None
 345 ///////////////////////////////////////////////////////////////////////////////////////////
 346 /// create orthogonal region
 347 #define CREATE_ORTHOGONALREGION(name) \
 348     CFrameworkunifiedCompositeState *l_p## name = new CFrameworkunifiedCompositeState(#name);
 349
 350 /// create action for external transition
 351 #define CREATE_ACTION(class_name) \
 352     C## class_name *l_pTrn## class_name = new C## class_name( #class_name); \
 353     CHKNULL(l_pTrn## class_name);
 354
 355
 356 ///////////////////////////////////////////////////////////////////////////////////////////
 357 /// \ingroup StateMachine_Macro
 358 /// \~english @par Brief
 359 ///        A macro that defines events for the framework.
 360 /// \~english @param [in] eventid Event ID
 361 /// \~english @retval None
 362 /// \~english @par Prerequisite
 363 ///       - None
 364 /// \~english @par Change of internal state
 365 ///       - The internal state is not changed.
 366 /// \~english @par Conditions of processing failure
 367 ///       - None
 368 /// \~english @par Detail
 369 ///       These macros define the IDs of the current events in the CFrameworkunifiedHSMParentFramework classes.
 370 /// \~english @par Classification
 371 ///          Public
 372 /// \~english @see  None
 373 ///////////////////////////////////////////////////////////////////////////////////////////
 374 /// framework event
 375 #define FRAMEWORKUNIFIED_EVENT(eventid) \
 376     CFrameworkunifiedHSMParentFramework::_## eventid
 377
 378 ///////////////////////////////////////////////////////////////////////////////////////////
 379 /// \ingroup StateMachine_Macro
 380 /// \~english @par Brief
 381 ///        Is a macro that defines events for an application
 382 /// \~english @param [in] eventid Event ID
 383 /// \~english @retval None
 384 /// \~english @par Prerequisite
 385 ///       - None
 386 /// \~english @par Change of internal state
 387 ///       - The internal state is not changed.
 388 /// \~english @par Conditions of processing failure
 389 ///       - None
 390 /// \~english @par Detail
 391 ///       A macro that defines an event ID for an application.
 392 /// \~english @par Classification
 393 ///          Public
 394 /// \~english @see  None
 395 ///////////////////////////////////////////////////////////////////////////////////////////
 396 /// Application event
 397 #define EVENT(eventid) \
 398     _## eventid
 399
 400 /// FrameworkunifiedReaction function signature for internal transition class
 401 #define IMPLEMENT_INTERNALTRANSITION(name) \
 402     CFrameworkunifiedState* C## name::FrameworkunifiedReaction(CFrameworkunifiedState* f_pSourceState, CEventDataPtr f_pData)
 403
 404 #define IMPLEMENT_ACTION(action_name) \
 405     void C## action_name::FrameworkunifiedAction(CFrameworkunifiedState *f_pSourceState, CFrameworkunifiedState *f_pTargetState, CEventDataPtr f_pEventData)
 406
 407 #define DEFINE_GUARD(guard_name)\
 408   class C## guard_name : public CFrameworkunifiedGuard{ \
 409    public: \
 410       C## guard_name(std::string f_pName):CFrameworkunifiedGuard(f_pName) {} \
 411       virtual BOOL FrameworkunifiedEvaluate();\
 412   };
 413
 414 #define CREATE_GUARD(guard_name)\
 415     CFrameworkunifiedGuard *l_pGrd## guard_name = new C## guard_name(#guard_name);
 416
 417 #define CONNECT_GUARD(transition, guard)\
 418   l_pTrn## transition->FrameworkunifiedSetGuard(l_pGrd## guard);
 419
 420 #define CONNECT_CONDITION(connector_name , guard , target_state) \
 421   CHKNULL(l_pTrn## connector_name)\
 422   l_pTrn## connector_name->FrameworkunifiedAddCondition(l_pGrd## guard , l_p## target_state); \
 423
 424 #define IMPLEMENT_GUARD(guard_name) \
 425   BOOL C## guard_name::FrameworkunifiedEvaluate()
 426
 427
 428 ///////////////////////////////////////////////////////////////////////////////////////////
 429 /// \ingroup StateMachine_Macro
 430 /// \~english @par Brief
 431 ///        These macros create instances for Shallow history transitions.
 432 /// \~english @param [in] parent State name for external transition
 433 /// \~english @retval None
 434 /// \~english @par Prerequisite
 435 ///       - None
 436 /// \~english @par Change of internal state
 437 ///       - The internal state is not changed.
 438 /// \~english @par Conditions of processing failure
 439 ///       - None
 440 /// \~english @par Detail
 441 ///       These macros create instances of CFrameworkunifiedExternalTransition classes for external transitions of Shallow history transitions.\n
 442 ///       Otherwise, the CNullPointerException objects are excepted.
 443 /// \~english @par Classification
 444 ///          Public
 445 /// \~english @see  None
 446 ///////////////////////////////////////////////////////////////////////////////////////////
 447 /// creates the instance of the shallow history transition
 448 #define CREATE_SHALLOWHISTORYTRANSITION(parent) \
 449     CFrameworkunifiedExternalTransition *l_pTrn##parent##SHALLOWHISTORYSTATE = \
 450     new CFrameworkunifiedExternalTransition(l_p##parent##SHALLOWHISTORYSTATE); \
 451     CHKNULL(l_pTrn##parent##SHALLOWHISTORYSTATE);
 452
 453 /// creates the instance of the deep history transition
 454 #define CREATE_DEEPHISTORYTRANSITION(parent) \
 455     CFrameworkunifiedExternalTransition *l_pTrn##parent##DEEPHISTORYSTATE = \
 456     new CFrameworkunifiedExternalTransition(l_p##parent##DEEPHISTORYSTATE); \
 457     CHKNULL(l_pTrn##parent##DEEPHISTORYSTATE);
 458
 459 #define CONNECT_CONDITION_SHALLOWHISTORYTRANSITION(connector_name , guard , target_state) \
 460     CHKNULL(l_pTrn## connector_name)\
 461     l_pTrn## connector_name->FrameworkunifiedAddCondition(l_pGrd## guard , l_p## target_state##SHALLOWHISTORYSTATE); \
 462
 463
 464 #define CONNECT_CONDITION_DEEPHISTORYTRANSITION(connector_name , guard , target_state) \
 465     CHKNULL(l_pTrn## connector_name)\
 466     l_pTrn## connector_name->FrameworkunifiedAddCondition(l_pGrd## guard , l_p## target_state##DEEPHISTORYSTATE); \
 467
 468
 469 #define CONNECT_ACTION(transition, action_name) \
 470     CHKNULL(l_pTrn## action_name); \
 471     CHKNULL(l_pTrn## transition); \
 472     l_pTrn## transition->FrameworkunifiedAddAction(l_pTrn## action_name); \
 473
 474 #ifdef DEBUG
 475 #define FRAMEWORKUNIFIED_PRINT_HSM(x) (FrameworkunifiedGetStateMachine(x))->FrameworkunifiedPrintXML();
 476 #define PRINT_HSM() FrameworkunifiedPrintXML();
 477 #else
 478 #define FRAMEWORKUNIFIED_PRINT_HSM(x)
 479 #define PRINT_HSM()
 480 #endif
 481
 482 /// defines options for integrating user change state
 483 typedef enum _EUserChangeOptions {
 484   eUserchangeIgnore = 0,
 485   eUserchangeReInit,
 486   eUserchangeRetPrevState
 487 } EUserChangeOptions;
 488 #endif /* __FRAMEWORKUNIFIED_NATIVESERVICES_NATIVESERVICES_INC_FRAMEWORK_STATEMACHINE_FRAMEWORKUNIFIED_FRAMEWORKUNIFIED_SM_FRAMEWORK_TYPES_H__ */  // NOLINT  (build/header_guard)
 489 /** @}*/
 490 /** @}*/
 491 /** @}*/
 492 /** @}*/
 493 /** @}*/
 494 //@}