video_in_hal/nsframework/framework_unified/client/include/native_service/frameworkunified_sm_state.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 the CFrameworkunifiedState class definitions. CFrameworkunifiedState is base class for all types of
  22 /// state classes.This class implements the basic functionality required for HSM state.
  23 /// It provides the standard interfaces for entering, exiting and reacting in a state.
  24 ///
  25 ///////////////////////////////////////////////////////////////////////////////
  26 //@{
  27 /**
  28  * @file frameworkunified_sm_state.h
  29  * @brief \~english This file has the CFrameworkunifiedState class definitions. CFrameworkunifiedState is base class for all types of
  30  *        state classes.This class implements the basic functionality required for HSM state.
  31  *        It provides the standard interfaces for entering, exiting and reacting in a state.
  32  *
  33  */
  34 /** @addtogroup BaseSystem
  35  *  @{
  36  */
  37 /** @addtogroup native_service
  38  *  @ingroup BaseSystem
  39  *  @{
  40  */
  41 /** @addtogroup framework_unified
  42  *  @ingroup native_service
  43  *  @{
  44  */
  45 /** @addtogroup framework
  46  *  @ingroup framework_unified
  47  *  @{
  48  */
  49 /** @addtogroup statemachine
  50  *  @ingroup framework
  51  *  @{
  52  */
  53 #ifndef __FRAMEWORKUNIFIED_NATIVESERVICES_NATIVESERVICES_INC_FRAMEWORK_STATEMACHINE_FRAMEWORKUNIFIED_SM_STATE_H__  // NOLINT  (build/header_guard)
  54 #define __FRAMEWORKUNIFIED_NATIVESERVICES_NATIVESERVICES_INC_FRAMEWORK_STATEMACHINE_FRAMEWORKUNIFIED_SM_STATE_H__
  55
  56 ///////////////////////////////////////////////////////////////////////////////////////////////////
  57 // Include Files
  58 ///////////////////////////////////////////////////////////////////////////////////////////////////
  59
  60 #include <native_service/frameworkunified_sm_reaction.h>
  61 #include <string>
  62 #include <map>
  63 #include <exception>
  64 #include <vector>
  65
  66 class CFrameworkunifiedReaction;
  67 class CFrameworkunifiedHSM;
  68
  69 /// defines the map of event reactions
  70 typedef std::map<UI_32, CFrameworkunifiedReaction *> EventReactionList;
  71
  72 typedef std::vector<UI_32>  DeferredEventList;
  73
  74 /// defines the map of event names
  75 typedef std::map<UI_32, std::string>   EventNameList;
  76
  77 /// defines the iterator for event reaction map
  78 typedef std::map<UI_32, CFrameworkunifiedReaction *>::iterator EventReactionIterator;;
  79
  80 typedef std::vector<CEventDataPtr>  EventInfoList;
  81
  82 ///////////////////////////////////////////////////////////////////////////////////////////////////
  83 /// This class implements the basic functionality required for HSM state. It provides the standard
  84 /// interfaces for entering, exiting and reacting in a state.
  85 ///////////////////////////////////////////////////////////////////////////////////////////////////
  86 class CFrameworkunifiedState {
  87  public :
  88   ///////////////////////////////////////////////////////////////////////////////////////////
  89   /// \ingroup CFrameworkunifiedState
  90   /// \~english @par Brief
  91   ///        CFrameworkunifiedState constructor
  92   /// \~english @param [in] f_pName
  93   ///        std::string   - Name of the state
  94   /// \~english @retval None
  95   /// \~english @par Prerequisite
  96   ///       - None
  97   /// \~english @par Change of internal state
  98   ///       - None
  99   /// \~english @par Conditions of processing failure
 100   ///       - None
 101   /// \~english @par Detail
 102   ///       This clase is a base class of state machine. \n
 103   ///       It creates object of CFrameworkunifiedState class, and initializes the member variable with state name specified by
 104   ///       argument(f_pName). \n
 105   ///       It creates the following event lists, and saves them as member variables. About the other member variables,
 106   ///       it initialzes them with NULL. \n
 107   ///       If error occurs, output the error log. \n
 108   ///       - list of events associated with the state(used for managing state of eace event)
 109   ///       - list of deferred events associated with the state(used for managing state of deferred event)
 110   ///       - list of deferred events posted in the state(used for posting list of deferred events)
 111   ///       - list of event names(used for managing event names)
 112   /// \~english @par Classification
 113   ///          public
 114   /// \~english @par Type
 115   ///       sync only
 116   /// \~english @see ~CFrameworkunifiedState
 117   ///////////////////////////////////////////////////////////////////////////////////////////
 118   /// CFrameworkunifiedState
 119   /// Parameterized constructor
 120   /// \param [in] f_pName
 121   ///     string - Name of the state
 122   ///
 123   /// \return none
 124   CFrameworkunifiedState(std::string f_pName);  // NOLINT  (readability/nolint)
 125
 126   ///////////////////////////////////////////////////////////////////////////////////////////
 127   /// \ingroup CFrameworkunifiedState
 128   /// \~english @par Brief
 129   ///        CFrameworkunifiedState destructor
 130   /// \~english @param None
 131   /// \~english @retval None
 132   /// \~english @par Prerequisite
 133   ///       - Calls constructor to successfully create object.
 134   /// \~english @par Change of internal state
 135   ///       - None
 136   /// \~english @par Conditions of processing failure
 137   ///       - None
 138   /// \~english @par Detail
 139   ///       This class destroys object of CFrameworkunifiedState class.\n
 140   ///       It destroys the following event list. If error occurs, output the error log.
 141   ///       - list of events associated with the state
 142   ///       - list of deferred events associated with the state
 143   ///       - list of deferred events posted in the state
 144   ///       - list of event names
 145   /// \~english @par Classification
 146   ///          public
 147   /// \~english @par Type
 148   ///       sync only
 149   /// \~english @see CFrameworkunifiedState
 150   ///////////////////////////////////////////////////////////////////////////////////////////
 151   ///////////////////////////////////////////////////////////////////////////////////////////
 152   /// ~CFrameworkunifiedState
 153   /// Class destructor
 154   ///
 155   /// \return none
 156   virtual ~CFrameworkunifiedState();
 157
 158   /////////////////////////////////////////////////////////////////////////////////////
 159   /// \ingroup CFrameworkunifiedState
 160   /// \~english @par Brief
 161   ///        add event information
 162   /// \~english @param [in] f_uiEventId
 163   ///        UI_32 f_uiEventId  -  event ID
 164   /// \~english @param [in] f_pReaction
 165   ///        CFrameworkunifiedReaction *f_pReaction  -  event reaction
 166   /// \~english @param [in] f_strEventName
 167   ///        std::string f_strEventName  -  event name
 168   /// \~english @retval eFrameworkunifiedStatusOK   add event success
 169   /// \~english @retval eFrameworkunifiedStatusNullPointer  exception occur when add event
 170   /// \~english @par Prerequisite
 171   ///        None
 172   /// \~english @par Change of internal state
 173   ///        None
 174   /// \~english @par Conditions of processing failure
 175   ///        given param is NULL
 176   /// \~english @par Detail
 177   ///        add event information to event list, failed if given param is NULL
 178   /// \~english @par Classification
 179   ///        Public
 180   /// \~english @par Type
 181   ///        sync only
 182   /// \~english @see
 183   ///
 184   /////////////////////////////////////////////////////////////////////////////////////
 185   ///////////////////////////////////////////////////////////////////////////////////////////
 186   /// FrameworkunifiedAddEvent
 187   /// Associates the event id with the reaction in the state. When the event is posted to the
 188   /// state the associated reaction is executed. This also adds the event name to the map
 189   /// which is used for debugging.
 190   ///
 191   /// \param [in] f_uiEventId
 192   ///     UI_32 - Event id of the event to be added in the state
 193   ///
 194   /// \param [in] f_pReaction
 195   ///     CFrameworkunifiedReaction* - Reaction to be associated with the with event id in the state
 196   ///
 197   /// \param [in] f_strEventName
 198   ///     string - Name of the event (used for debugging purpose only)
 199   ///
 200   /// \return EFrameworkunifiedStatus
 201   ///         EFrameworkunifiedStatus - Returns status of operation
 202   ///
 203   ///////////////////////////////////////////////////////////////////////////////////////////
 204   EFrameworkunifiedStatus FrameworkunifiedAddEvent(UI_32 f_uiEventId, CFrameworkunifiedReaction *f_pReaction, std::string f_strEventName = "");
 205
 206   ///////////////////////////////////////////////////////////////////////////////////////////
 207   /// \ingroup CFrameworkunifiedState
 208   /// \~english @par Brief
 209   ///        This function processes the event.
 210   /// \~english @param [in] f_pEventData
 211   ///      CEventDataPtr - Pointer to event data class
 212   /// \~english @retval CFrameworkunifiedState*  Pointer to current CFrameworkunifiedState object after processing event
 213   /// \~english @par Prerequisite
 214   ///        - Calls constructor to successfully create object.
 215   ///        - State machine of current state in the applicaton is setted in FrameworkunifiedSetHSM.
 216   /// \~english @par Change of internal state
 217   ///        - None
 218   /// \~english @par Conditions of processing failure
 219   ///        - Failed to call constructor to create object. [this(current CFrameworkunifiedState object]
 220   ///        - Pointer to event data class is NULL. [NULL]
 221   /// \~english @par Detail
 222   ///        This function processes the event. If the reaction for event is available in the current
 223   ///        state within eventlist and deferred eventlist then it is consumed in the current state
 224   ///        otherwise forwarded to the parent state. Event forwarding is done recursively till either
 225   ///        event is consumed or the root state has encountered. This also process the events posted
 226   ///        in the reactions recursively till all posted events are cleared.
 227   /// \~english @par Classification
 228   ///        Public
 229   /// \~english @par Type
 230   ///        sync only
 231   /// \~english @see CEventData, FrameworkunifiedIsReactionAvailable
 232   ///
 233   ///////////////////////////////////////////////////////////////////////////////////////////
 234   ///////////////////////////////////////////////////////////////////////////////////////////
 235   /// FrameworkunifiedOnEvent
 236   /// This function processes the event. If the reaction for event is available in the current
 237   /// state within eventlist and deferred eventlist then it is consumed in the current state
 238   /// otherwise forwarded to the parent state. Event forwarding is done recursively till either
 239   /// event is consumed or the root state has encountered. This also process the events posted
 240   /// in the reactions recursively till all posted events are cleared.
 241   ///
 242   /// \param [in] f_pEventData
 243   ///     CEventDataPtr - Event data
 244   ///
 245   ///
 246   /// \return state
 247   ///         CFrameworkunifiedState* - Returns current state after the event is processed
 248   ///
 249   virtual CFrameworkunifiedState *FrameworkunifiedOnEvent(CEventDataPtr f_pEventData);
 250
 251   /////////////////////////////////////////////////////////////////////////////////////
 252   /// \ingroup CFrameworkunifiedState
 253   /// \~english @par Brief
 254   ///        add deferred event information
 255   /// \~english @param [in] f_uiEventId
 256   ///        UI_32 f_uiEventId  -  event ID
 257   /// \~english @param [in] f_strEventName
 258   ///        std::string f_strEventName  -  event name
 259   /// \~english @retval eFrameworkunifiedStatusOK   add deferred event success
 260   /// \~english @retval eFrameworkunifiedStatusNullPointer  exception occur when add deferred event
 261   /// \~english @par Prerequisite
 262   ///        None
 263   /// \~english @par Change of internal state
 264   ///        None
 265   /// \~english @par Conditions of processing failure
 266   ///        given param is NULL
 267   /// \~english @par Detail
 268   ///        add deferred event information to event list , failed if given param is NULL
 269   /// \~english @par Classification
 270   ///        Public
 271   /// \~english @par Type
 272   ///        sync only
 273   /// \~english @see
 274   ///
 275   /////////////////////////////////////////////////////////////////////////////////////
 276   ///////////////////////////////////////////////////////////////////////////////////////////
 277   /// FrameworkunifiedAddDeferredEvent
 278   /// Associates the deferred event id with the reaction in the state. When the event is posted
 279   /// to the state the event is deferred and stored in the state. In case of implicit recall
 280   /// of the deferred events, events are processed before exiting the state. The deferred
 281   /// events can also be recalled explicitly in the state  This also adds the event name
 282   /// to the map which is used for debugging.
 283   ///
 284   /// \param [in] f_uiEventId
 285   ///     UI_32 - Event id of the event to be added in the state
 286   ///
 287   /// \param [in] f_strEventName
 288   ///     string - Name of the event (used for debugging purpose only)
 289   ///
 290   /// \return EFrameworkunifiedStatus
 291   ///         EFrameworkunifiedStatus - Returns status of operation
 292   ///
 293   ///////////////////////////////////////////////////////////////////////////////////////////
 294   EFrameworkunifiedStatus FrameworkunifiedAddDeferredEvent(UI_32 f_uiEventId, std::string f_strEventName = "");
 295
 296   ///////////////////////////////////////////////////////////////////////////////////////////
 297   /// \ingroup CFrameworkunifiedState
 298   /// \~english @par Brief
 299   ///        This function creates new eventdata object and add it to event queue of the state machine.
 300   /// \~english @param [in] f_uiEventId
 301   ///        UI_32 f_uiEventId  -  event ID
 302   /// \~english @retval eFrameworkunifiedStatusOK   post event success
 303   /// \~english @retval eFrameworkunifiedStatusNullPointer  exception occur when post event
 304   /// \~english @par Prerequisite
 305   ///        - Calls constructor to successfully create object.
 306   ///        - State machine of current state in the applicaton is setted in FrameworkunifiedSetHSM.
 307   /// \~english @par Change of internal state
 308   ///        - None
 309   /// \~english @par Conditions of processing failure
 310   ///       - State machine of application is NULL. [eFrameworkunifiedStatusNullPointer]
 311   ///       - Failed to create object of eventdata. [eFrameworkunifiedStatusNullPointer]
 312   ///       - Pointer to event list in which to add eventdata in state machine is NULL. [eFrameworkunifiedStatusNullPointer]
 313   ///       - Pointer to active state in state machine is NULL. [eFrameworkunifiedStatusNullPointer]
 314   ///       - Name of active state in state machine is NULL. [eFrameworkunifiedStatusNullPointer]
 315   /// \~english @par Detail
 316   ///       This function creates new eventdata object and add it to event queue of the state machine.\n
 317   ///       The events are posted in the reaction which are executed in the state.
 318   ///       The event queue is processed once the execution of the reaction is completed.
 319   /// \~english @par Classification
 320   ///        Public
 321   /// \~english @par Type
 322   ///        sync only
 323   /// \~english @see FrameworkunifiedPostEvent(CEventDataPtr), CEventData, CFrameworkunifiedHSM::FrameworkunifiedQueueEvent, CFrameworkunifiedHSM::ProcessEvent
 324   ///
 325   ///////////////////////////////////////////////////////////////////////////////////////////
 326   ///////////////////////////////////////////////////////////////////////////////////////////
 327   /// FrameworkunifiedPostEvent
 328   /// This function creates new eventdata object and add the to event queue of the state.
 329   /// The events are posted in the reaction which are executed in the state.
 330   /// The event queue is processed once the execution of the reaction is completed.
 331   ///
 332   /// \param [in] f_uiEventId
 333   ///     UI_32 - Event Id
 334   ///
 335   /// \return EFrameworkunifiedStatus
 336   ///         EFrameworkunifiedStatus - Returns status of operation
 337   ///
 338   EFrameworkunifiedStatus FrameworkunifiedPostEvent(UI_32 f_uiEventId);
 339
 340   ///////////////////////////////////////////////////////////////////////////////////////////
 341   /// \ingroup CFrameworkunifiedState
 342   /// \~english @par Brief
 343   ///        This function adds event data to event queue of the state machine.
 344   /// \~english @param [in] f_pEventData
 345   ///      CEventDataPtr - Pointer to event data class
 346   /// \~english @retval eFrameworkunifiedStatusOK   post event success
 347   /// \~english @retval eFrameworkunifiedStatusNullPointer  exception occur when post event
 348   /// \~english @par Prerequisite
 349   ///        - Calls constructor to successfully create object.
 350   ///        - State machine of current state in the applicaton is setted in FrameworkunifiedSetHSM.
 351   /// \~english @par Change of internal state
 352   ///        - None
 353   /// \~english @par Conditions of processing failure
 354   ///      - State machine of application is NULL. [eFrameworkunifiedStatusNullPointer]
 355   ///       - Pointer to event data class specified by argument(f_pEventData) is NULL. [eFrameworkunifiedStatusNullPointer]
 356   ///       - Pointer to event list in which to add eventdata in state machine is NULL. [eFrameworkunifiedStatusNullPointer]
 357   ///       - Pointer to active state in state machine is NULL. [eFrameworkunifiedStatusNullPointer]
 358   ///       - Name of active state in state machine is NULL. [eFrameworkunifiedStatusNullPointer]
 359   /// \~english @par Detail
 360   ///        This function adds event data to event queue of the state machine. The events are posted in the reaction
 361   ///        which are executed in the state. The event queue is processed once the execution of the
 362   ///        reaction is completed.
 363   /// \~english @par Classification
 364   ///        Public
 365   /// \~english @par Type
 366   ///        sync only
 367   /// \~english @see CEventData, FrameworkunifiedIsReactionAvailable, CFrameworkunifiedHSM::FrameworkunifiedQueueEvent, CFrameworkunifiedHSM::ProcessEvent
 368   ///////////////////////////////////////////////////////////////////////////////////////////
 369   ///////////////////////////////////////////////////////////////////////////////////////////
 370   /// FrameworkunifiedPostEvent
 371   /// This function adds the event queue of the state. The events are posted in the reaction
 372   /// which are executed in the state. The event queue is processed once the execution of the
 373   /// reaction is completed.
 374   ///
 375   /// \param [in] f_pEventData
 376   ///     CEventDataPtr - Event data
 377   ///
 378   /// \return EFrameworkunifiedStatus
 379   ///         EFrameworkunifiedStatus - Returns status of operation
 380   ///
 381   EFrameworkunifiedStatus FrameworkunifiedPostEvent(CEventDataPtr f_pEventData);
 382
 383   /////////////////////////////////////////////////////////////////////////////////////
 384   /// \ingroup CFrameworkunifiedState
 385   /// \~english @par Brief
 386   ///        delete event from deferred event list
 387   /// \~english @param [in] f_uiEventId
 388   ///        UI_32 f_uiEventId  -  event ID
 389   /// \~english @retval eFrameworkunifiedStatusOK   delete deferred event success
 390   /// \~english @retval eFrameworkunifiedStatusInvldID   invalid event ID
 391   /// \~english @retval eFrameworkunifiedStatusNullPointer  exception occur when delete deferred event
 392   /// \~english @par Prerequisite
 393   ///        None
 394   /// \~english @par Change of internal state
 395   ///        None
 396   /// \~english @par Conditions of processing failure
 397   ///        None
 398   /// \~english @par Detail
 399   ///        delete event from deferred event list by event ID
 400   ///        failed if event id is not exist. exception occur if given param is NULL
 401   /// \~english @par Classification
 402   ///        Public
 403   /// \~english @par Type
 404   ///        sync only
 405   /// \~english @see
 406   ///
 407   /////////////////////////////////////////////////////////////////////////////////////
 408   ///////////////////////////////////////////////////////////////////////////////////////////
 409   /// FrameworkunifiedRemoveEventFromDeferredEventList
 410   /// This function removes the event from the posted deferred queue list of the state.
 411   ///
 412   /// \param [in] f_uiEventId
 413   ///     UI_32 - Event id
 414   ///
 415   /// \return EFrameworkunifiedStatus
 416   ///         EFrameworkunifiedStatus - eFrameworkunifiedStatusOK if event removed
 417   ///            eFrameworkunifiedStatusInvldID if event not found in list
 418   ///
 419   ///////////////////////////////////////////////////////////////////////////////////////////
 420   EFrameworkunifiedStatus FrameworkunifiedRemoveEventFromDeferredEventList(UI_32 f_uiEventId);
 421
 422   ///////////////////////////////////////////////////////////////////////////////////////////
 423   /// \ingroup CFrameworkunifiedState
 424   /// \~english @par Brief
 425   ///        This function indicates if the state has sub states.
 426   /// \~english @param None
 427   /// \~english @retval BOOL  if the state has sub states
 428   /// \~english @par Prerequisite
 429   ///        - Calls constructor to successfully create object.
 430   /// \~english @par Change of internal state
 431   ///        - None
 432   /// \~english @par Conditions of processing failure
 433   ///        - None
 434   /// \~english @par Detail
 435   ///        This function indicates if the state has sub states. It returns TRUE only in the CompositeState
 436   ///        where this function is overridden
 437   /// \~english @par Classification
 438   ///        Public
 439   /// \~english @par Type
 440   ///        sync only
 441   /// \~english @see CFrameworkunifiedCompositeState::FrameworkunifiedHasSubStates
 442   ///
 443   ///////////////////////////////////////////////////////////////////////////////////////////
 444   ///////////////////////////////////////////////////////////////////////////////////////////
 445   /// FrameworkunifiedHasSubStates
 446   /// This indicates if the state has sub states. It returns TRUE only in the CompositeState
 447   /// where this function is overridden
 448   ///
 449   /// \return TRUE/FASLE
 450   ///     BOOL - returns TRUE if it has sub states otherwise returns false.
 451   virtual BOOL FrameworkunifiedHasSubStates();
 452
 453   ///////////////////////////////////////////////////////////////////////////////////////////
 454   /// \ingroup CFrameworkunifiedState
 455   /// \~english @par Brief
 456   ///        This function indicates if the state has sub states.
 457   /// \~english @param None
 458   /// \~english @retval BOOL  if the state has sub states
 459   /// \~english @par Prerequisite
 460   ///        - Calls constructor to successfully create object.
 461   /// \~english @par Change of internal state
 462   ///        - None
 463   /// \~english @par Conditions of processing failure
 464   ///        - None
 465   /// \~english @par Detail
 466   ///        This function indicates if the state has sub states. It returns TRUE only in the OrthogonalState
 467   ///        where this function is overridden
 468   /// \~english @par Classification
 469   ///        Public
 470   /// \~english @par Type
 471   ///        sync only
 472   /// \~english @see CFrameworkunifiedOrthogonalState
 473   ///////////////////////////////////////////////////////////////////////////////////////////
 474   ///////////////////////////////////////////////////////////////////////////////////////////
 475   /// FrameworkunifiedHasOrthogoanlRegions
 476   /// This indicates if the state has sub states. It returns TRUE only in the OrthogonalState
 477   /// where this function is overridden
 478   ///
 479   /// \return TRUE/FASLE
 480   ///     BOOL - returns TRUE if it has sub states otherwise returns false.
 481   ///////////////////////////////////////////////////////////////////////////////////////////
 482   virtual BOOL FrameworkunifiedHasOrthogoanlRegions();
 483
 484   ///////////////////////////////////////////////////////////////////////////////////////////
 485   /// \ingroup CFrameworkunifiedState
 486   /// \~english @par Brief
 487   ///        This logs the state name and event name associated with the state
 488   /// \~english @param None
 489   /// \~english @retval eFrameworkunifiedStatusOK  success
 490   /// \~english @retval eFrameworkunifiedStatusNullPointer  null pointer exception
 491   /// \~english @par Prerequisite
 492   ///        - Calls constructor to successfully create object.
 493   /// \~english @par Change of internal state
 494   ///        - None
 495   /// \~english @par Conditions of processing failure
 496   ///        - Failed to call constructor to create object. [eFrameworkunifiedStatusNullPointer]
 497   /// \~english @par Detail
 498   ///       This logs the state name and event name associated with the state. \n
 499   ///       It outputs the following logs:
 500   ///       - state name of parent state machine and self state machine
 501   ///       - all event names in event list
 502   ///       - all event names in deferred event list
 503   ///       CFrameworkunifiedCompositeState and CFrameworkunifiedOrthogonalState class overrides this function
 504   ///       and use it.
 505   /// \~english @par Classification
 506   ///        Public
 507   /// \~english @par Type
 508   ///        sync only
 509   /// \~english @see
 510   ///////////////////////////////////////////////////////////////////////////////////////////
 511   ///////////////////////////////////////////////////////////////////////////////////////////
 512   /// FrameworkunifiedPrintStates
 513   /// This logs the state name and events associated with the state
 514   ///
 515   /// \return EFrameworkunifiedStatus
 516   ///     EFrameworkunifiedStatus - Returns status of operation
 517   ///////////////////////////////////////////////////////////////////////////////////////////
 518   virtual  EFrameworkunifiedStatus FrameworkunifiedPrintStates();
 519
 520   ///////////////////////////////////////////////////////////////////////////////////////////
 521   /// \ingroup CFrameworkunifiedState
 522   /// \~english @par Brief
 523   ///        Initialize state.
 524   /// \~english @param [in] f_pEventData
 525   ///      CEventDataPtr - Pointer to event data class
 526   /// \~english @retval CFrameworkunifiedState*  Pointer to current CFrameworkunifiedState object after processing event
 527   /// \~english @retval NULL        error occurs in internal process
 528   /// \~english @par Prerequisite
 529   ///        - Calls constructor to successfully create object.
 530   ///        - State machine of current state in the applicaton is setted in FrameworkunifiedSetHSM.
 531   /// \~english @par Change of internal state
 532   ///        - None
 533   /// \~english @par Conditions of processing failure
 534   ///        - Failed to call function(FrameworkunifiedOnEntry) recursively. [NULL]
 535   /// \~english @par Detail
 536   ///        This function is called recursively till the leaf state is reached. This internally
 537   ///        calls the Entry function of the current state.
 538   /// \~english @par Classification
 539   ///        Public
 540   /// \~english @par Type
 541   ///        sync only
 542   /// \~english @see CEventData, FrameworkunifiedOnEntry, FrameworkunifiedOnHSMStop
 543   ///////////////////////////////////////////////////////////////////////////////////////////
 544   ///////////////////////////////////////////////////////////////////////////////////////////
 545   /// FrameworkunifiedOnHSMStart
 546   /// This function is called recursively till the leaf state is reached. This internally
 547   /// calls the Entry function of the current state.
 548   ///
 549   /// \param [in] f_pEventData
 550   ///     CEventDataPtr - Event data
 551   ///
 552   /// \return CurrentState
 553   ///     CFrameworkunifiedState* - Returns current state after operation
 554   ///////////////////////////////////////////////////////////////////////////////////////////
 555   virtual CFrameworkunifiedState *FrameworkunifiedOnHSMStart(CEventDataPtr f_pEventData);
 556
 557   ///////////////////////////////////////////////////////////////////////////////////////////
 558   /// \ingroup CFrameworkunifiedState
 559   /// \~english @par Brief
 560   ///        Clearup state.
 561   /// \~english @param [in] f_pEventData
 562   ///      CEventDataPtr - Pointer to event data class
 563   /// \~english @retval CFrameworkunifiedState*  Pointer to current CFrameworkunifiedState object after processing event
 564   /// \~english @retval NULL        error occurs in internal process
 565   /// \~english @par Prerequisite
 566   ///        - Calls constructor to successfully create object.
 567   ///        - State machine of current state in the applicaton is setted in FrameworkunifiedSetHSM.
 568   /// \~english @par Change of internal state
 569   ///        - None
 570   /// \~english @par Conditions of processing failure
 571   ///       - Failed to call constructor to create object. [NULL]
 572   ///       - Pointer to list of deferred events posted in the state is NULL. [NULL]
 573   ///       - Pointer to event data getted from list of deferred events posted in the state is NULL. [NULL]
 574   ///       - Event name of event data getted from list of deferred events posted in the state is NULL. [NULL]
 575   /// \~english @par Detail
 576   ///       This function is called recursively till the required parent state is reached. This
 577   ///       internally calls the Exit function of the current state.
 578   /// \~english @par Classification
 579   ///        Public
 580   /// \~english @par Type
 581   ///        sync only
 582   /// \~english @see CEventData, FrameworkunifiedOnExit, FrameworkunifiedOnHSMStart
 583   ///////////////////////////////////////////////////////////////////////////////////////////
 584   ///////////////////////////////////////////////////////////////////////////////////////////
 585   /// FrameworkunifiedOnHSMStop
 586   /// This function is called recursively till the required parent state is reached. This
 587   /// internally calls the Exit function of the current state.
 588   ///
 589   /// \param [in] f_pEventData
 590   ///     CECEventDataPtr Event data
 591   /// \return CurrentState
 592   ///     CFrameworkunifiedState* - Returns current state after operation
 593   ///////////////////////////////////////////////////////////////////////////////////////////
 594   virtual CFrameworkunifiedState *FrameworkunifiedOnHSMStop(CEventDataPtr f_pEventData);
 595
 596   ///////////////////////////////////////////////////////////////////////////////////////////
 597   /// \ingroup CFrameworkunifiedState
 598   /// \~english @par Brief
 599   ///        Check the availability of event.
 600   /// \~english @param [in] f_uiEventId
 601   ///       UI_32  -  event ID
 602   /// \~english @retval TRUE  reaction is available for this event
 603   /// \~english @retval FALSE reaction is not available for this event
 604   /// \~english @par Prerequisite
 605   ///       - Calls constructor to successfully create object.
 606   /// \~english @par Change of internal state
 607   ///        - None
 608   /// \~english @par Conditions of processing failure
 609   ///       - None
 610   /// \~english @par Detail
 611   ///       If the event specified by argument(f_uiEventId) is in event list,
 612   ///       the reaction is available for this event, return TRUE.
 613   ///       If the event specified by argument(f_uiEventId) is in deferred event list
 614   ///       but not in event list, the reaction is available for this event, return TRUE.
 615   ///       Otherwise, the event specified by argument(f_uiEventId) isn't available, return FALSE.
 616   /// \~english @par Classification
 617   ///        Public
 618   /// \~english @par Type
 619   ///        sync only
 620   /// \~english @see FrameworkunifiedPostEvent
 621   ///////////////////////////////////////////////////////////////////////////////////////////
 622   ///////////////////////////////////////////////////////////////////////////////////////////
 623   /// FrameworkunifiedIsReactionAvailable
 624   ///
 625   ///
 626   /// \param [in] f_uiEventId
 627   ///     UI_32 - Event identifier
 628   ///
 629   /// \return TRUE/FASLE
 630   ///     BOOL - returns TRUE if it reaction is available for this event
 631   virtual BOOL FrameworkunifiedIsReactionAvailable(UI_32 f_uiEventId);
 632
 633   /////////////////////////////////////////////////////////////////////////////////////
 634   /// \ingroup CFrameworkunifiedState
 635   /// \~english @par Summary
 636   ///       pure virtual fuction
 637   /// \~english @param None
 638   /// \~english @retval CFrameworkunifiedState* depend on implement class
 639   /// \~english @par Preconditions
 640   ///       - None.
 641   /// \~english @par Change of the internal state
 642   ///       - None
 643   /// \~english @par Causes of failures
 644   ///       None
 645   /// \~english @par Classification
 646   ///       Public
 647   /// \~english @par Type
 648   ///       sync only
 649   /// \~english @par Detail
 650   ///       pure virtual function , implement by child class
 651   /// \~english @see
 652   ////////////////////////////////////////////////////////////////////////////////////
 653   ///////////////////////////////////////////////////////////////////////////////////////////
 654   /// FrameworkunifiedGetActiveState
 655   /// This interface returns the Active state of the current composite state. In case of
 656   /// non-composite state current state is active state
 657   ///
 658   /// \return Active state
 659   ///     CFrameworkunifiedState* - Active state
 660   ///////////////////////////////////////////////////////////////////////////////////////////
 661   virtual CFrameworkunifiedState *FrameworkunifiedGetActiveState() = 0;
 662
 663   ///////////////////////////////////////////////////////////////////////////////////////////
 664   /// \ingroup CFrameworkunifiedState
 665   /// \~english @par Brief
 666   ///        This Interface associates the gives statemachine with the current state
 667   /// \~english @param [in] f_pStatemachine
 668   ///      CFrameworkunifiedHSM*  - Statemachine associated with the state.
 669   /// \~english @retval eFrameworkunifiedStatusOK  success
 670   /// \~english @retval eFrameworkunifiedStatusNullPointer  NULL pointer exception
 671   /// \~english @par Prerequisite
 672   ///       - Calls constructor to successfully create object.
 673   /// \~english @par Change of internal state
 674   ///        - None
 675   /// \~english @par Conditions of processing failure
 676   ///       - Pointer to state machine(CFrameworkunifiedHSM class) specified by argument(f_pStatemachine) is NULL.
 677   ///       [eFrameworkunifiedStatusNullPointer]
 678   /// \~english @par Detail
 679   ///       This Interface sets state machine of member variable to state machine specified by argument,
 680   ///       so it can associate the giving statemachine with current state.
 681   /// \~english @par Classification
 682   ///        Public
 683   /// \~english @par Type
 684   ///        sync only
 685   /// \~english @see CFrameworkunifiedHSM
 686   ///////////////////////////////////////////////////////////////////////////////////////////
 687   ///////////////////////////////////////////////////////////////////////////////////////////
 688   /// FrameworkunifiedSetHSM
 689   /// This Interface associates the gives statemachine with the current state
 690   ///
 691   /// \param [in] f_pStatemachine
 692   ///     CFrameworkunifiedHSM* - Statemachine associated with the state.
 693   ///
 694   /// \return EFrameworkunifiedStatus
 695   ///     EFrameworkunifiedStatus - Returns status of operation
 696   virtual EFrameworkunifiedStatus FrameworkunifiedSetHSM(CFrameworkunifiedHSM *f_pStatemachine);
 697
 698   ///////////////////////////////////////////////////////////////////////////////////////////
 699   /// \ingroup CFrameworkunifiedState
 700   /// \~english @par Brief
 701   ///        Get application handle.
 702   /// \~english @param None
 703   /// \~english @retval HANDLE  application handle
 704   /// \~english @par Prerequisite
 705   ///        - Calls constructor to successfully create object.
 706   ///        - State machine of current state in the applicaton is setted in FrameworkunifiedSetHSM.
 707   /// \~english @par Change of internal state
 708   ///        - None
 709   /// \~english @par Conditions of processing failure
 710   ///       - Failed to get application handle. [NULL]
 711   /// \~english @par Detail
 712   ///       This interface gets and returns the application handle with following steps:
 713   ///       - If member variable used for state machine of application is not setted, return NULL.
 714   ///       - Get application handle from state machine of application.
 715   /// \~english @par Classification
 716   ///        Public
 717   /// \~english @par Type
 718   ///        sync only
 719   /// \~english @see CFrameworkunifiedHSM::FrameworkunifiedGetAppHandle
 720   ///////////////////////////////////////////////////////////////////////////////////////////
 721   ///////////////////////////////////////////////////////////////////////////////////////////
 722   /// FrameworkunifiedGetAppHandle
 723   /// This interface returns the application handle
 724   ///
 725   /// \return HANDLE
 726   ///         HANDLE - Application Handle
 727   ///
 728   virtual HANDLE FrameworkunifiedGetAppHandle();
 729
 730   ///////////////////////////////////////////////////////////////////////////////////////////
 731   /// \ingroup CFrameworkunifiedState
 732   /// \~english @par Brief
 733   ///        Update the State information in the given stream in the form of XML tags
 734   /// \~english @param [out] f_strXMLString
 735   ///      std::ostringstream &  - reference to the XML stream
 736   /// \~english @retval eFrameworkunifiedStatusOK  success
 737   /// \~english @retval eFrameworkunifiedStatusNullPointer  NULL pointer exception
 738   /// \~english @par Prerequisite
 739   ///        - Calls constructor to successfully create object.
 740   ///        - State machine of current state in the applicaton is setted in FrameworkunifiedSetHSM.
 741   /// \~english @par Change of internal state
 742   ///        - None
 743   /// \~english @par Conditions of processing failure
 744   ///       - Failed to call constructor to create object. [eFrameworkunifiedStatusNullPointer]
 745   /// \~english @par Detail
 746   ///       Update the following State information in the given stream in the form of XML tags
 747   ///       - state name
 748   ///       - all event information in event list(eventID, event name)
 749   ///       - all event information in deferred event list(eventID, event name)
 750   /// \~english @par Classification
 751   ///        Public
 752   /// \~english @par Type
 753   ///        sync only
 754   /// \~english @see CEventData, FrameworkunifiedIsReactionAvailable, CFrameworkunifiedHSM::FrameworkunifiedQueueEvent, CFrameworkunifiedHSM::ProcessEvent
 755   ///////////////////////////////////////////////////////////////////////////////////////////
 756   ///////////////////////////////////////////////////////////////////////////////////////////
 757   /// FrameworkunifiedPrintXML
 758   /// Update the State information in the given stream in the form of XML tags
 759   ///
 760   /// \param [in] f_strXMLString
 761   ///     std::ostringstream & - reference to the XML stream
 762   ///
 763   /// \return EFrameworkunifiedStatus
 764   ///     EFrameworkunifiedStatus - Returns status of operation
 765   virtual EFrameworkunifiedStatus FrameworkunifiedPrintXML(std::ostringstream &f_strXMLString);
 766
 767   /////////////////////////////////////////////////////////////////////////////////////
 768   /// \ingroup CFrameworkunifiedState
 769   /// \~english @par Summary
 770   ///       pure virtual fuction
 771   /// \~english @param None
 772   /// \~english @retval None
 773   /// \~english @par Preconditions
 774   ///       - None.
 775   /// \~english @par Change of the internal state
 776   ///       - None
 777   /// \~english @par Causes of failures
 778   ///       None
 779   /// \~english @par Classification
 780   ///       Public
 781   /// \~english @par Type
 782   ///       sync only
 783   /// \~english @par Detail
 784   ///       pure virtual function , implement by child class
 785   /// \~english @see
 786   ////////////////////////////////////////////////////////////////////////////////////
 787   ///////////////////////////////////////////////////////////////////////////////////////////
 788   /// UpdateHistory
 789   /// This function stores the last active state
 790   ///
 791   /// \return EFrameworkunifiedStatus
 792   ///     EFrameworkunifiedStatus - Returns status of operation
 793   ///////////////////////////////////////////////////////////////////////////////////////////
 794   virtual EFrameworkunifiedStatus UpdateHistory() = 0;
 795
 796  protected :
 797   ///////////////////////////////////////////////////////////////////////////////////////////
 798   /// FrameworkunifiedOnEntry
 799   /// This is pure virtual function implemented by the derived classes of the application.
 800   /// state initialization can be performed in this function.
 801   ///
 802   /// \param [in] f_pEventData
 803   ///     CEventDataPtr - Event data
 804   ///
 805   /// \return EFrameworkunifiedStatus
 806   ///     EFrameworkunifiedStatus - Returns status of operation
 807   ///////////////////////////////////////////////////////////////////////////////////////////
 808   virtual EFrameworkunifiedStatus FrameworkunifiedOnEntry(CEventDataPtr f_pEventData) = 0;
 809
 810   ///////////////////////////////////////////////////////////////////////////////////////////
 811   /// FrameworkunifiedOnExit
 812   /// This is pure virtual function implemented by the derived classes of the application.
 813   /// state cleanup can be performed in this function.
 814   ///
 815   /// \param [in] f_pEventData
 816   ///     CEventDataPtr - Event data
 817   ///
 818   /// \return EFrameworkunifiedStatus
 819   ///     EFrameworkunifiedStatus - Returns status of operation
 820   ///////////////////////////////////////////////////////////////////////////////////////////
 821   virtual EFrameworkunifiedStatus FrameworkunifiedOnExit(CEventDataPtr f_pEventData) = 0;
 822
 823  private:
 824   ///////////////////////////////////////////////////////////////////////////////////////////
 825   /// IsEventDeferred
 826   /// This checks if the given event is marked as deferred in the state.
 827   ///
 828   /// \param [in] f_uiEventId
 829   ///     UI_32 - Event identifier
 830   ///
 831   /// \return BOOL
 832   ///     BOOL - event deferred or not
 833   ///////////////////////////////////////////////////////////////////////////////////////////
 834   BOOL IsEventDeferred(UI_32 f_uiEventId);
 835
 836  public:
 837   /// state name
 838   std::string m_strStateName;
 839
 840   /// Pointer to the parent state
 841   CFrameworkunifiedState *m_pParentState;
 842
 843   /// pointer to the default state
 844   CFrameworkunifiedState *m_pDefaultState;
 845
 846   /// pointer to the active state
 847   CFrameworkunifiedState *m_pActiveState;
 848
 849   /// pointer to the map that stores the event name against event id
 850   EventNameList *m_pEventName;
 851
 852  protected :
 853   /// pointer to the map that stores the reaction against event id
 854   EventReactionList *m_pEventList;
 855
 856   /// pointer to the map that stores deferred event ids
 857   DeferredEventList *m_pDeferredEventList;
 858
 859   /// pointer to the vector that stores the eventinfo of the posted deferred event
 860   EventInfoList *m_pDeferredPostEventList;
 861
 862   /// pointer to the application statemachine
 863   CFrameworkunifiedHSM *m_pStateMachine;
 864 };
 865
 866 #endif  // __FRAMEWORKUNIFIED_NATIVESERVICES_NATIVESERVICES_INC_FRAMEWORK_STATEMACHINE_FRAMEWORKUNIFIED_SM_STATE_H__  // NOLINT  (build/header_guard)
 867 /** @}*/
 868 /** @}*/
 869 /** @}*/
 870 /** @}*/
 871 /** @}*/
 872 //@}