path: root/nsframework/framework_unified/client/include/native_service/frameworkunified_sm_orthogonalstate.h

/*
 * @copyright Copyright (c) 2016-2020 TOYOTA MOTOR CORPORATION.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

///////////////////////////////////////////////////////////////////////////////
/// \ingroup  tag_StateMachine
/// \brief
///
/// This file has the CFrameworkunifiedOrthogonalState class definitions. CFrameworkunifiedOrthogonalState is derived from
/// CFrameworkunifiedCompositeState class.This class implements the additional functionality supported by HSM
/// Orthogonal state. It provides the standard interfaces for adding orthogonal state machines.
///
///////////////////////////////////////////////////////////////////////////////
//@{
/**
 * @file frameworkunified_sm_orthogonalstate.h
 * @brief \~english This file has the CFrameworkunifiedOrthogonalState class definitions. CFrameworkunifiedOrthogonalState is derived from
 *        CFrameworkunifiedCompositeState class.This class implements the additional functionality supported by HSM
 *        Orthogonal state. It provides the standard interfaces for adding orthogonal state machines.
 */
/** @addtogroup BaseSystem
 *  @{
 */
/** @addtogroup native_service
 *  @ingroup BaseSystem
 *  @{
 */
/** @addtogroup framework_unified
 *  @ingroup native_service
 *  @{
 */
/** @addtogroup framework
 *  @ingroup framework_unified
 *  @{
 */
/** @addtogroup statemachine
 *  @ingroup framework
 *  @{
 */
#ifndef _FRAMEWORKUNIFIEDORTHOGONALSTATE_H  // NOLINT  (build/header_guard)
#define _FRAMEWORKUNIFIEDORTHOGONALSTATE_H

///////////////////////////////////////////////////////////////////////////////////////////////////
// Include Files
///////////////////////////////////////////////////////////////////////////////////////////////////

#include <native_service/frameworkunified_sm_state.h>
#include <vector>

typedef std::vector<CFrameworkunifiedState *> OrthogonalRegionList;

class CFrameworkunifiedCompositeState;

class CFrameworkunifiedHSM;
///////////////////////////////////////////////////////////////////////////////////////////////////
/// This class implements the additional functionality supported by HSM
/// Orthogonal state. It provides the standard interfaces for adding orthogonal state machines.
///////////////////////////////////////////////////////////////////////////////////////////////////
class CFrameworkunifiedOrthogonalState : public CFrameworkunifiedState {
 public :
  ///////////////////////////////////////////////////////////////////////////////////////////
  /// \ingroup tag_CFrameworkunifiedOrthogonalState
  /// \~english @par Brief
  ///        Constructors for CFrameworkunifiedOrthogonalState classes
  /// \~english @param [in] f_pName
  ///        std::string   - state name
  /// \~english @retval None
  /// \~english @par Prerequisite
  ///       - None
  /// \~english @par Change of internal state
  ///       - The internal state is not changed.
  /// \~english @par Conditions of processing failure
  ///       - When the quadrature region list cannot be created due to insufficient memory
  /// \~english @par Detail
  ///       Generates an orthographic region list.\n
  ///       CFrameworkunifiedOrthogonalState classes are used to manage the status of independent features individually.\n
  ///       For example, when the function of the clock is set to the following two, the management of the internal state is performed according to the function.\n
  ///       - Clock function (Clock display by 12h/24h)\n
  ///       - Alarm function (on/off setting)
  /// \~english @par Classification
  ///       Public
  /// \~english @par Type
  ///       Not applicable
  /// \~english @see ~CFrameworkunifiedOrthogonalState
  ///////////////////////////////////////////////////////////////////////////////////////////
  /// CFrameworkunifiedCompositeState
  /// Parameterized constructor
  /// \param [in] f_pName
  ///     string - Name of the state
  ///
  /// \return none
  CFrameworkunifiedOrthogonalState(std::string f_pName);  // NOLINT  (readability/nolint)

