diff -r 000000000000 -r 9cfd9a3ee49c networkprotocolmodules/networkprotocolmodule/LbsProtocolModule/inc/cstatemachinebase.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/networkprotocolmodules/networkprotocolmodule/LbsProtocolModule/inc/cstatemachinebase.h Tue Feb 02 01:50:39 2010 +0200 @@ -0,0 +1,416 @@ +// Copyright (c) 2006-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: +// This file defines the base class for protocol state machines. +// It also defined a timer class and a request queue class used +// by the state machines. +// +// + +/** + @file + @internalComponent + @test +*/ + +#ifndef __CSTATEMACHINEBASE_H__ +#define __CSTATEMACHINEBASE_H__ + +#include +#include +#include +#include +#include +#include +#include "lbstimer.h" +#include "lbsprotocolmoduleerrors.h" +#include "cprotocolmanager.h" + + +//----------------------------------------------------------------------------- +// State Machine Base Class +//----------------------------------------------------------------------------- + +/** KAssistDataTimerEvent +Identity of timer for when assistance data is expected from network +*/ +const TInt KAssistDataTimerEvent = 0x01; + +/** KAssistDataTimerDurationInSec +Timer duration for when assistance data is expected from network +*/ +const TInt KAssistDataTimerDurationInSec = 20; + + +class CStateQueue; +class CStateHandlerBase; + +/** Base class definition for protocol state machines. +This class provides support for common features of all state machines. + +A significant aspect incorporated in this base class is the active object +mechanism for performing state transitions. This feature is used to provide +state machines with the ability to perform autonomous and asynchronous actions +e.g. to receive a single network measurement control indication and to perform +one or more interactions with LBS. + +State transitions are broken down into stages: to leave one state and then +enter a new state. This staged approach ensures that lengthy protocol module +activity is broken down into shorter steps, thereby releasing the active +scheduler to process other threads. A self-completion approach is employed +to achieve this. @see CStateMachineBase::DoStateTransitionStage() + +The base class includes various attributes that describe protocol activity, +together with access methods used to retrieve the value of these attributes. +*/ +NONSHARABLE_CLASS(CStateMachineBase) : public CActive + { +public: + + /** State machine protocol state. + This defines the general protocol state for state machines. + */ + enum TProtocolState + { + /** Not valid */ + EStateNull, + /** Ready to use, but not currently active. */ + EStateReady, + /** Actively performing a protocol procedure. */ + EStateActive, + /** In the process of cancelling. */ + EStateCancelling + }; + + /** State machine cancel source. + This defines the source of a cancellation. + */ + enum TCancelSource + { + /** Not cancelling */ + ECancelNone, + /** The LBS client cancelled the procedure */ + ECancelClientCancel, + /** The LBS client cancelled the procedure and there should be no + cancellation messages sent to LBS + */ + ECancelClientCancelSilent, + /** The network cancelled the procedure */ + ECancelNetworkCancel, + /** A network error occurred */ + ECancelNetworkError, + /** A client LBS timeout occurred */ + ECancelClientTimeout, + /** A network timeout occurred */ + ECancelNetworkTimeout, + /** State machine is closing down (destruction)*/ + ECancelClosing + }; + +protected: + + /** State transition stage. + This defines the individual stages used when a state machine makes a + transition from one state to another. This approach allows the state + machine to perform a number of asynchronous actions without making + any call to RunL too lengthy. + */ + enum TTransitionStage + { + /** Not in a transition */ + ETransitionNull, + /** Exit from current state */ + ETransitionExit, + /** Enter new state */ + ETransitionEnter + }; + +public: + + virtual ~CStateMachineBase(); + + void PerformStateTransition(); + void EnterNewState(); + void ExitCurrentState(); + void SetMachineAsQueued(); + void CheckForQueuedRequest(); + void CancelMachine(const TCancelSource& aCancelSource); + void CancelMachine(const TCancelSource& aCancelSource, TInt aReason); + + void StartAssistDataTimer(); + + void SessionId(const TLbsNetSessionId& aSessionId); + void QueueSessionId(const TLbsNetSessionId& aSessionId); + void ResetSessionId(); + const TLbsNetSessionId& SessionId() const; + const TLbsNetSessionId& QueueSessionId() const; + MStateMachineObserver& Observer(); + TProtocolState State() const; + + TBool IsMachineQueued() const; + + virtual TInt ClientCloseReason() const; + TInt NetworkCloseReason() const; + TBool IsNetworkConnectionError() const; + TBool IsSilentClientCancel() const; + + TInt LocRespReason() const; + MLbsNetworkProtocolObserver::TLbsNetProtocolService LocReqType() const; + + const TPositionInfoBase& LocRespPosition() const; + const TPositionInfoBase& ReferenceLoc() const; + const TLbsNetPosRequestQuality& LocReqQuality() const; + const TLbsNetPosRequestMethod& PosMethod() const; + + TBool IsLocReqReceived() const; + TBool IsLocRespSent() const; + TBool IsMeasureControlHandled() const; + TBool IsAssistanceDataActionReq() const; + + void HandleMeasureControlError(const TBool& aCancelRequired, TInt aReason); + + // CActive derived methods + + void RunL(); + void DoCancel(); + + // Methods that can be overriden in derived classes + + virtual void MeasurementControlInd(const TPositionInfoBase& aPosInfo, + const TLbsNetPosRequestQuality& aQuality, + const TLbsNetPosRequestMethod& aPosMethod); + virtual void AssistanceDataReq(); + virtual void AdditionalAssistDataInd(); + virtual void MeasurementControlErrorInd(TInt aReason); + virtual void NetworkErrorInd(); + + + // Pure virtual methods to be implemented in derived classes + + /** Start the previously queued state machine. + Derived classes implement a method to start the state machine + which has been previously queued by the Protocol Manager. + */ + virtual void StartQueuedMachine() = 0; + + /** Timeout occured waiting for measurement control from network. + Derived classes implement a method to handle this timeout, with due + consideration of the prevailing state machine activity. + */ + virtual void MeasurementControlTimeout() = 0; + + /** A location response has been received from LBS. + Derived classes implement a method to handle this response, with due + consideration of the prevailing state machine activity. + */ + virtual void LocationResp(TInt aReason, const TPositionInfoBase& aPosInfo) = 0; + + /** Prepare state transition. + Derived classes implement a method to perform actions prior to a state transition. + */ + virtual void PreStateTransition() = 0; + + /** Change state. + Derived classes implement a method to perform actions during a state transition. + */ + virtual void StateTransition() = 0; + + /** Complete state transition. + Derived classes implement a method to perform actions after a state transition. + */ + virtual void PostStateTransition() = 0; + + /** Cancel the active procedure. + Derived classes implement a method to cancel the active procedure. + */ + virtual void CancelProcedure() = 0; + + /** Do queued request. + Derived classes implement a method to perform any requests that were queued + due to busy activity. + */ + virtual void DoQueuedRequest(TInt aRequest) = 0; + +protected: + + CStateMachineBase(MStateMachineObserver& aObserver); + + void InitialiseMachineBase(); + void CompleteMachineBase(); + + void StoreLocationResp(TInt aReason, const TPositionInfoBase& aPosInfo); + void StoreNetLocCancelReason(TInt aReason); + void StoreLocReqQuality(const TLbsNetPosRequestQuality& aQuality); + void StoreRefLoc(const TPositionInfoBase& aPosInfo); + void StorePosMethod(const TLbsNetPosRequestMethod& aPosMethod); + + TBool Cancelling() const; + TBool CancelPending() const; + void SetMachineAsCancelling(); + +private: + + void DoStateTransitionStage(); + +protected: + + /** Reference to State machine observer + */ + MStateMachineObserver& iObserver; + + /** Local queue for buffering requests. + */ + CStateQueue* iQueue; + + /** Pointer to state handler. + This is owned by the derived classes that create state handlers. + */ + CStateHandlerBase* iStateHandler; + + /** Current protocol state. + */ + TProtocolState iProtocolState; + + /** Indicates if state machine is in a queued state. + */ + TBool iIsMachineQueued; + + /** Session ID. + This is owned by the derived classes that create state handlers. + */ + TLbsNetSessionId iSessionId; + + /** ID for a queued session. + This is owned by the derived classes that create state handlers. + */ + TLbsNetSessionId iQueueSessionId; + + /** State transition stage enumeration. + */ + TTransitionStage iTransitionState; + + /** Timer for additional assistance data expected from network + */ + CLbsCallbackTimer* iAssistDataTimer; + + /** Network Session result. + */ + TInt iNetSessionResult; + + /** Flag to indicate if state machine is to be cancelled. + */ + TBool iIsCancelPending; + + /** Indication of the source for cancellation. + */ + TCancelSource iCancelSource; + + /** A specific reason for client cancelling. + */ + TInt iClientCancelReason; + + /** A specific reason for network cancelling. + */ + TInt iNetworkCancelReason; + + /** Flag to show assistance data action required. + This indicates when assistance data has been requested or received + and is used to decide when to perform corresponding actions. + */ + TBool iAssistanceDataActionRequired; + + /** Flag to show location request has been received. + */ + TBool iIsLocReqReceived; + + /** Flag to show that a response to the location request has + been sent to the network + */ + TBool iIsLocRespSent; + + /** Flag to show measurement control data has been handled. + */ + TBool iIsMeasureControlHandled; + + /** Flag to show additional assistance data is expected. + */ + TBool iIsAdditionalDataExpected; + + /** Location request type. + */ + MLbsNetworkProtocolObserver::TLbsNetProtocolService iLocReqType; + + /** Location error response reason. + */ + TInt iLocRespReason; + + /** Location response position info. + */ + TPositionInfo iLocRespPosInfo; + + /** Reference Location position info. + */ + TPositionInfo iReferenceLoc; + + /** Location request quality. + */ + TLbsNetPosRequestQuality iLocReqQuality; + + /** Network location request cancel reason. + */ + TInt iNetLocCancelReason; + + /** Location request positioning method. + */ + TLbsNetPosRequestMethod iPosMethod; + + }; + + +//----------------------------------------------------------------------------- +// State Machine Request Queue Class +//----------------------------------------------------------------------------- + +/** State machine queue. +This is used to hold requests that require asynchronous actions but have +arrived when the state machine is already in an active state. + +Requests are added to the queue and are popped off the queue by a state machine +when it is next in a position to be able to service the request. +*/ +NONSHARABLE_CLASS(CStateQueue) : public CBase +{ + +public: + static CStateQueue* NewL(TInt aMaxEntries); + ~CStateQueue(); + + TBool IsRequestPending(); + TInt AddRequest(TInt aNewRequest); + TInt PopRequest(); + +protected: + CStateQueue(TInt aMaxEntries); + void ConstructL(TInt aMaxEntries); + +protected: + /** The internal queue, represented by an array of request numbers. + */ + RArray iQueue; + /** The maximum number of request entries permitted in the queue. + */ + TInt iMaxEntries; +}; + + +#endif // __CSTATEMACHINEBASE_H__