|
1 // Copyright (c) 2003-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 // Offers a base class for an asynchronous state machine |
|
15 // THIS API IS INTERNAL TO NETWORKING AND IS SUBJECT TO CHANGE AND NOT FOR EXTERNAL USE |
|
16 // |
|
17 // |
|
18 |
|
19 /** |
|
20 @file |
|
21 @internalTechnology |
|
22 */ |
|
23 |
|
24 #include <e32base.h> |
|
25 |
|
26 #ifndef _STATEMACHINE_H_ |
|
27 #define _STATEMACHINE_H_ |
|
28 |
|
29 class CAsynchEvent; |
|
30 |
|
31 class CStateMachine; |
|
32 /** |
|
33 The statemachine notifier interface. |
|
34 |
|
35 If the notifier is registered with a CStateMachine instance |
|
36 it receives state machine events |
|
37 @see CStateMachine |
|
38 @internalTechnology |
|
39 **/ |
|
40 class MStateMachineNotify |
|
41 { |
|
42 public: |
|
43 virtual ~MStateMachineNotify() {}; |
|
44 |
|
45 /** |
|
46 * Called by RunL when the state machine completed its task. |
|
47 * |
|
48 * @param aStateMachine the instance that has raised the event |
|
49 * @return if the value is ETrue then aStateMachine deletes itself |
|
50 */ |
|
51 virtual TBool OnCompletion( CStateMachine* aStateMachine ) = 0; |
|
52 }; |
|
53 |
|
54 /** |
|
55 The base class for asynchronous state machine with the next state represented |
|
56 by CAsynchEvent. |
|
57 |
|
58 The class is not thread safe |
|
59 @see CAsynchEvent |
|
60 @internalTechnology |
|
61 **/ |
|
62 class CStateMachine : public CActive |
|
63 { |
|
64 public: |
|
65 IMPORT_C ~CStateMachine(); |
|
66 |
|
67 TInt LastError() const; |
|
68 void SetLastError( TInt aLastError ); |
|
69 void SetClientStatus( TRequestStatus* aClientStatus ); |
|
70 TRequestStatus* ClientStatus() const; |
|
71 void SetActiveEvent( CAsynchEvent* aEvent ); |
|
72 void SetErrorEvent( CAsynchEvent* aEvent ); |
|
73 void SetSuspendRequest( TBool aSuspendRequest ); |
|
74 TBool SuspendRequest() const; |
|
75 |
|
76 void UpdateHistory( TInt aUpdate ); |
|
77 TInt History() const; |
|
78 |
|
79 void RegisterNotify( MStateMachineNotify* aStateMachineNotify ); |
|
80 void DeRegisterNotify( MStateMachineNotify* aStateMachineNotify ); |
|
81 |
|
82 IMPORT_C void Start( TRequestStatus* aClientStatus, CAsynchEvent* aErrorEvent, MStateMachineNotify* aStateMachineNotify |
|
83 /*the object is NOT taking ownership of the params*/ ); |
|
84 //CActive::Cancel method should not be used |
|
85 IMPORT_C void Cancel( TInt aLastError ); |
|
86 |
|
87 IMPORT_C HBufC8* ReAllocL( TInt aNewLength ); |
|
88 HBufC8* Fragment() const; |
|
89 |
|
90 protected: |
|
91 IMPORT_C CStateMachine(); |
|
92 |
|
93 IMPORT_C virtual void DoCancel(); |
|
94 IMPORT_C virtual void RunL(); |
|
95 IMPORT_C virtual TInt RunError(TInt aError); |
|
96 |
|
97 IMPORT_C void OnError(); |
|
98 IMPORT_C virtual void OnCompletion(); |
|
99 |
|
100 protected: |
|
101 CAsynchEvent* iActiveEvent; //referenced not owned |
|
102 CAsynchEvent* iErrorEvent; //referenced not owned |
|
103 TInt iHistory; |
|
104 TInt iLastError; |
|
105 |
|
106 TRequestStatus* iClientStatus; //optional |
|
107 HBufC8* iFragment; //shared data fragment buffer owned by this class |
|
108 |
|
109 MStateMachineNotify* iStateMachineNotify; //one at the time so far |
|
110 TBool iSuspendRequest : 1; //if ETrue causes the state machine to stop after completion of |
|
111 //ongoing asynch event (no client request will be completed but MStateMachineNotify::OnCompletion |
|
112 //will be called if installed) |
|
113 }; |
|
114 |
|
115 inline void CStateMachine::SetActiveEvent( CAsynchEvent* aEvent ) |
|
116 /** |
|
117 * Sets the active event (the next state of the instance). |
|
118 |
|
119 * An ownership is not transfered |
|
120 * |
|
121 * @param aEvent a pointer to the active event |
|
122 */ |
|
123 { |
|
124 iActiveEvent = aEvent; |
|
125 } |
|
126 |
|
127 inline void CStateMachine::SetErrorEvent( CAsynchEvent* aEvent ) |
|
128 /** |
|
129 * Sets the error event (the one called if RunL leaves or completes with an error). |
|
130 |
|
131 * An ownership is not transfered |
|
132 * |
|
133 * @param aEvent a pointer to the error event |
|
134 */ |
|
135 { |
|
136 iErrorEvent = aEvent; |
|
137 } |
|
138 |
|
139 inline TBool CStateMachine::SuspendRequest() const |
|
140 /** |
|
141 * Query for suspend request |
|
142 * |
|
143 * @return iSuspendRequest |
|
144 */ |
|
145 { |
|
146 return iSuspendRequest; |
|
147 } |
|
148 |
|
149 inline void CStateMachine::SetSuspendRequest( TBool aSuspendRequest ) |
|
150 /** |
|
151 * Sets the suspend request |
|
152 |
|
153 * If ETrue than it will stop the state machine to stop before |
|
154 * processing the iActiveEvent. Notifier is notified but client request is not completed |
|
155 * |
|
156 * @return iSuspendRequest |
|
157 */ |
|
158 { |
|
159 iSuspendRequest = aSuspendRequest; |
|
160 } |
|
161 |
|
162 inline void CStateMachine::DeRegisterNotify( MStateMachineNotify* /*aStateMachineNotify*/ ) |
|
163 /** |
|
164 * De-registers the notifier |
|
165 * |
|
166 * @param aStateMachineNotify not used |
|
167 */ |
|
168 { |
|
169 iStateMachineNotify = NULL; //so far it's simple |
|
170 } |
|
171 |
|
172 inline void CStateMachine::RegisterNotify( MStateMachineNotify* aStateMachineNotify ) |
|
173 /** |
|
174 * Registers the notifier |
|
175 * |
|
176 * @param aStateMachineNotify a notifier to register. An ownership is not transfered |
|
177 */ |
|
178 { |
|
179 iStateMachineNotify = aStateMachineNotify; |
|
180 } |
|
181 |
|
182 inline void CStateMachine::SetClientStatus( TRequestStatus* aClientStatus ) |
|
183 /** |
|
184 * Sets a request status to complete. |
|
185 |
|
186 * It does not transfer the ownership |
|
187 * |
|
188 * @param aClientStatus the client request to complete |
|
189 */ |
|
190 { |
|
191 iClientStatus = aClientStatus; |
|
192 } |
|
193 |
|
194 inline TRequestStatus* CStateMachine::ClientStatus() const |
|
195 /** |
|
196 * Gets a request status to complete. |
|
197 * |
|
198 * @return aClientStatus the client request to complete |
|
199 */ |
|
200 { |
|
201 return iClientStatus; |
|
202 } |
|
203 |
|
204 inline HBufC8* CStateMachine::Fragment() const |
|
205 /** |
|
206 * Gets a pointer to an arbitrary data fragment owned by the instance |
|
207 * |
|
208 * @return a pointer to the fragment |
|
209 */ |
|
210 { |
|
211 return iFragment; |
|
212 } |
|
213 |
|
214 inline void CStateMachine::UpdateHistory( TInt aUpdate ) |
|
215 /** |
|
216 * Updates the state machine history whatever the history means in the context |
|
217 * the instance is being used |
|
218 * |
|
219 * @param aUpdate a value to OR with the current history |
|
220 */ |
|
221 { |
|
222 iHistory |= aUpdate; |
|
223 } |
|
224 |
|
225 inline TInt CStateMachine::History() const |
|
226 /** |
|
227 * Gets the state machine history whatever the history means in the context |
|
228 * the instance is being used |
|
229 * |
|
230 * @return the history |
|
231 */ |
|
232 { |
|
233 return iHistory; |
|
234 } |
|
235 |
|
236 inline TInt CStateMachine::LastError() const |
|
237 /** |
|
238 * Gets the last error set when an active event processing leaves or completes |
|
239 with an error |
|
240 * |
|
241 * @return the last error |
|
242 */ |
|
243 { |
|
244 return iLastError; |
|
245 } |
|
246 |
|
247 inline void CStateMachine::SetLastError( TInt aLastError ) |
|
248 /** |
|
249 * Sets the last error |
|
250 * |
|
251 * @param aLastError a value of the last error |
|
252 */ |
|
253 { |
|
254 iLastError = aLastError; |
|
255 } |
|
256 |
|
257 #endif |
|
258 |