  ///////////////////////////////////////////////////////////////////////////////////////////
  /// \ingroup tag_CFrameworkunifiedOrthogonalState
  /// \~english @par Brief
  ///        Destructors of CFrameworkunifiedOrthogonalState classes
  /// \~english @retval None
  /// \~english @par Prerequisite
  ///       - Its own instance (CFrameworkunifiedOrthogonalState) has been created.
  /// \~english @par Change of internal state
  ///       - The internal state is not changed.
  /// \~english @par Conditions of processing failure
  ///       - None
  /// \~english @par Detail
  ///       Frees the memory in the orthographic area list and clears the memory contents.
  /// \~english @par Classification
  ///       Public
  /// \~english @par Type
  ///       Not applicable
  /// \~english @see CFrameworkunifiedOrthogonalState
  ///////////////////////////////////////////////////////////////////////////////////////////
  /// ~CFrameworkunifiedOrthogonalState
  /// Class destructor
  ///
  /// \return none
  virtual ~CFrameworkunifiedOrthogonalState();



  ///////////////////////////////////////////////////////////////////////////////////////////
  /// \ingroup tag_CFrameworkunifiedOrthogonalState
  /// \~english @par Brief
  ///        Initialize state
  /// \~english @param [in] f_pEventData
  ///        CEventDataPtr   - Pointer to the event data class
  /// \~english @retval Successful pointer to the current state after processing
  /// \~english @retval NULL       Exception supine in internal processing
  /// \~english @par Prerequisite
  ///       - Its own instance (CFrameworkunifiedOrthogonalState) has been created.
  ///       - The State Machine for the current state of the application is set in the FrameworkunifiedSetHSM.
  /// \~english @par Change of internal state
  ///       - The internal state is not changed.
  /// \~english @par Conditions of processing failure
  ///       - Failed recursive function call (FrameworkunifiedOnEntry call)[NULL]
  ///       - If the pointers to the orthographic regions are NULL [NULL]
  /// \~english @par Detail
  ///       Loops as many times as the number of elements in the quadrature area list, and initializes the active state (calls FrameworkunifiedOnEntry).\n
  ///       If the current state is Leaf State, it does not initialize because it does not have any active state.\n
  ///       If, after initialization, the current state is a child state of Orthogonal State, sets itself (the this pointer) to the current state.\n
  ///       Breaks looping if the current state is not a child state of Orthogonal State.\n
  ///       To maintain the hierarchy, the active state of the parent state is set to the current state.
  /// \~english @par Classification
  ///       Public
  /// \~english @par Type
  ///       Not applicable
  /// \~english @see FrameworkunifiedOnHSMStop, FrameworkunifiedOnEntry, CFrameworkunifiedState::FrameworkunifiedOnHSMStart, IsOrthogonalChildState
  ///////////////////////////////////////////////////////////////////////////////////////////
  /// FrameworkunifiedOnHSMStart
  /// This function is called recursively till the leaf state is reached. This internally
  /// calls the Entry function of the current state.
  ///
  /// \param [in] f_pEventData
  ///     CEventDataPtr - Event data
  ///
  /// \return CurrentState
  ///     CFrameworkunifiedState* - Returns current state after operation
  CFrameworkunifiedState *FrameworkunifiedOnHSMStart(CEventDataPtr f_pEventData);

