// Copyright (c) 2003-2009 Nokia Corporation and/or its subsidiary(-ies).

// All rights reserved.

// This component and the accompanying materials are made available

// under the terms of "Eclipse Public License v1.0"

// which accompanies this distribution, and is available

// at the URL "http://www.eclipse.org/legal/epl-v10.html".

//

// Initial Contributors:

// Nokia Corporation - initial contribution.

//

// Contributors:

//

// Description:

// Offers a base class for an asynchronous state machine

// THIS API IS INTERNAL TO NETWORKING AND IS SUBJECT TO CHANGE AND NOT FOR EXTERNAL USE

// 

//

/**

 @file 

 @internalTechnology

*/

#include <e32base.h>

#ifndef _STATEMACHINE_H_

#define _STATEMACHINE_H_

class CAsynchEvent;

class CStateMachine;

/**

 The statemachine notifier interface.

 If the notifier is registered with a CStateMachine instance 

 it receives state machine events

 @see CStateMachine

 @internalTechnology

**/

class MStateMachineNotify

   {

   public:

      virtual ~MStateMachineNotify() {};

      /** 

       * Called by RunL when the state machine completed its task.

       *

       * @param aStateMachine the instance that has raised the event

       * @return if the value is ETrue then aStateMachine deletes itself 

       */

      virtual TBool OnCompletion( CStateMachine* aStateMachine ) = 0;

   };

/**

 The base class for asynchronous state machine with the next state represented 

 by CAsynchEvent.

 The class is not thread safe

 @see CAsynchEvent

 @internalTechnology

**/

class CStateMachine : public CActive

   {

   public:

      IMPORT_C ~CStateMachine();

      TInt LastError() const;

      void SetLastError( TInt aLastError );

      void SetClientStatus( TRequestStatus* aClientStatus );

      TRequestStatus* ClientStatus() const;

      void SetActiveEvent( CAsynchEvent* aEvent );

      void SetErrorEvent( CAsynchEvent* aEvent );

      void SetSuspendRequest( TBool aSuspendRequest );

      TBool SuspendRequest() const;

      void UpdateHistory( TInt aUpdate );

      TInt History() const;

      void RegisterNotify( MStateMachineNotify* aStateMachineNotify );

      void DeRegisterNotify( MStateMachineNotify* aStateMachineNotify );

      IMPORT_C void Start( TRequestStatus* aClientStatus, CAsynchEvent* aErrorEvent, MStateMachineNotify* aStateMachineNotify

         /*the object is NOT taking ownership of the params*/ );

      //CActive::Cancel method should not be used

      IMPORT_C void Cancel( TInt aLastError );

      IMPORT_C HBufC8* ReAllocL( TInt aNewLength );

      HBufC8* Fragment() const;

   protected:

      IMPORT_C CStateMachine();

	   IMPORT_C virtual void DoCancel();

	   IMPORT_C virtual void RunL();

	   IMPORT_C virtual TInt RunError(TInt aError);

      IMPORT_C void OnError();

      IMPORT_C virtual void OnCompletion();

   protected:

      CAsynchEvent* iActiveEvent; //referenced not owned

      CAsynchEvent* iErrorEvent; //referenced not owned

      TInt iHistory;

      TInt iLastError;

      TRequestStatus* iClientStatus; //optional

      HBufC8* iFragment; //shared data fragment buffer owned by this class

      MStateMachineNotify* iStateMachineNotify; //one at the time so far

      TBool iSuspendRequest : 1; //if ETrue causes the state machine to stop after completion of

      //ongoing asynch event (no client request will be completed but MStateMachineNotify::OnCompletion

      //will be called if installed)

   };

inline void CStateMachine::SetActiveEvent( CAsynchEvent* aEvent )

/** 

 * Sets the active event (the next state of the instance).

 * An ownership is not transfered

 *

 * @param aEvent a pointer to the active event

 */

   {

   iActiveEvent = aEvent;

   }

inline void CStateMachine::SetErrorEvent( CAsynchEvent* aEvent )

/** 

 * Sets the error event (the one called if RunL leaves or completes with an error).

 * An ownership is not transfered

 *

 * @param aEvent a pointer to the error event

 */

   {

   iErrorEvent = aEvent;

   }

inline TBool CStateMachine::SuspendRequest() const

/** 

 * Query for suspend request

 *

 * @return iSuspendRequest

 */

   {

   return iSuspendRequest;

   }

inline void CStateMachine::SetSuspendRequest( TBool aSuspendRequest )

/** 

 * Sets the suspend request

 * If ETrue than it will stop the state machine to stop before 

 * processing the iActiveEvent. Notifier is notified but client request is not completed

 *

 * @return iSuspendRequest

 */

   {

   iSuspendRequest = aSuspendRequest;

   }

inline void CStateMachine::DeRegisterNotify( MStateMachineNotify* /*aStateMachineNotify*/ )

/** 

 * De-registers the notifier

 *

 * @param aStateMachineNotify not used

 */

   {

   iStateMachineNotify = NULL; //so far it's simple

   }

inline void CStateMachine::RegisterNotify( MStateMachineNotify* aStateMachineNotify )

/** 

 * Registers the notifier

 *

 * @param aStateMachineNotify a notifier to register. An ownership is not transfered

 */

   {

   iStateMachineNotify = aStateMachineNotify;

   }

inline void CStateMachine::SetClientStatus( TRequestStatus* aClientStatus )

/** 

 * Sets a request status to complete.

 * It does not transfer the ownership

 *

 * @param aClientStatus the client request to complete

 */

   {

   iClientStatus = aClientStatus;

   }

inline TRequestStatus* CStateMachine::ClientStatus() const

/** 

 * Gets a request status to complete.

 *

 * @return aClientStatus the client request to complete

 */

   {

   return iClientStatus;

   }

inline HBufC8* CStateMachine::Fragment() const

/** 

 * Gets a pointer to an arbitrary data fragment owned by the instance

 *

 * @return a pointer to the fragment

 */

   {

   return iFragment;

   }

inline void CStateMachine::UpdateHistory( TInt aUpdate )

/** 

 * Updates the state machine history whatever the history means in the context 

 * the instance is being used

 *

 * @param aUpdate a value to OR with the current history

 */

   {

   iHistory |= aUpdate;

   }

inline TInt CStateMachine::History() const

/** 

 * Gets the state machine history whatever the history means in the context 

 * the instance is being used

 *

 * @return the history

 */

   {

   return iHistory;

   }

inline TInt CStateMachine::LastError() const

/** 

 * Gets the last error set when an active event processing leaves or completes

   with an error

 *

 * @return the last error

 */

   {

   return iLastError;

   }

inline void CStateMachine::SetLastError( TInt aLastError )

/** 

 * Sets the last error

 *

 * @param aLastError a value of the last error

 */

   {

   iLastError = aLastError;

   }

#endif