video_in_hal/nsframework/framework_unified/client/include/native_service/frameworkunified_sm_compositestate.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 CFrameworkunifiedCompositeState class definitions. CFrameworkunifiedCompositeState is derived from C
  22 /// FrameworkunifiedState class.This class implements the additional functionality supported by HSM Composite
  23 /// state. It provides the standard interfaces for adding state.
  24 ///
  25 ///////////////////////////////////////////////////////////////////////////////
  26 //@{
  27 /**
  28  * @file frameworkunified_sm_compositestate.h
  29  * @brief \~english This file has the CFrameworkunifiedCompositeState class definitions. CFrameworkunifiedCompositeState is derived from C
  30  *        FrameworkunifiedState class.This class implements the additional functionality supported by HSM Composite
  31  *        state. It provides the standard interfaces for adding 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 _FRAMEWORKUNIFIEDCOMPOSITESTATE_H  // NOLINT  (build/header_guard)
  54 #define _FRAMEWORKUNIFIEDCOMPOSITESTATE_H
  55
  56 ///////////////////////////////////////////////////////////////////////////////////////////////////
  57 // Include Files
  58 ///////////////////////////////////////////////////////////////////////////////////////////////////
  59
  60 #include <native_service/frameworkunified_sm_state.h>
  61 #include <map>
  62 #include <string>
  63
  64 typedef std::map<std::string, CFrameworkunifiedState *> ChildStateList;
  65 typedef std::map<std::string, CFrameworkunifiedState *>::iterator StateIterator;
  66
  67 class CFrameworkunifiedHSM;
  68
  69 ///////////////////////////////////////////////////////////////////////////////////////////////////
  70 /// This class implements the additional functionality supported by HSM Composite
  71 /// state. It provides the standard interfaces for adding state.
  72 ///////////////////////////////////////////////////////////////////////////////////////////////////
  73 class CFrameworkunifiedCompositeState : public CFrameworkunifiedState {
  74  public :
  75
  76   typedef enum _FRAMEWORKUNIFIED_STATE_TYPE {
  77     eFrameworkunifiedState = 0,
  78     eFrameworkunifiedDefaultState
  79   } FRAMEWORKUNIFIED_STATE_TYPE;
  80
  81   ///////////////////////////////////////////////////////////////////////////////////////////
  82   /// \ingroup CFrameworkunifiedCompositeState
  83   /// \~english @par Brief
  84   ///          Constructor for class CFrameworkunifiedCompositeState.
  85   /// \~english @param [in] f_strName
  86   ///          std::string -Name of state
  87   /// \~english @retval
  88   /// \~english @par Prerequisite
  89   ///          none
  90   /// \~english @par Change of internal state
  91   ///          none
  92   /// \~english @par Conditions of processing failure
  93   ///          none
  94   /// \~english @par Detail
  95   ///          This class inherit from CFrameworkunifiedState(basic class of state machine), \n
  96   ///          and create object of CFrameworkunifiedCompositeState class. \n
  97   ///          Create and initialize child state, and set the pointor to member variable. \n
  98   ///          Initialize other member variables with NULL. \n
  99   ///          Output the process error logs.
 100   /// \~english @par Classification
 101   ///           public
 102   /// \~english @par Type
 103   ///           none
 104   /// \~english @see CFrameworkunifiedState, ~CFrameworkunifiedCompositeState
 105   ///////////////////////////////////////////////////////////////////////////////////////////
 106   CFrameworkunifiedCompositeState(std::string f_pName);  // NOLINT  (readability/nolint)
 107
 108   ///////////////////////////////////////////////////////////////////////////////////////////
 109   /// \ingroup CFrameworkunifiedCompositeState
 110   /// \~english @par Brief
 111   ///        Destructor for CFrameworkunifiedCompositeState
 112   /// \~english @retval none
 113   /// \~english @par Preconditons
 114   ///          - Self instance of CFrameworkunifiedCompositeState created.
 115   /// \~english @par Change of internal status
 116   ///                none
 117   /// \~english @par Conditions of processing failure
 118   ///                none
 119   /// \~english @par Detail
 120   ///           Release the objects of CFrameworkunifiedState class and CFrameworkunifiedCompositeState class. \n
 121   ///           Release all the child states registered in child states list of member variable. \n
 122   ///           Output error log if failed.
 123   /// \~english @par Classification
 124   ///           public
 125   /// \~english @par Type
 126   ///            none
 127   /// \~english @see CFrameworkunifiedState, CFrameworkunifiedCompositeState::CFrameworkunifiedCompositeState
 128   ///////////////////////////////////////////////////////////////////////////////////////////
 129   virtual ~CFrameworkunifiedCompositeState();
 130
 131   ////////////////////////////////////////////////////////////////////////////////////////////
 132   /// \ingroup CFrameworkunifiedCompositeState
 133   /// \~english @par Brief
 134   ///           sets the given state as a substate of the current state. If the f_eStateType is
 135   ///           eFrameworkunifiedDefaultState then substate is default state for current state.
 136   /// \~english @param [in] f_pState
 137   ///           CFrameworkunifiedState* - Pointer to the substate object to be added in the current state
 138   /// \~english @param [in] f_eStateType
 139   ///           FRAMEWORKUNIFIED_STATE_TYPE - state type indicating if it is default state
 140   /// \~english @retval EFrameworkunifiedStatus
 141   ///            success or fail
 142   /// \~english @par Preconditons
 143   ///        -  Self instance of CFrameworkunifiedCompositeState created.
 144   /// \~english @par Change of internal status
 145   ///        -  none
 146   /// \~english @par Conditions of processing failure
 147   ///           - If parameter f_pState is NULL. [eFrameworkunifiedStatusNullPointer]
 148   ///            - If m_pChildStates is NULL. [eFrameworkunifiedStatusNullPointer]
 149   /// \~english @par Detail
 150   ///           sets the given state as a substate of the current state. If the f_eStateType is
 151   ///              eFrameworkunifiedDefaultState then substate is default state for current state.
 152   /// \~english @par Classification
 153   ///          public
 154   /// \~english @par Type
 155   ///          none
 156   /// \~english @see none
 157   ////////////////////////////////////////////////////////////////////////////////////////////
 158   EFrameworkunifiedStatus FrameworkunifiedAddState(CFrameworkunifiedState *f_pState,
 159                          FRAMEWORKUNIFIED_STATE_TYPE f_eStateType = eFrameworkunifiedState);
 160
 161   ////////////////////////////////////////////////////////////////////////////////////////////
 162   /// \ingroup CFrameworkunifiedCompositeState
 163   /// \~english @par Brief
 164   ///           Returns the default state of the current composite state.
 165   /// \~english @param none
 166   /// \~english @retval CFrameworkunifiedState*  - pointer default state
 167   /// \~english @par Preconditons
 168   ///        -  Self instance of CFrameworkunifiedCompositeState created.
 169   /// \~english @par Change of internal status
 170   ///        -  none
 171   /// \~english @par Conditions of processing failure
 172   ///           none
 173   /// \~english @par Detail
 174   ///           Returns the default state of the current composite state.
 175   /// \~english @par Classification
 176   ///          public
 177   /// \~english @par Type
 178   ///          none
 179   /// \~english @see none
 180   ////////////////////////////////////////////////////////////////////////////////////////////
 181   CFrameworkunifiedState *FrameworkunifiedGetDefaultState();
 182
 183   ///////////////////////////////////////////////////////////////////////////////////////////
 184   /// \ingroup CFrameworkunifiedCompositeState
 185   /// \~english @par Brief
 186   ///           Logs the state name and events associated with the state.
 187   /// \~english @param none
 188   /// \~english @retval eFrameworkunifiedStatusOK succ
 189   /// \~english @retval eFrameworkunifiedStatusNullPointer failed
 190   /// \~english @par Preconditons
 191   ///        -  Self instance of CFrameworkunifiedCompositeState created.
 192   /// \~english @par Change of internal status
 193   ///        -  none
 194   /// \~english @par Conditions of processing failure
 195   ///        -  Don't create instance of CFrameworkunifiedCompositeState [eFrameworkunifiedStatusNullPointer]
 196   /// \~english @par Detail
 197   ///           This function overrides the fuction of CFrameworkunifiedState::FrameworkunifiedPrintStates.
 198   ///           This function outputs log of state name and events associated with the state as follows:
 199   ///           - state name of parent state machine and self state machine
 200   ///           - all the event names in event list
 201   ///           - all the event names in delay event list
 202   /// \~english @par Classification
 203   ///          public
 204   /// \~english @par Type
 205   ///          none
 206   /// \~english @see none
 207   ///////////////////////////////////////////////////////////////////////////////////////////
 208   virtual  EFrameworkunifiedStatus FrameworkunifiedPrintStates();
 209
 210   ///////////////////////////////////////////////////////////////////////////////////////////
 211   /// \ingroup CFrameworkunifiedCompositeState
 212   /// \~english @par Brief
 213   ///    This indicates if the state has sub states. It returns TRUE only in the CompositeState
 214   ///          where this function is overridden
 215   /// \~english @param none
 216   /// \~english @retval BOOL   TRUE - has substate FALSE - has not substatue
 217   /// \~english @par Preconditons
 218   ///        -  Self instance of CFrameworkunifiedCompositeState created.
 219   /// \~english @par Change of internal status
 220   ///        -  none
 221   /// \~english @par Conditions of processing failure
 222   ///        -  none
 223   /// \~english @par Detail
 224   ///           This function overrides the fuction of CFrameworkunifiedState::FrameworkunifiedHasSubStates.
 225   ///           Return true only in CFrameworkunifiedCompositeState class.
 226   /// \~english @par Classification
 227   ///          public
 228   /// \~english @par Type
 229   ///          none
 230   /// \~english @see CFrameworkunifiedState::FrameworkunifiedHasSubStates
 231   virtual BOOL FrameworkunifiedHasSubStates();
 232
 233   ///////////////////////////////////////////////////////////////////////////////////////////
 234   /// \ingroup CFrameworkunifiedCompositeState
 235   /// \~english @par Brief
 236   ///       This interface returns the Active state of the current composite state. In case of
 237   ///          non-composite state current state is active state
 238   /// \~english @param none
 239   /// \~english @retval CFrameworkunifiedState*  pointer of active state
 240   /// \~english @par Preconditons
 241   ///        -  Self instance of CFrameworkunifiedCompositeState created.
 242   /// \~english @par Change of internal status
 243   ///        -  none
 244   /// \~english @par Conditions of processing failure
 245   ///        -  none
 246   /// \~english @par Detail
 247   ///           This function overrides the pure virtual fuction of CFrameworkunifiedState::FrameworkunifiedGetActiveState.
 248   ///           Reture active state of current composite state. If it isn't a composite state,
 249   ///           return current state as an active state.
 250   /// \~english @par Classification
 251   ///          public
 252   /// \~english @par Type
 253   ///          none
 254   /// \~english @see CFrameworkunifiedState::FrameworkunifiedGetActiveState
 255   ///////////////////////////////////////////////////////////////////////////////////////////
 256   virtual CFrameworkunifiedState *FrameworkunifiedGetActiveState();
 257
 258   ///////////////////////////////////////////////////////////////////////////////////////////
 259   /// \ingroup CFrameworkunifiedCompositeState
 260   /// \~english @par Brief
 261   ///       This function stores the last active state
 262   /// \~english @param none
 263   /// \~english @retval EFrameworkunifiedStatus  eFrameworkunifiedStatusOK
 264   /// \~english @par Preconditons
 265   ///        -  Self instance of CFrameworkunifiedCompositeState created.
 266   /// \~english @par Change of internal status
 267   ///        -  none
 268   /// \~english @par Conditions of processing failure
 269   ///        -  none
 270   /// \~english @par Detail
 271   ///           This function overrides the pure virtual fuction of CFrameworkunifiedState::UpdateHistory.
 272   ///           Store the last active state.
 273   /// \~english @par Classification
 274   ///          public
 275   /// \~english @par Type
 276   ///          none
 277   /// \~english @see CFrameworkunifiedState::UpdateHistory
 278   ///////////////////////////////////////////////////////////////////////////////////////////
 279   EFrameworkunifiedStatus UpdateHistory();
 280
 281   ///////////////////////////////////////////////////////////////////////////////////////////
 282   /// \ingroup CFrameworkunifiedCompositeState
 283   /// \~english @par Brief
 284   ///       Update the State information in the given stream in the form of XML tags
 285   ///
 286   /// \~english @param f_strXMLString
 287   ///         std::ostringstream & - reference to the XML stream
 288   /// \~english @retval EFrameworkunifiedStatus  eFrameworkunifiedStatusOK
 289   ///                               eFrameworkunifiedStatusNullPointer
 290   /// \~english @par Preconditons
 291   ///        -  Self instance of CFrameworkunifiedCompositeState created.
 292   ///        -  State machine of current state in the applicaton is setted in FrameworkunifiedSetHSM.
 293   /// \~english @par Change of internal status
 294   ///        -  Self instance of CFrameworkunifiedCompositeState created failed. [eFrameworkunifiedStatusNullPointer].
 295   /// \~english @par Conditions of processing failure
 296   ///        -  none
 297   /// \~english @par Detail
 298   ///           This function overrides the fuction of CFrameworkunifiedState::FrameworkunifiedPrintXML.
 299   ///           Set parameter f_strXMLString with the following state information by XML type.
 300   ///           - state name
 301   ///           - all the event information in event list(event ID, event name)
 302   ///           - all the event information in delay event list(event ID, event name)
 303   /// \~english @par Classification
 304   ///          public
 305   /// \~english @par Type
 306   ///          none
 307   /// \~english @see CFrameworkunifiedState::FrameworkunifiedPrintXML
 308   ///////////////////////////////////////////////////////////////////////////////////////////
 309   virtual EFrameworkunifiedStatus FrameworkunifiedPrintXML(std::ostringstream &f_strXMLString);
 310
 311
 312  protected :
 313
 314   ///////////////////////////////////////////////////////////////////////////////////////////
 315   /// \ingroup CFrameworkunifiedCompositeState
 316   /// \~english @par Brief
 317   ///        Initialize state
 318   /// \~english @param f_pEventData
 319   ///       CEventDataPtr - Pointer to the event data class
 320   /// \~english @retval eFrameworkunifiedStatusOK
 321   /// \~english @par Preconditions
 322   ///       - Its own instance (CFrameworkunifiedCompositeState) has been created.
 323   /// \~english @par Change of internal status
 324   ///       - The internal state is not changed.
 325   /// \~english @par Conditions of processing failure
 326   ///       - None
 327   /// \~english @par Detail
 328   ///       This method overrides and uses CFrameworkunifiedState::FrameworkunifiedOnEntry, which is pure virtual functions, to initialize state.
 329   /// \~english @par Classification
 330   ///       Public
 331   /// \~english @par Type
 332   ///       Not applicable
 333   /// \~english @see CFrameworkunifiedState::FrameworkunifiedOnEntry, FrameworkunifiedOnExit
 334   ///
 335   /// state initialization can be performed in this function.
 336   ///
 337   /// \param [in] f_pEventData
 338   ///     CEventDataPtr - Event data
 339   ///
 340   /// \return EFrameworkunifiedStatus
 341   ///     EFrameworkunifiedStatus - Returns status of operation
 342   ///////////////////////////////////////////////////////////////////////////////////////////
 343   virtual EFrameworkunifiedStatus FrameworkunifiedOnEntry(CEventDataPtr f_pEventData);
 344
 345   ///////////////////////////////////////////////////////////////////////////////////////////
 346   /// \ingroup CFrameworkunifiedCompositeState
 347   /// \~english @par Brief
 348   ///        Clean up state.
 349   /// \~english @param f_pEventData
 350   ///       CEventDataPtr - Pointer to the event data class
 351   /// \~english @retval eFrameworkunifiedStatusOK
 352   /// \~english @par Preconditions
 353   ///       - Its own instance (CFrameworkunifiedCompositeState) has been created.
 354   /// \~english @par Change of internal status
 355   ///       - The internal state is not changed.
 356   /// \~english @par Conditions of processing failure
 357   ///       - None
 358   /// \~english @par Detail
 359   ///       This method overrides and uses CFrameworkunifiedState::FrameworkunifiedOnExit, which is pure virtual functions, to clean up state.
 360   /// \~english @par Classification
 361   ///       Public
 362   /// \~english @par Type
 363   ///       Not applicable
 364   /// \~english @see CFrameworkunifiedState::FrameworkunifiedOnExit, FrameworkunifiedOnEntry
 365   ///
 366   /// state cleanup can be performed in this function.
 367   ///
 368   /// \param [in] f_pEventData
 369   ///     CEventDataPtr - Event data
 370   ///
 371   /// \return EFrameworkunifiedStatus
 372   ///     EFrameworkunifiedStatus - Returns status of operation
 373   ///////////////////////////////////////////////////////////////////////////////////////////
 374   virtual EFrameworkunifiedStatus FrameworkunifiedOnExit(CEventDataPtr f_pEventData);
 375
 376   /// stores the pointers to sub state, key is state name
 377   ChildStateList *m_pChildStates;
 378
 379   ///////////////////////////////////////////////////////////////////////////////////////////
 380   /// \ingroup CFrameworkunifiedCompositeState
 381   /// \~english @par Brief
 382   ///        Associate the state machine with the current state.
 383   /// \~english @param [in] f_pStatemachine
 384   ///      CFrameworkunifiedHSM*  - Pointers to state machines (CFrameworkunifiedHSM classes)
 385   /// \~english @retval eFrameworkunifiedStatusOK
 386   /// \~english @retval eFrameworkunifiedStatusNullPointer  Specifying NULL pointers
 387   /// \~english @par Preconditions
 388   ///       - Its own instance (CFrameworkunifiedCompositeState) has been created.
 389   /// \~english @par Change of internal status
 390   ///       - The internal state is not changed.
 391   /// \~english @par Conditions of processing failure
 392   ///       - When the pointers to the state machines (CFrameworkunifiedHSM classes) specified in the arguments (f_pStatemachine) are NULL [eFrameworkunifiedStatusNullPointer]
 393   /// \~english @par Detail
 394   ///       This method is used by overriding CFrameworkunifiedState::FrameworkunifiedSetHSM.\n
 395   ///       Associates a state machine with the current state by setting a pointer (f_pStatemachine)
 396   ///       to the state machine (CFrameworkunifiedHSM) specified by the argument to the pointer to the state machine of the member variable. \n
 397   ///       Calling FrameworkunifiedSetHSM() for child states also associates the state machine of the child states with the state of the current state.
 398   /// \~english @par Classification
 399   ///       Public
 400   /// \~english @par Type
 401   ///       Not applicable
 402   /// \~english @see CFrameworkunifiedHSM, CFrameworkunifiedState::FrameworkunifiedSetHSM
 403   ///
 404   /// Sets the statemachine in the status
 405   ///
 406   /// \param [in] f_pStatemachine
 407   ///     CFrameworkunifiedHSM* - Statemachine pointer
 408   ///
 409   /// \return EFrameworkunifiedStatus
 410   ///     EFrameworkunifiedStatus - Returns status of operation
 411   ///////////////////////////////////////////////////////////////////////////////////////////
 412   virtual EFrameworkunifiedStatus FrameworkunifiedSetHSM(CFrameworkunifiedHSM *f_pStatemachine);
 413
 414  private:
 415   ////////////////////////////////////////////////////////////////////////////////////////////////
 416   /// CheckHistory
 417   /// This function searches for history state in this composite state and updates it.
 418   ///
 419   /// \param [in] l_cHistoryType
 420   ///     string - Type of history state (shallow or deep)
 421   ///
 422   /// \return EFrameworkunifiedStatus
 423   ///     EFrameworkunifiedStatus - Returns status of operation
 424   ///////////////////////////////////////////////////////////////////////////////////////////
 425   EFrameworkunifiedStatus CheckHistory(std::string l_cHistoryType);
 426 };
 427
 428 #endif // _FRAMEWORKUNIFIEDCOMPOSITESTATE_H  // NOLINT  (build/header_guard)
 429 /** @}*/
 430 /** @}*/
 431 /** @}*/
 432 /** @}*/
 433 /** @}*/
 434 //@}