  ///////////////////////////////////////////////////////////////////////////////////////////
  /// \ingroup tag_CFrameworkunifiedOrthogonalState
  /// \~english @par Brief
  ///        Clean up state.
  /// \~english @param [in] f_pEventData
  ///        CEventDataPtr   - Pointer to the event data class
  /// \~english @retval Successful pointer to the current state after processing
  /// \~english @retval NULL                                 Exception supine in internal processing
  /// \~english @par Prerequisite
  ///       - Its own instance (CFrameworkunifiedOrthogonalState) has been created.
  ///       - The State Machine for the current state of the application is set in the FrameworkunifiedSetHSM.
  /// \~english @par Change of internal state
  ///       - The internal state is not changed.
  /// \~english @par Conditions of processing failure
  ///       - If the pointers to the orthographic regions are NULL [NULL]
  ///       - If the pointers to the orthographic area lists of the member variables are NULL [NULL]
  ///       - Active state pointers from orthographic area lists of member variables are NULL [NULL]
  ///       - If the current state of the state being cleaned up is NULL [NULL]
  /// \~english @par Detail
  ///       Loops as many times as the number of elements in the quadrature area list, and performs cleanup of the active state (calls FrameworkunifiedOnExit).\n
  ///       If the current state is Leaf State,Do not clean up because it does not have any active state.\n
  ///       If the current state is a child state of Orthogonal State (orthographic state) after the cleanup process finishes,Sets itself (the this pointer) to the current state.\n
  ///       Breaks looping if the current state is not a child state of Orthogonal State.
  /// \~english @par Classification
  ///       Public
  /// \~english @par Type
  ///       Not applicable
  /// \~english @see FrameworkunifiedOnHSMStart, CFrameworkunifiedState::FrameworkunifiedOnHSMStop, CFrameworkunifiedState::FrameworkunifiedPostEvent, FrameworkunifiedOnExit,
  ///   IsOrthogonalChildState
  ///////////////////////////////////////////////////////////////////////////////////////////
  /// FrameworkunifiedOnHSMStop
  /// This function is called recursively till the required parent state is reached. This
  /// internally calls the Exit function of the current state.
  ///
  /// \param [in] f_pEventData
  ///     CEventDataPtr - Event data
  ///
  /// \return CurrentState
  ///     CFrameworkunifiedState* - Returns current state after operation
  CFrameworkunifiedState *FrameworkunifiedOnHSMStop(CEventDataPtr f_pEventData);

  ///////////////////////////////////////////////////////////////////////////////////////////
  /// FrameworkunifiedAddOrthogonalRegion
  /// This Interface adds orthogonal region in the orthogonal state.
  ///
  /// \param [in] f_pOrthogonalRegion
  ///     CFrameworkunifiedCompositeState - Orthogonal region object to be associated with state.
  ///
  /// \return CurrentState
  ///     CFrameworkunifiedState* - Returns current state after operation
  ///////////////////////////////////////////////////////////////////////////////////////////
  EFrameworkunifiedStatus FrameworkunifiedAddOrthogonalRegion(CFrameworkunifiedCompositeState *f_pOrthogonalRegion);

  ///////////////////////////////////////////////////////////////////////////////////////////
  /// \ingroup tag_CFrameworkunifiedOrthogonalState
  /// \~english @par Brief
  ///        Checks whether OrthogonalRegion (orthographic area) is registered or not.
  /// \~english @retval TRUE  OrthogonalRegion (orthographic area) is registered
  /// \~english @retval FALSE OrthogonalRegion (orthographic area) is not registered
  /// \~english @par Prerequisite
  ///       - Its own instance (CFrameworkunifiedOrthogonalState) has been created.
  ///       - OrthogonalRegion (orthographic area) is registered in FrameworkunifiedAddOrthogonalRegion.
  /// \~english @par Change of internal state
  ///       - The internal state is not changed.
  /// \~english @par Conditions of processing failure
  ///       - If the pointers to the orthographic regions are NULL [FALSE]
  ///       - When the OrthogonalRegion (orthographic area) is not registered and the number of elements (size) of the orthographic area is 0, [FALSE]
  /// \~english @par Detail
  ///       Checks whether OrthogonalRegion (orthographic area) is registered by referring to the number of elements (size) of the orthographic area list.
  /// \~english @par Classification
  ///       Public
  /// \~english @par Type
  ///       Not applicable
  /// \~english @see 
  ///////////////////////////////////////////////////////////////////////////////////////////
  /// FrameworkunifiedHasOrthogoanlRegions
  /// This checks if the current state has Orthogonal regions
  ///
  ///
  /// \return TRUE/FASLE
  ///     BOOL - returns TRUE if orthogonal regions are available in the state
  virtual BOOL FrameworkunifiedHasOrthogoanlRegions();

