|
1 // Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies). |
|
2 // All rights reserved. |
|
3 // This component and the accompanying materials are made available |
|
4 // under the terms of "Eclipse Public License v1.0" |
|
5 // which accompanies this distribution, and is available |
|
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // This file defines the base class for protocol state machines. |
|
15 // It also defined a timer class and a request queue class used |
|
16 // by the state machines. |
|
17 // |
|
18 // |
|
19 |
|
20 /** |
|
21 @file |
|
22 @internalComponent |
|
23 @test |
|
24 */ |
|
25 |
|
26 #ifndef __CSTATEMACHINEBASE_H__ |
|
27 #define __CSTATEMACHINEBASE_H__ |
|
28 |
|
29 #include <e32base.h> |
|
30 #include <lbs/lbslocdatasourcegpsbase.h> |
|
31 #include <lbspositioninfo.h> |
|
32 #include <lbs/lbsnetcommon.h> |
|
33 #include <lbs/lbsnetprotocolbase.h> |
|
34 #include <lbs/lbsloccommon.h> |
|
35 #include "lbstimer.h" |
|
36 #include "lbsprotocolmoduleerrors.h" |
|
37 #include "cprotocolmanager.h" |
|
38 |
|
39 |
|
40 //----------------------------------------------------------------------------- |
|
41 // State Machine Base Class |
|
42 //----------------------------------------------------------------------------- |
|
43 |
|
44 /** KAssistDataTimerEvent |
|
45 Identity of timer for when assistance data is expected from network |
|
46 */ |
|
47 const TInt KAssistDataTimerEvent = 0x01; |
|
48 |
|
49 /** KAssistDataTimerDurationInSec |
|
50 Timer duration for when assistance data is expected from network |
|
51 */ |
|
52 const TInt KAssistDataTimerDurationInSec = 20; |
|
53 |
|
54 |
|
55 class CStateQueue; |
|
56 class CStateHandlerBase; |
|
57 |
|
58 /** Base class definition for protocol state machines. |
|
59 This class provides support for common features of all state machines. |
|
60 |
|
61 A significant aspect incorporated in this base class is the active object |
|
62 mechanism for performing state transitions. This feature is used to provide |
|
63 state machines with the ability to perform autonomous and asynchronous actions |
|
64 e.g. to receive a single network measurement control indication and to perform |
|
65 one or more interactions with LBS. |
|
66 |
|
67 State transitions are broken down into stages: to leave one state and then |
|
68 enter a new state. This staged approach ensures that lengthy protocol module |
|
69 activity is broken down into shorter steps, thereby releasing the active |
|
70 scheduler to process other threads. A self-completion approach is employed |
|
71 to achieve this. @see CStateMachineBase::DoStateTransitionStage() |
|
72 |
|
73 The base class includes various attributes that describe protocol activity, |
|
74 together with access methods used to retrieve the value of these attributes. |
|
75 */ |
|
76 NONSHARABLE_CLASS(CStateMachineBase) : public CActive |
|
77 { |
|
78 public: |
|
79 |
|
80 /** State machine protocol state. |
|
81 This defines the general protocol state for state machines. |
|
82 */ |
|
83 enum TProtocolState |
|
84 { |
|
85 /** Not valid */ |
|
86 EStateNull, |
|
87 /** Ready to use, but not currently active. */ |
|
88 EStateReady, |
|
89 /** Actively performing a protocol procedure. */ |
|
90 EStateActive, |
|
91 /** In the process of cancelling. */ |
|
92 EStateCancelling |
|
93 }; |
|
94 |
|
95 /** State machine cancel source. |
|
96 This defines the source of a cancellation. |
|
97 */ |
|
98 enum TCancelSource |
|
99 { |
|
100 /** Not cancelling */ |
|
101 ECancelNone, |
|
102 /** The LBS client cancelled the procedure */ |
|
103 ECancelClientCancel, |
|
104 /** The LBS client cancelled the procedure and there should be no |
|
105 cancellation messages sent to LBS |
|
106 */ |
|
107 ECancelClientCancelSilent, |
|
108 /** The network cancelled the procedure */ |
|
109 ECancelNetworkCancel, |
|
110 /** A network error occurred */ |
|
111 ECancelNetworkError, |
|
112 /** A client LBS timeout occurred */ |
|
113 ECancelClientTimeout, |
|
114 /** A network timeout occurred */ |
|
115 ECancelNetworkTimeout, |
|
116 /** State machine is closing down (destruction)*/ |
|
117 ECancelClosing |
|
118 }; |
|
119 |
|
120 protected: |
|
121 |
|
122 /** State transition stage. |
|
123 This defines the individual stages used when a state machine makes a |
|
124 transition from one state to another. This approach allows the state |
|
125 machine to perform a number of asynchronous actions without making |
|
126 any call to RunL too lengthy. |
|
127 */ |
|
128 enum TTransitionStage |
|
129 { |
|
130 /** Not in a transition */ |
|
131 ETransitionNull, |
|
132 /** Exit from current state */ |
|
133 ETransitionExit, |
|
134 /** Enter new state */ |
|
135 ETransitionEnter |
|
136 }; |
|
137 |
|
138 public: |
|
139 |
|
140 virtual ~CStateMachineBase(); |
|
141 |
|
142 void PerformStateTransition(); |
|
143 void EnterNewState(); |
|
144 void ExitCurrentState(); |
|
145 void SetMachineAsQueued(); |
|
146 void CheckForQueuedRequest(); |
|
147 void CancelMachine(const TCancelSource& aCancelSource); |
|
148 void CancelMachine(const TCancelSource& aCancelSource, TInt aReason); |
|
149 |
|
150 void StartAssistDataTimer(); |
|
151 |
|
152 void SessionId(const TLbsNetSessionId& aSessionId); |
|
153 void QueueSessionId(const TLbsNetSessionId& aSessionId); |
|
154 void ResetSessionId(); |
|
155 const TLbsNetSessionId& SessionId() const; |
|
156 const TLbsNetSessionId& QueueSessionId() const; |
|
157 MStateMachineObserver& Observer(); |
|
158 TProtocolState State() const; |
|
159 |
|
160 TBool IsMachineQueued() const; |
|
161 |
|
162 virtual TInt ClientCloseReason() const; |
|
163 TInt NetworkCloseReason() const; |
|
164 TBool IsNetworkConnectionError() const; |
|
165 TBool IsSilentClientCancel() const; |
|
166 |
|
167 TInt LocRespReason() const; |
|
168 MLbsNetworkProtocolObserver::TLbsNetProtocolService LocReqType() const; |
|
169 |
|
170 const TPositionInfoBase& LocRespPosition() const; |
|
171 const TPositionInfoBase& ReferenceLoc() const; |
|
172 const TLbsNetPosRequestQuality& LocReqQuality() const; |
|
173 const TLbsNetPosRequestMethod& PosMethod() const; |
|
174 |
|
175 TBool IsLocReqReceived() const; |
|
176 TBool IsLocRespSent() const; |
|
177 TBool IsMeasureControlHandled() const; |
|
178 TBool IsAssistanceDataActionReq() const; |
|
179 |
|
180 void HandleMeasureControlError(const TBool& aCancelRequired, TInt aReason); |
|
181 |
|
182 // CActive derived methods |
|
183 |
|
184 void RunL(); |
|
185 void DoCancel(); |
|
186 |
|
187 // Methods that can be overriden in derived classes |
|
188 |
|
189 virtual void MeasurementControlInd(const TPositionInfoBase& aPosInfo, |
|
190 const TLbsNetPosRequestQuality& aQuality, |
|
191 const TLbsNetPosRequestMethod& aPosMethod); |
|
192 virtual void AssistanceDataReq(); |
|
193 virtual void AdditionalAssistDataInd(); |
|
194 virtual void MeasurementControlErrorInd(TInt aReason); |
|
195 virtual void NetworkErrorInd(); |
|
196 |
|
197 |
|
198 // Pure virtual methods to be implemented in derived classes |
|
199 |
|
200 /** Start the previously queued state machine. |
|
201 Derived classes implement a method to start the state machine |
|
202 which has been previously queued by the Protocol Manager. |
|
203 */ |
|
204 virtual void StartQueuedMachine() = 0; |
|
205 |
|
206 /** Timeout occured waiting for measurement control from network. |
|
207 Derived classes implement a method to handle this timeout, with due |
|
208 consideration of the prevailing state machine activity. |
|
209 */ |
|
210 virtual void MeasurementControlTimeout() = 0; |
|
211 |
|
212 /** A location response has been received from LBS. |
|
213 Derived classes implement a method to handle this response, with due |
|
214 consideration of the prevailing state machine activity. |
|
215 */ |
|
216 virtual void LocationResp(TInt aReason, const TPositionInfoBase& aPosInfo) = 0; |
|
217 |
|
218 /** Prepare state transition. |
|
219 Derived classes implement a method to perform actions prior to a state transition. |
|
220 */ |
|
221 virtual void PreStateTransition() = 0; |
|
222 |
|
223 /** Change state. |
|
224 Derived classes implement a method to perform actions during a state transition. |
|
225 */ |
|
226 virtual void StateTransition() = 0; |
|
227 |
|
228 /** Complete state transition. |
|
229 Derived classes implement a method to perform actions after a state transition. |
|
230 */ |
|
231 virtual void PostStateTransition() = 0; |
|
232 |
|
233 /** Cancel the active procedure. |
|
234 Derived classes implement a method to cancel the active procedure. |
|
235 */ |
|
236 virtual void CancelProcedure() = 0; |
|
237 |
|
238 /** Do queued request. |
|
239 Derived classes implement a method to perform any requests that were queued |
|
240 due to busy activity. |
|
241 */ |
|
242 virtual void DoQueuedRequest(TInt aRequest) = 0; |
|
243 |
|
244 protected: |
|
245 |
|
246 CStateMachineBase(MStateMachineObserver& aObserver); |
|
247 |
|
248 void InitialiseMachineBase(); |
|
249 void CompleteMachineBase(); |
|
250 |
|
251 void StoreLocationResp(TInt aReason, const TPositionInfoBase& aPosInfo); |
|
252 void StoreNetLocCancelReason(TInt aReason); |
|
253 void StoreLocReqQuality(const TLbsNetPosRequestQuality& aQuality); |
|
254 void StoreRefLoc(const TPositionInfoBase& aPosInfo); |
|
255 void StorePosMethod(const TLbsNetPosRequestMethod& aPosMethod); |
|
256 |
|
257 TBool Cancelling() const; |
|
258 TBool CancelPending() const; |
|
259 void SetMachineAsCancelling(); |
|
260 |
|
261 private: |
|
262 |
|
263 void DoStateTransitionStage(); |
|
264 |
|
265 protected: |
|
266 |
|
267 /** Reference to State machine observer |
|
268 */ |
|
269 MStateMachineObserver& iObserver; |
|
270 |
|
271 /** Local queue for buffering requests. |
|
272 */ |
|
273 CStateQueue* iQueue; |
|
274 |
|
275 /** Pointer to state handler. |
|
276 This is owned by the derived classes that create state handlers. |
|
277 */ |
|
278 CStateHandlerBase* iStateHandler; |
|
279 |
|
280 /** Current protocol state. |
|
281 */ |
|
282 TProtocolState iProtocolState; |
|
283 |
|
284 /** Indicates if state machine is in a queued state. |
|
285 */ |
|
286 TBool iIsMachineQueued; |
|
287 |
|
288 /** Session ID. |
|
289 This is owned by the derived classes that create state handlers. |
|
290 */ |
|
291 TLbsNetSessionId iSessionId; |
|
292 |
|
293 /** ID for a queued session. |
|
294 This is owned by the derived classes that create state handlers. |
|
295 */ |
|
296 TLbsNetSessionId iQueueSessionId; |
|
297 |
|
298 /** State transition stage enumeration. |
|
299 */ |
|
300 TTransitionStage iTransitionState; |
|
301 |
|
302 /** Timer for additional assistance data expected from network |
|
303 */ |
|
304 CLbsCallbackTimer* iAssistDataTimer; |
|
305 |
|
306 /** Network Session result. |
|
307 */ |
|
308 TInt iNetSessionResult; |
|
309 |
|
310 /** Flag to indicate if state machine is to be cancelled. |
|
311 */ |
|
312 TBool iIsCancelPending; |
|
313 |
|
314 /** Indication of the source for cancellation. |
|
315 */ |
|
316 TCancelSource iCancelSource; |
|
317 |
|
318 /** A specific reason for client cancelling. |
|
319 */ |
|
320 TInt iClientCancelReason; |
|
321 |
|
322 /** A specific reason for network cancelling. |
|
323 */ |
|
324 TInt iNetworkCancelReason; |
|
325 |
|
326 /** Flag to show assistance data action required. |
|
327 This indicates when assistance data has been requested or received |
|
328 and is used to decide when to perform corresponding actions. |
|
329 */ |
|
330 TBool iAssistanceDataActionRequired; |
|
331 |
|
332 /** Flag to show location request has been received. |
|
333 */ |
|
334 TBool iIsLocReqReceived; |
|
335 |
|
336 /** Flag to show that a response to the location request has |
|
337 been sent to the network |
|
338 */ |
|
339 TBool iIsLocRespSent; |
|
340 |
|
341 /** Flag to show measurement control data has been handled. |
|
342 */ |
|
343 TBool iIsMeasureControlHandled; |
|
344 |
|
345 /** Flag to show additional assistance data is expected. |
|
346 */ |
|
347 TBool iIsAdditionalDataExpected; |
|
348 |
|
349 /** Location request type. |
|
350 */ |
|
351 MLbsNetworkProtocolObserver::TLbsNetProtocolService iLocReqType; |
|
352 |
|
353 /** Location error response reason. |
|
354 */ |
|
355 TInt iLocRespReason; |
|
356 |
|
357 /** Location response position info. |
|
358 */ |
|
359 TPositionInfo iLocRespPosInfo; |
|
360 |
|
361 /** Reference Location position info. |
|
362 */ |
|
363 TPositionInfo iReferenceLoc; |
|
364 |
|
365 /** Location request quality. |
|
366 */ |
|
367 TLbsNetPosRequestQuality iLocReqQuality; |
|
368 |
|
369 /** Network location request cancel reason. |
|
370 */ |
|
371 TInt iNetLocCancelReason; |
|
372 |
|
373 /** Location request positioning method. |
|
374 */ |
|
375 TLbsNetPosRequestMethod iPosMethod; |
|
376 |
|
377 }; |
|
378 |
|
379 |
|
380 //----------------------------------------------------------------------------- |
|
381 // State Machine Request Queue Class |
|
382 //----------------------------------------------------------------------------- |
|
383 |
|
384 /** State machine queue. |
|
385 This is used to hold requests that require asynchronous actions but have |
|
386 arrived when the state machine is already in an active state. |
|
387 |
|
388 Requests are added to the queue and are popped off the queue by a state machine |
|
389 when it is next in a position to be able to service the request. |
|
390 */ |
|
391 NONSHARABLE_CLASS(CStateQueue) : public CBase |
|
392 { |
|
393 |
|
394 public: |
|
395 static CStateQueue* NewL(TInt aMaxEntries); |
|
396 ~CStateQueue(); |
|
397 |
|
398 TBool IsRequestPending(); |
|
399 TInt AddRequest(TInt aNewRequest); |
|
400 TInt PopRequest(); |
|
401 |
|
402 protected: |
|
403 CStateQueue(TInt aMaxEntries); |
|
404 void ConstructL(TInt aMaxEntries); |
|
405 |
|
406 protected: |
|
407 /** The internal queue, represented by an array of request numbers. |
|
408 */ |
|
409 RArray<TInt> iQueue; |
|
410 /** The maximum number of request entries permitted in the queue. |
|
411 */ |
|
412 TInt iMaxEntries; |
|
413 }; |
|
414 |
|
415 |
|
416 #endif // __CSTATEMACHINEBASE_H__ |