2 * @copyright Copyright (c) 2016-2020 TOYOTA MOTOR CORPORATION.
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
17 ///////////////////////////////////////////////////////////////////////////////
18 /// \ingroup tag_StateMachine
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.
25 ///////////////////////////////////////////////////////////////////////////////
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.
34 /** @addtogroup BaseSystem
37 /** @addtogroup native_service
41 /** @addtogroup framework_unified
42 * @ingroup native_service
45 /** @addtogroup framework
46 * @ingroup framework_unified
49 /** @addtogroup statemachine
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__
56 ///////////////////////////////////////////////////////////////////////////////////////////////////
58 ///////////////////////////////////////////////////////////////////////////////////////////////////
60 #include <native_service/frameworkunified_sm_reaction.h>
66 class CFrameworkunifiedReaction;
67 class CFrameworkunifiedHSM;
69 /// defines the map of event reactions
70 typedef std::map<UI_32, CFrameworkunifiedReaction *> EventReactionList;
72 typedef std::vector<UI_32> DeferredEventList;
74 /// defines the map of event names
75 typedef std::map<UI_32, std::string> EventNameList;
77 /// defines the iterator for event reaction map
78 typedef std::map<UI_32, CFrameworkunifiedReaction *>::iterator EventReactionIterator;;
80 typedef std::vector<CEventDataPtr> EventInfoList;
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 {
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
97 /// \~english @par Change of internal state
99 /// \~english @par Conditions of processing failure
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
114 /// \~english @par Type
116 /// \~english @see ~CFrameworkunifiedState
117 ///////////////////////////////////////////////////////////////////////////////////////////
118 /// CFrameworkunifiedState
119 /// Parameterized constructor
120 /// \param [in] f_pName
121 /// string - Name of the state
124 CFrameworkunifiedState(std::string f_pName); // NOLINT (readability/nolint)
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
136 /// \~english @par Conditions of processing failure
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
147 /// \~english @par Type
149 /// \~english @see CFrameworkunifiedState
150 ///////////////////////////////////////////////////////////////////////////////////////////
151 ///////////////////////////////////////////////////////////////////////////////////////////
152 /// ~CFrameworkunifiedState
156 virtual ~CFrameworkunifiedState();
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
172 /// \~english @par Change of internal state
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
180 /// \~english @par Type
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.
191 /// \param [in] f_uiEventId
192 /// UI_32 - Event id of the event to be added in the state
194 /// \param [in] f_pReaction
195 /// CFrameworkunifiedReaction* - Reaction to be associated with the with event id in the state
197 /// \param [in] f_strEventName
198 /// string - Name of the event (used for debugging purpose only)
200 /// \return EFrameworkunifiedStatus
201 /// EFrameworkunifiedStatus - Returns status of operation
203 ///////////////////////////////////////////////////////////////////////////////////////////
204 EFrameworkunifiedStatus FrameworkunifiedAddEvent(UI_32 f_uiEventId, CFrameworkunifiedReaction *f_pReaction, std::string f_strEventName = "");
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
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
229 /// \~english @par Type
231 /// \~english @see CEventData, FrameworkunifiedIsReactionAvailable
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.
242 /// \param [in] f_pEventData
243 /// CEventDataPtr - Event data
247 /// CFrameworkunifiedState* - Returns current state after the event is processed
249 virtual CFrameworkunifiedState *FrameworkunifiedOnEvent(CEventDataPtr f_pEventData);
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
263 /// \~english @par Change of internal state
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
271 /// \~english @par Type
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.
284 /// \param [in] f_uiEventId
285 /// UI_32 - Event id of the event to be added in the state
287 /// \param [in] f_strEventName
288 /// string - Name of the event (used for debugging purpose only)
290 /// \return EFrameworkunifiedStatus
291 /// EFrameworkunifiedStatus - Returns status of operation
293 ///////////////////////////////////////////////////////////////////////////////////////////
294 EFrameworkunifiedStatus FrameworkunifiedAddDeferredEvent(UI_32 f_uiEventId, std::string f_strEventName = "");
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
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
321 /// \~english @par Type
323 /// \~english @see FrameworkunifiedPostEvent(CEventDataPtr), CEventData, CFrameworkunifiedHSM::FrameworkunifiedQueueEvent, CFrameworkunifiedHSM::ProcessEvent
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.
332 /// \param [in] f_uiEventId
335 /// \return EFrameworkunifiedStatus
336 /// EFrameworkunifiedStatus - Returns status of operation
338 EFrameworkunifiedStatus FrameworkunifiedPostEvent(UI_32 f_uiEventId);
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
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
365 /// \~english @par Type
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.
375 /// \param [in] f_pEventData
376 /// CEventDataPtr - Event data
378 /// \return EFrameworkunifiedStatus
379 /// EFrameworkunifiedStatus - Returns status of operation
381 EFrameworkunifiedStatus FrameworkunifiedPostEvent(CEventDataPtr f_pEventData);
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
394 /// \~english @par Change of internal state
396 /// \~english @par Conditions of processing failure
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
403 /// \~english @par Type
407 /////////////////////////////////////////////////////////////////////////////////////
408 ///////////////////////////////////////////////////////////////////////////////////////////
409 /// FrameworkunifiedRemoveEventFromDeferredEventList
410 /// This function removes the event from the posted deferred queue list of the state.
412 /// \param [in] f_uiEventId
415 /// \return EFrameworkunifiedStatus
416 /// EFrameworkunifiedStatus - eFrameworkunifiedStatusOK if event removed
417 /// eFrameworkunifiedStatusInvldID if event not found in list
419 ///////////////////////////////////////////////////////////////////////////////////////////
420 EFrameworkunifiedStatus FrameworkunifiedRemoveEventFromDeferredEventList(UI_32 f_uiEventId);
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
432 /// \~english @par Conditions of processing failure
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
439 /// \~english @par Type
441 /// \~english @see CFrameworkunifiedCompositeState::FrameworkunifiedHasSubStates
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
449 /// \return TRUE/FASLE
450 /// BOOL - returns TRUE if it has sub states otherwise returns false.
451 virtual BOOL FrameworkunifiedHasSubStates();
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
463 /// \~english @par Conditions of processing failure
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
470 /// \~english @par Type
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
479 /// \return TRUE/FASLE
480 /// BOOL - returns TRUE if it has sub states otherwise returns false.
481 ///////////////////////////////////////////////////////////////////////////////////////////
482 virtual BOOL FrameworkunifiedHasOrthogoanlRegions();
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
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
505 /// \~english @par Classification
507 /// \~english @par Type
510 ///////////////////////////////////////////////////////////////////////////////////////////
511 ///////////////////////////////////////////////////////////////////////////////////////////
512 /// FrameworkunifiedPrintStates
513 /// This logs the state name and events associated with the state
515 /// \return EFrameworkunifiedStatus
516 /// EFrameworkunifiedStatus - Returns status of operation
517 ///////////////////////////////////////////////////////////////////////////////////////////
518 virtual EFrameworkunifiedStatus FrameworkunifiedPrintStates();
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
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
540 /// \~english @par Type
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.
549 /// \param [in] f_pEventData
550 /// CEventDataPtr - Event data
552 /// \return CurrentState
553 /// CFrameworkunifiedState* - Returns current state after operation
554 ///////////////////////////////////////////////////////////////////////////////////////////
555 virtual CFrameworkunifiedState *FrameworkunifiedOnHSMStart(CEventDataPtr f_pEventData);
557 ///////////////////////////////////////////////////////////////////////////////////////////
558 /// \ingroup CFrameworkunifiedState
559 /// \~english @par Brief
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
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
580 /// \~english @par Type
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.
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);
596 ///////////////////////////////////////////////////////////////////////////////////////////
597 /// \ingroup CFrameworkunifiedState
598 /// \~english @par Brief
599 /// Check the availability of event.
600 /// \~english @param [in] f_uiEventId
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
608 /// \~english @par Conditions of processing failure
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
618 /// \~english @par Type
620 /// \~english @see FrameworkunifiedPostEvent
621 ///////////////////////////////////////////////////////////////////////////////////////////
622 ///////////////////////////////////////////////////////////////////////////////////////////
623 /// FrameworkunifiedIsReactionAvailable
626 /// \param [in] f_uiEventId
627 /// UI_32 - Event identifier
629 /// \return TRUE/FASLE
630 /// BOOL - returns TRUE if it reaction is available for this event
631 virtual BOOL FrameworkunifiedIsReactionAvailable(UI_32 f_uiEventId);
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
641 /// \~english @par Change of the internal state
643 /// \~english @par Causes of failures
645 /// \~english @par Classification
647 /// \~english @par Type
649 /// \~english @par Detail
650 /// pure virtual function , implement by child class
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
658 /// \return Active state
659 /// CFrameworkunifiedState* - Active state
660 ///////////////////////////////////////////////////////////////////////////////////////////
661 virtual CFrameworkunifiedState *FrameworkunifiedGetActiveState() = 0;
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
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
683 /// \~english @par Type
685 /// \~english @see CFrameworkunifiedHSM
686 ///////////////////////////////////////////////////////////////////////////////////////////
687 ///////////////////////////////////////////////////////////////////////////////////////////
688 /// FrameworkunifiedSetHSM
689 /// This Interface associates the gives statemachine with the current state
691 /// \param [in] f_pStatemachine
692 /// CFrameworkunifiedHSM* - Statemachine associated with the state.
694 /// \return EFrameworkunifiedStatus
695 /// EFrameworkunifiedStatus - Returns status of operation
696 virtual EFrameworkunifiedStatus FrameworkunifiedSetHSM(CFrameworkunifiedHSM *f_pStatemachine);
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
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
717 /// \~english @par Type
719 /// \~english @see CFrameworkunifiedHSM::FrameworkunifiedGetAppHandle
720 ///////////////////////////////////////////////////////////////////////////////////////////
721 ///////////////////////////////////////////////////////////////////////////////////////////
722 /// FrameworkunifiedGetAppHandle
723 /// This interface returns the application handle
726 /// HANDLE - Application Handle
728 virtual HANDLE FrameworkunifiedGetAppHandle();
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
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
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
752 /// \~english @par Type
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
760 /// \param [in] f_strXMLString
761 /// std::ostringstream & - reference to the XML stream
763 /// \return EFrameworkunifiedStatus
764 /// EFrameworkunifiedStatus - Returns status of operation
765 virtual EFrameworkunifiedStatus FrameworkunifiedPrintXML(std::ostringstream &f_strXMLString);
767 /////////////////////////////////////////////////////////////////////////////////////
768 /// \ingroup CFrameworkunifiedState
769 /// \~english @par Summary
770 /// pure virtual fuction
771 /// \~english @param None
772 /// \~english @retval None
773 /// \~english @par Preconditions
775 /// \~english @par Change of the internal state
777 /// \~english @par Causes of failures
779 /// \~english @par Classification
781 /// \~english @par Type
783 /// \~english @par Detail
784 /// pure virtual function , implement by child class
786 ////////////////////////////////////////////////////////////////////////////////////
787 ///////////////////////////////////////////////////////////////////////////////////////////
789 /// This function stores the last active state
791 /// \return EFrameworkunifiedStatus
792 /// EFrameworkunifiedStatus - Returns status of operation
793 ///////////////////////////////////////////////////////////////////////////////////////////
794 virtual EFrameworkunifiedStatus UpdateHistory() = 0;
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.
802 /// \param [in] f_pEventData
803 /// CEventDataPtr - Event data
805 /// \return EFrameworkunifiedStatus
806 /// EFrameworkunifiedStatus - Returns status of operation
807 ///////////////////////////////////////////////////////////////////////////////////////////
808 virtual EFrameworkunifiedStatus FrameworkunifiedOnEntry(CEventDataPtr f_pEventData) = 0;
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.
815 /// \param [in] f_pEventData
816 /// CEventDataPtr - Event data
818 /// \return EFrameworkunifiedStatus
819 /// EFrameworkunifiedStatus - Returns status of operation
820 ///////////////////////////////////////////////////////////////////////////////////////////
821 virtual EFrameworkunifiedStatus FrameworkunifiedOnExit(CEventDataPtr f_pEventData) = 0;
824 ///////////////////////////////////////////////////////////////////////////////////////////
826 /// This checks if the given event is marked as deferred in the state.
828 /// \param [in] f_uiEventId
829 /// UI_32 - Event identifier
832 /// BOOL - event deferred or not
833 ///////////////////////////////////////////////////////////////////////////////////////////
834 BOOL IsEventDeferred(UI_32 f_uiEventId);
838 std::string m_strStateName;
840 /// Pointer to the parent state
841 CFrameworkunifiedState *m_pParentState;
843 /// pointer to the default state
844 CFrameworkunifiedState *m_pDefaultState;
846 /// pointer to the active state
847 CFrameworkunifiedState *m_pActiveState;
849 /// pointer to the map that stores the event name against event id
850 EventNameList *m_pEventName;
853 /// pointer to the map that stores the reaction against event id
854 EventReactionList *m_pEventList;
856 /// pointer to the map that stores deferred event ids
857 DeferredEventList *m_pDeferredEventList;
859 /// pointer to the vector that stores the eventinfo of the posted deferred event
860 EventInfoList *m_pDeferredPostEventList;
862 /// pointer to the application statemachine
863 CFrameworkunifiedHSM *m_pStateMachine;
866 #endif // __FRAMEWORKUNIFIED_NATIVESERVICES_NATIVESERVICES_INC_FRAMEWORK_STATEMACHINE_FRAMEWORKUNIFIED_SM_STATE_H__ // NOLINT (build/header_guard)