  ///////////////////////////////////////////////////////////////////////////////////////////
  /// \ingroup tag_CFrameworkunifiedOrthogonalState
  /// \~english @par Brief
  ///        Event handling
  /// \~english @param [in] f_pEventData
  ///        CEventDataPtr   - Pointer to the event data class
  /// \~english @retval Successful pointer to the current state after processing
  /// \~english @retval NULL       Operation cannot be guaranteed.
  /// \~english @par Prerequisite
  ///       - Its own instance (CFrameworkunifiedOrthogonalState) has been created.
  ///       - The State Machine for the current state of the application is set in the FrameworkunifiedSetHSM.
  ///       - OrthogonalRegion (orthographic area) is registered in FrameworkunifiedAddOrthogonalRegion.
  /// \~english @par Change of internal state
  ///       - The internal state is not changed.
  /// \~english @par Conditions of processing failure
  ///       - If the pointers to the orthographic regions are NULL [NULL]
  ///       - If the event data class is pointed to by NULL [NULL]
  /// \~english @par Detail
  ///       If the event specified in the argument (f_pEventData) is available in the current state,Set itself (this) to current state and return it.\n
  ///       Invokes the parent-state FrameworkunifiedOnEvent if not available in the current state
  ///       (Repeated until the root state is reached.)\n
  ///       However, since the FrameworkunifiedState that is the parent state of the Orthogonal State (orthographic state) is the root state,You call the FrameworkunifiedOnEvent of FrameworkunifiedState.\n
  ///       If the current state is a child state of the Orthogonal State (quadrature state) after the above process, sets itself (the this pointer) to the current state.
  /// \~english @par Classification
  ///       Public
  /// \~english @par Type
  ///       Not applicable
  /// \~english @see CFrameworkunifiedCompositeState::FrameworkunifiedGetActiveState, CFrameworkunifiedState::FrameworkunifiedIsReactionAvailable, CFrameworkunifiedState::FrameworkunifiedOnEvent,
  /// IsOrthogonalChildState
  ///////////////////////////////////////////////////////////////////////////////////////////
  ///////////////////////////////////////////////////////////////////////////////////////////
  /// FrameworkunifiedOnEvent
  /// This function processes the event. If the reaction for event is available in the current
  /// state within eventlist and deferred eventlist then it is consumed in the current state
  /// otherwise forwarded to the parent state. Event forwarding is done recursively till either
  /// event is consumed or the root state has encountered. This also process the events posted
  /// in the reactions recursively till all posted events are cleared.
  ///
  /// \param [in] f_pEventData
  ///     CEventDataPtr - Event data
  ///
  ///
  /// \return state
  ///         CFrameworkunifiedState* - Returns current state after the event is processed
  ///
  virtual CFrameworkunifiedState *FrameworkunifiedOnEvent(CEventDataPtr f_pEventData);

  ///////////////////////////////////////////////////////////////////////////////////////////
  /// \ingroup tag_CFrameworkunifiedOrthogonalState
  /// \~english @par Brief
  ///        Logs the state name and event name.
  /// \~english @retval eFrameworkunifiedStatusOK success
  /// \~english @retval eFrameworkunifiedStatusNullPointer Specifying NULL pointers
  /// \~english @par Prerequisite
  ///       - Its own instance (CFrameworkunifiedOrthogonalState) has been created.
  ///       - OrthogonalRegion (orthographic area) is registered in FrameworkunifiedAddOrthogonalRegion.
  /// \~english @par Change of internal state
  ///       - The internal state is not changed.
  /// \~english @par Conditions of processing failure
  ///       - If the pointers to the orthographic regions are NULL [eFrameworkunifiedStatusNullPointer]
  /// \~english @par Detail
  ///       Size of the log output data
  ///       - State name of the parent state machine and the state name of the self-state machine
  ///       - All event names on the event list
  ///       - All event names on the deferred event list
  /// \~english @par Classification
  ///       Public
  /// \~english @par Type
  ///       Not applicable
  /// \~english @see CFrameworkunifiedCompositeState::FrameworkunifiedPrintStates
  ///////////////////////////////////////////////////////////////////////////////////////////
  ///////////////////////////////////////////////////////////////////////////////////////////
  /// FrameworkunifiedPrintStates
  /// This logs the state name and events associated with the state
  ///
  /// \return EFrameworkunifiedStatus
  ///     EFrameworkunifiedStatus - Returns status of operation
  ///////////////////////////////////////////////////////////////////////////////////////////
  virtual  EFrameworkunifiedStatus FrameworkunifiedPrintStates();

