--- /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 <e32base.h>
+#include <lbs/lbslocdatasourcegpsbase.h>
+#include <lbspositioninfo.h>
+#include <lbs/lbsnetcommon.h>
+#include <lbs/lbsnetprotocolbase.h>
+#include <lbs/lbsloccommon.h>
+#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<TInt> iQueue;
+	/** The maximum number of request entries permitted in the queue.
+	*/
+	TInt iMaxEntries;
+};
+
+
+#endif // __CSTATEMACHINEBASE_H__