  ///////////////////////////////////////////////////////////////////////////////////////////
  /// \ingroup tag_CFrameworkunifiedOrthogonalState
  /// \~english @par Brief
  ///        Get the active state.
  /// \~english @retval Successful pointer to the active state
  /// \~english @par Prerequisite
  ///       - Its own instance (CFrameworkunifiedOrthogonalState) has been created.
  /// \~english @par Change of internal state
  ///       - The internal state is not changed.
  /// \~english @par Conditions of processing failure
  ///       - None
  /// \~english @par Detail
  ///       In this class, the current state (this state) is always returned as the active state.
  /// \~english @par Classification
  ///       Public
  /// \~english @par Type
  ///       Not applicable
  /// \~english @see None
  ///////////////////////////////////////////////////////////////////////////////////////////
  ///////////////////////////////////////////////////////////////////////////////////////////
  /// FrameworkunifiedGetActiveState
  /// This interface returns the Active state of the current composite state. In case of
  /// non-composite state current state is active state
  ///
  /// \return Active state
  ///     CFrameworkunifiedState* - Active state
  virtual CFrameworkunifiedState *FrameworkunifiedGetActiveState();

  ///////////////////////////////////////////////////////////////////////////////////////////
  /// \ingroup tag_CFrameworkunifiedOrthogonalState
  /// \~english @par Brief
  ///        Associate the state machine with the current state.
  /// \~english @param [in] f_pStatemachine
  ///        CFrameworkunifiedHSM* - Pointers to state machines (CFrameworkunifiedHSM classes)
  /// \~english @retval eFrameworkunifiedStatusOK success
  /// \~english @retval eFrameworkunifiedStatusNullPointer Specifiying NULL pointers
  /// \~english @par Prerequisite
  ///       - Its own instance (CFrameworkunifiedOrthogonalState) has been created.
  /// \~english @par Change of internal state
  ///       - The internal state is not changed.
  /// \~english @par Conditions of processing failure
  ///       - When the pointers to the state machines (CFrameworkunifiedHSM classes) specified in the arguments (f_pStatemachine) are NULL
  ///       [eFrameworkunifiedStatusNullPointer]
  /// \~english @par Detail
  ///       Associates a state machine with the current state by setting a pointer (f_pStatemachine) to the state machine (CFrameworkunifiedHSM) specified by the argument to the pointer to the state machine of the member variables.
  /// \~english @par Classification
  ///       Public
  /// \~english @par Type
  ///       Not applicable
  /// \~english @see CFrameworkunifiedCompositeState::FrameworkunifiedSetHSM
  ///////////////////////////////////////////////////////////////////////////////////////////
  ///////////////////////////////////////////////////////////////////////////////////////////
  /// FrameworkunifiedSetHSM
  /// This Interface associates the gives statemachine with the current state
  ///
  /// \param [in] f_pStatemachine
  ///     CFrameworkunifiedHSM* - Statemachine associated with the state.
  ///
  /// \return EFrameworkunifiedStatus
  ///     EFrameworkunifiedStatus - Returns status of operation
  ///////////////////////////////////////////////////////////////////////////////////////////
  virtual EFrameworkunifiedStatus FrameworkunifiedSetHSM(CFrameworkunifiedHSM *f_pStatemachine);

  ///////////////////////////////////////////////////////////////////////////////////////////
  /// \ingroup tag_CFrameworkunifiedOrthogonalState
  /// \~english @par Brief
  ///        Outputs state information in the form of XML tags.
  /// \~english @param [out] f_strXMLString
  ///        std::ostringstream& - Only kept in NPS
  /// \~english @retval eFrameworkunifiedStatusOK success
  /// \~english @retval eFrameworkunifiedStatusNullPointer Specifiying NULL pointers
  /// \~english @par Prerequisite
  ///       - Its own instance (CFrameworkunifiedOrthogonalState) has been created.
  ///       - The State Machine for the current state of the application is set in the FrameworkunifiedSetHSM.
  /// \~english @par Change of internal state
  ///       - The internal state is not changed.
  /// \~english @par Conditions of processing failure
  ///       - If generating of own instance (CFrameworkunifiedOrthogonalState) failed, [eFrameworkunifiedStatusNullPointer]
  /// \~english @par Detail
  ///       Outputs the following state information in XML tag format to the XML stream specified by the argument.
  ///       - Sate name
  ///       - All event information (event ID and event name) in the event list
  ///       - All event information (event ID and event name) in the deferred event list
  /// \~english @par Classification
  ///       Public
  /// \~english @par Type
  ///       Not applicable
  /// \~english @see CFrameworkunifiedCompositeState::FrameworkunifiedPrintXML
  ///////////////////////////////////////////////////////////////////////////////////////////
  ///////////////////////////////////////////////////////////////////////////////////////////
  /// FrameworkunifiedPrintXML
  /// Update the State information in the given stream in the form of XML tags
  ///
  /// \param [in] f_strXMLString
  ///     std::ostringstream & - reference to the XML stream
  ///
  /// \return EFrameworkunifiedStatus
  ///     EFrameworkunifiedStatus - Returns status of operation
  ///////////////////////////////////////////////////////////////////////////////////////////
  EFrameworkunifiedStatus FrameworkunifiedPrintXML(std::ostringstream &f_strXMLString);

  ///////////////////////////////////////////////////////////////////////////////////////////
  /// \ingroup tag_CFrameworkunifiedOrthogonalState
  /// \~english @par Brief
  ///        Always returns eFrameworkunifiedStatusOK (Successful).
  /// \~english @retval eFrameworkunifiedStatusOK success
  /// \~english @par Prerequisite
  ///       - Its own instance (CFrameworkunifiedOrthogonalState) has been created.
  /// \~english @par Change of internal state
  ///       - The internal state is not changed.
  /// \~english @par Conditions of processing failure
  ///       - None
  /// \~english @par Detail
  ///       In this class, eFrameworkunifiedStatusOK is always returned because the class does not require the History feature.\n
  ///       The History feature holds the active state prior to preprocessing and
  ///       returns the inside state to the active state prior to processing after the processing is executed.
  /// \~english @par Classification
  ///       Public
  /// \~english @par Type
  ///       Not applicable
  /// \~english @see 
  ///////////////////////////////////////////////////////////////////////////////////////////
  /// UpdateHistory
  /// This function stores the last active state
  ///
  /// \return EFrameworkunifiedStatus
  ///     EFrameworkunifiedStatus - Returns status of operation
  EFrameworkunifiedStatus UpdateHistory();

 protected :

  ///////////////////////////////////////////////////////////////////////////////////////////
  /// FrameworkunifiedOnEntry
  /// state initialization can be performed in this function.
  ///
  /// \param [in] f_pEventData
  ///     CEventDataPtr - Event data
  ///
  /// \return EFrameworkunifiedStatus
  ///     EFrameworkunifiedStatus - Returns status of operation
  ///////////////////////////////////////////////////////////////////////////////////////////
  virtual EFrameworkunifiedStatus FrameworkunifiedOnEntry(CEventDataPtr f_pEventData);

  ///////////////////////////////////////////////////////////////////////////////////////////
  /// FrameworkunifiedOnExit
  /// state cleanup can be performed in this function.
  ///
  /// \param [in] f_pEventData
  ///     CEventDataPtr - Event data
  ///
  /// \return EFrameworkunifiedStatus
  ///     EFrameworkunifiedStatus - Returns status of operation
  ///////////////////////////////////////////////////////////////////////////////////////////
  virtual EFrameworkunifiedStatus FrameworkunifiedOnExit(CEventDataPtr f_pEventData);

 private:
  /// Pointer to the map that stores the pointer to Orthogonal region list
  OrthogonalRegionList *m_pOrthogonalReigonList;

  ///////////////////////////////////////////////////////////////////////////////////////////
  /// IsOrthogonalChildState
  /// Checks if the given state is a child of orthogonal region
  ///
  /// \param [in] f_pChildState
  ///     CFrameworkunifiedState* - Child state pointer
  ///
  /// \return TRUE/FASLE
  ///     BOOL - returns TRUE if the given state is child of orthogonal state
  ///////////////////////////////////////////////////////////////////////////////////////////
  BOOL IsOrthogonalChildState(CFrameworkunifiedState *f_pChildState);
};

#endif  // _FRAMEWORKUNIFIEDORTHOGONALSTATE_H  // NOLINT  (build/header_guard)
/** @}*/
/** @}*/
/** @}*/
/** @}*/
/** @}*/
//@}