|
1 // Copyright (c) 1998-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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members |
|
5 // which accompanies this distribution, and is available |
|
6 // at the URL "http://www.symbianfoundation.org/legal/licencesv10.html". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // |
|
15 |
|
16 #ifdef _DEBUG |
|
17 #undef _NO_SESSION_LOGGING_ |
|
18 #endif |
|
19 |
|
20 #ifndef __MSVAPI_H__ |
|
21 #define __MSVAPI_H__ |
|
22 |
|
23 #include <e32base.h> |
|
24 #include <s32file.h> |
|
25 |
|
26 #ifdef _MSVAPI_DONT_INCLUDE_FLOGGER_ |
|
27 #ifndef _NO_SESSION_LOGGING_ |
|
28 #define _NO_SESSION_LOGGING_ |
|
29 #endif |
|
30 #else |
|
31 #include <flogger.h> |
|
32 #endif |
|
33 |
|
34 #include <msvstd.h> |
|
35 #include <msvstore.h> |
|
36 #include <msvipc.h> |
|
37 #include <msvarray.h> |
|
38 #include <mclient.h> |
|
39 |
|
40 // Forward declarations |
|
41 class CMsvSession; |
|
42 class CMsvEntry; |
|
43 class CBaseMtm; |
|
44 class CMsvClientEntry; |
|
45 class CMsvEntryArray; |
|
46 class CMsvServer; |
|
47 class CMsvServerEntry; |
|
48 |
|
49 // Remove these to remove client logging |
|
50 //#define _NO_SESSION_LOGGING_ |
|
51 #define _NO_SESSION_LOGGING_SERIAL_ |
|
52 |
|
53 // Single export used to start the message server |
|
54 IMPORT_C TInt StartMessageServer(TAny*); |
|
55 |
|
56 // Create Message Server and return a server entry owned by caller |
|
57 // This is all that is required to test server Mtm's |
|
58 IMPORT_C CServer2* CreateMessageServerL(CMsvServerEntry*& aServerEntry); |
|
59 |
|
60 //********************************** |
|
61 // CMsvOperation |
|
62 //********************************** |
|
63 // |
|
64 // Abstract base class for operations controlling asynchronous functions |
|
65 // |
|
66 |
|
67 class CMsvOperation : public CActive |
|
68 /** Defines an interface for use by objects which control asynchronous commands |
|
69 in the messaging system. |
|
70 |
|
71 Such objects are returned by CMsvEntry and User Interface MTM functions that |
|
72 complete asynchronously. The interface allows clients to: |
|
73 |
|
74 1. get progress information about the operation |
|
75 |
|
76 2. cancel the operation |
|
77 |
|
78 3. be signalled asynchronously when the operation completes; a client passes |
|
79 in a TRequestStatus of a suitable active object for this purpose |
|
80 |
|
81 The client only needs to understand the CMsvOperation interface, not the concrete |
|
82 implementation used. |
|
83 |
|
84 Writing derived classes: |
|
85 |
|
86 As the base class interface for User Interface MTMs, CBaseUiMtm, defines functions |
|
87 that return CMsvOperation objects for control of asynchronous operations, |
|
88 implementers of these MTM components are required to provide suitable derived |
|
89 classes. For example, if CBaseUiMtm::EditL() is implemented to provide message |
|
90 editing, a CMsvOperation -derived class would be provided that completes when |
|
91 the editing operation is complete. |
|
92 |
|
93 Concrete derived classes must provide implementations of the pure virtual |
|
94 DoCancel() and RunL() functions defined by CActive. DoCancel() should be provided |
|
95 in the normal way to cancel the operation. RunL() should, in addition to any |
|
96 other required functionality, always end by signalling the client that the |
|
97 operation is complete with a suitable completion code. |
|
98 |
|
99 @publishedAll |
|
100 @released |
|
101 */ |
|
102 { |
|
103 public: |
|
104 IMPORT_C CMsvOperation(CMsvSession& aMsvSession, TInt aPriority, TRequestStatus& aObserverRequestStatus); |
|
105 IMPORT_C ~CMsvOperation(); |
|
106 /** Gets information on the progress of the operation. |
|
107 |
|
108 All operations on local entries share the same progress information format, |
|
109 which defined by TMsvLocalOperationProgress. |
|
110 |
|
111 For MTM-specific operations, progress information can be extracted by calling |
|
112 CBaseUiMtm::GetProgress() or displayed by CBaseUiMtm::DisplayProgressSummary() |
|
113 on the appropriate User Interface MTM. |
|
114 |
|
115 Requirements: |
|
116 |
|
117 Derived classes should implement this function so that the client can check |
|
118 on the progress of the operation. The function should share an understanding |
|
119 of the format of the buffer with the implementations of CBaseUiMtm::GetProgress() |
|
120 and CBaseUiMtm::DisplayProgressSummary() in the User Interface MTM. The arguments |
|
121 of CBaseUiMtm::GetProgress() show some information that should be included |
|
122 where appropriate. |
|
123 |
|
124 @leave KErrNotReady The operation has not yet been started: it has been queued |
|
125 for execution in the Message Server |
|
126 @return Descriptor holding progress information. The maximum buffer size should |
|
127 be KMsvProgressBufferLength (defined in msvipc.h). */ |
|
128 virtual const TDesC8& ProgressL()=0; |
|
129 IMPORT_C virtual const TDesC8& FinalProgress(); |
|
130 IMPORT_C TInt SystemProgress(TMsvSystemProgress& aOutSysProg); |
|
131 IMPORT_C virtual TUid Mtm() const; |
|
132 // |
|
133 inline TMsvOp Id() const; |
|
134 inline TMsvId Service() const; |
|
135 // |
|
136 protected: |
|
137 IMPORT_C TInt Extension_(TUint aExtensionId, TAny *&a0, TAny *a1); |
|
138 |
|
139 protected: |
|
140 /** The ID of the service that is associated with this operation. |
|
141 |
|
142 Usually, the derived class constructor will contain a suitable argument to |
|
143 allow the caller to set this. |
|
144 |
|
145 @see Service() */ |
|
146 TMsvId iService; |
|
147 /** The UID of the MTM associated with the operation. |
|
148 |
|
149 The appropriate value should be set by the derived class constructor. |
|
150 |
|
151 @see Mtm() */ |
|
152 TUid iMtm; |
|
153 /** Request status of the operation observer. |
|
154 |
|
155 This is the aObserverRequestStatus passed in the constructor. */ |
|
156 TRequestStatus& iObserverRequestStatus; |
|
157 /** Message Server session used by object. This is set by the constructor. */ |
|
158 CMsvSession& iMsvSession; |
|
159 |
|
160 private: |
|
161 TMsvOp iId; |
|
162 }; |
|
163 |
|
164 |
|
165 //********************************** |
|
166 // CMsvOperationWait |
|
167 //********************************** |
|
168 // |
|
169 // Allows a synchronous wait on a operation |
|
170 // |
|
171 |
|
172 class CMsvOperationWait: public CActive |
|
173 /** Utility class used to wait until an asynchronous messaging operation |
|
174 has completed. |
|
175 |
|
176 Note that CMsvOperationActiveSchedulerWait is simpler to use, and should be used in |
|
177 preference to this class. |
|
178 |
|
179 To use the class: |
|
180 |
|
181 1. Create a new CMsvOperationWait object |
|
182 |
|
183 2. Call the messaging function that returns the asynchronous operation. |
|
184 The operation observer parameter should be the iStatus word of the CMsvOperationWait |
|
185 object. This means that the CMsvOperationWait object will be signalled when |
|
186 the operation completes. |
|
187 |
|
188 3. Call the CMsvOperationWait object's Start() function. This sets the object |
|
189 to be active. |
|
190 |
|
191 4. Call CActiveScheduler::Start(). This starts a nested active scheduler. The |
|
192 program will then wait until this active scheduler is stopped. The CMsvOperationWait |
|
193 object stops the scheduler when the operation completes, allowing the program to |
|
194 continue. |
|
195 |
|
196 These steps cause the program to wait until the operation completes. |
|
197 |
|
198 @code |
|
199 CMsvOperationWait* waiter=CMsvOperationWait::NewLC(); |
|
200 CMsvOperation* op = function_returning_opLC(waiter->iStatus); |
|
201 waiter->Start(); |
|
202 CActiveScheduler::Start(); |
|
203 CleanupStack::PopAndDestroy(2); // op, waiter |
|
204 @endcode |
|
205 |
|
206 @see CActiveScheduler |
|
207 @publishedAll |
|
208 @released |
|
209 */ |
|
210 { |
|
211 public: |
|
212 IMPORT_C static CMsvOperationWait* NewLC(TInt aPriority=EPriorityStandard); |
|
213 IMPORT_C ~CMsvOperationWait(); |
|
214 IMPORT_C void Start(); |
|
215 protected: |
|
216 CMsvOperationWait(TInt aPriority); |
|
217 void RunL(); |
|
218 void DoCancel(); |
|
219 }; |
|
220 |
|
221 |
|
222 //********************************** |
|
223 // CMsvOperationActiveSchedulerWait |
|
224 //********************************** |
|
225 // |
|
226 // Allows a synchronous wait on a operation using CActiveSchedulerWait class |
|
227 // This class should be used in preference to CMsvOperationWait |
|
228 // DOES NOT require an explicit call to CActiveScheduler::Start()--CMsvOperationActiveSchedulerWait::Start() |
|
229 // effectively encapsulates this functionality |
|
230 // |
|
231 |
|
232 class CMsvOperationActiveSchedulerWait: public CActive |
|
233 /** Utility class used to wait until an asynchronous messaging operation |
|
234 has completed. |
|
235 |
|
236 To use the class: |
|
237 |
|
238 1. Create a new CMsvOperationActiveSchedulerWait object |
|
239 |
|
240 2. Call the messaging function that returns the asynchronous operation. |
|
241 The operation observer parameter should be the iStatus word of the CMsvOperationActiveSchedulerWait |
|
242 object. This means that the CMsvOperationActiveSchedulerWait object will be signalled when |
|
243 the operation completes. |
|
244 |
|
245 3. Call the CMsvOperationActiveSchedulerWait object's Start() function. This sets the object |
|
246 to be active. |
|
247 |
|
248 These steps cause the program to wait until the operation completes. |
|
249 |
|
250 @code |
|
251 CMsvOperationActiveSchedulerWait* waiter=CMsvOperationActiveSchedulerWait::NewLC(); |
|
252 CMsvOperation* op = function_returning_opLC(waiter->iStatus); |
|
253 waiter->Start(); |
|
254 |
|
255 CleanupStack::PopAndDestroy(2); // op, waiter |
|
256 @endcode |
|
257 |
|
258 @publishedAll |
|
259 @released |
|
260 */ |
|
261 { |
|
262 public: |
|
263 IMPORT_C static CMsvOperationActiveSchedulerWait* NewLC(TInt aPriority=EPriorityStandard); |
|
264 IMPORT_C ~CMsvOperationActiveSchedulerWait(); |
|
265 IMPORT_C void Start(); |
|
266 private: |
|
267 CMsvOperationActiveSchedulerWait(TInt aPriority); |
|
268 void RunL(); |
|
269 void DoCancel(); |
|
270 private: |
|
271 CActiveSchedulerWait iActiveSchedulerWait; |
|
272 }; |
|
273 |
|
274 //********************************** |
|
275 // CMsvCompletedOperation |
|
276 //********************************** |
|
277 // |
|
278 // An operation which is already completed on construction |
|
279 // |
|
280 |
|
281 class CMsvCompletedOperation : public CMsvOperation |
|
282 /** Utility to create a messaging operation object for an operation that has already |
|
283 completed. |
|
284 |
|
285 This utility is useful, for example, for writers of MTMs, where the API requires that an |
|
286 asynchronous operation is returned, but where in reality, the operation has performed |
|
287 synchronously. It allows the program to construct an operation object for which |
|
288 the operation is already completed, with the progress information and error code set. |
|
289 |
|
290 @publishedAll |
|
291 @released |
|
292 */ |
|
293 { |
|
294 public: |
|
295 IMPORT_C static CMsvCompletedOperation* NewL(CMsvSession& aMsvSession, TUid aMtm, const TDesC8& aProgress, TMsvId aService, TRequestStatus& aObserverRequestStatus, TInt aErr=KErrNone); |
|
296 IMPORT_C ~CMsvCompletedOperation(); |
|
297 // |
|
298 const TDesC8& ProgressL(); |
|
299 const TDesC8& FinalProgress(); |
|
300 private: |
|
301 CMsvCompletedOperation(CMsvSession& aSession, TRequestStatus& aObserverRequestStatus); |
|
302 void ConstructL(TUid aMtm, TInt aError, const TDesC8& aProgress, TMsvId aService); |
|
303 // from CActive |
|
304 void DoCancel(); |
|
305 void RunL(); |
|
306 // |
|
307 private: |
|
308 HBufC8* iProgress; |
|
309 }; |
|
310 |
|
311 //********************************** |
|
312 // CMsvSendOperation |
|
313 //********************************** |
|
314 // |
|
315 // A send operation which returns a standard progress (used by SendAs2) |
|
316 // |
|
317 |
|
318 /** Utility to create an operation containing a sending operation which may be used |
|
319 to retrieve a standard progress structure. |
|
320 |
|
321 This class is intended to be derived from. The derived class must define the TranslateProgress() |
|
322 member function. This function is responsible for translating the native progress of the given |
|
323 mtm into the standard progress structure, CMsvSendOperation::TSendOperationProgress. |
|
324 |
|
325 @publishedAll |
|
326 @released |
|
327 */ |
|
328 class CMsvSendOperation : public CMsvOperation |
|
329 { |
|
330 public: |
|
331 /** Send progress state. |
|
332 |
|
333 @see TSendOperationProgress |
|
334 */ |
|
335 enum TSendOperationState |
|
336 { |
|
337 ESendStateInPreparation, |
|
338 ESendStateWaitingToSend, |
|
339 ESendStateConnecting, |
|
340 ESendStateSending, |
|
341 ESendStateDone, |
|
342 ESendStateFailed |
|
343 }; |
|
344 /** Send progress. |
|
345 |
|
346 Structure holding send progress. For mtms unable to provide detailed progress |
|
347 information, iProgressMax and iProgress must be zeroed. This will then allow |
|
348 the client to check for this case and display a busy status dialog as opposed to |
|
349 a progress dialog. If the mtm is capable of detailed progress, iProgressMax |
|
350 should be set to the total number of units to be sent and iProgress the number |
|
351 of units sent. |
|
352 |
|
353 @see TSendOperationState |
|
354 */ |
|
355 class TSendOperationProgress |
|
356 { |
|
357 public: |
|
358 TSendOperationState iState; |
|
359 TInt iError; |
|
360 TInt iProgressMax; |
|
361 TInt iProgress; |
|
362 }; |
|
363 |
|
364 public: |
|
365 IMPORT_C virtual ~CMsvSendOperation(); |
|
366 // methods from CMsvOperation |
|
367 IMPORT_C virtual const TDesC8& ProgressL(); |
|
368 IMPORT_C virtual const TDesC8& FinalProgress(); |
|
369 IMPORT_C void Start(CMsvOperation* aOperation); |
|
370 protected: |
|
371 IMPORT_C CMsvSendOperation(CMsvSession& aMsvSession, TRequestStatus& aObserverRequestStatus); |
|
372 private: // methods from CActive |
|
373 IMPORT_C virtual void DoCancel(); |
|
374 IMPORT_C virtual void RunL(); |
|
375 private: |
|
376 /** Translates the progress from sending operation's progress into TSendOperationProgress. |
|
377 |
|
378 This member function must be defined by derived classes. Must not leave. |
|
379 @see TSendOperationProgress |
|
380 @return Descriptor holding progress information. |
|
381 */ |
|
382 virtual const TDesC8& TranslateProgress(const TDesC8& aProgress)=0; |
|
383 void Complete(TInt anError); |
|
384 protected: |
|
385 /** The progress that is associated with this operation. |
|
386 |
|
387 The TranslateProgress defined by derived classes must populate and return |
|
388 this progress structure. |
|
389 @see TranslateProgress() |
|
390 @see TSendOperationProgress */ |
|
391 TPckgBuf<TSendOperationProgress> iProgress; |
|
392 /** The sending operation. |
|
393 |
|
394 Assigned when ConstructL is called |
|
395 */ |
|
396 CMsvOperation* iOperation; |
|
397 }; |
|
398 |
|
399 /** Package buffer for a TSendOperationProgress |
|
400 */ |
|
401 typedef TPckgBuf<CMsvSendOperation::TSendOperationProgress> TMsvSendOperationProgress; |
|
402 |
|
403 |
|
404 //********************************** |
|
405 // MMsvSessionObserver |
|
406 //********************************** |
|
407 // |
|
408 // |
|
409 // |
|
410 |
|
411 class MMsvSessionObserver |
|
412 /** Provides the interface for notification of events from a Message Server session. |
|
413 |
|
414 |
|
415 The types of event are given in the enumeration TMsvSessionEvent. Clients |
|
416 must provide an object that implements the interface, and set it to be notified |
|
417 through CMsvSession::OpenSyncL() or CMsvSession::OpenASyncL(). Additional |
|
418 observers can also be added and removed through CMsvSession. |
|
419 |
|
420 @see CMsvSession::AddObserverL() |
|
421 @see CMsvSession::RemoveObserver() |
|
422 @publishedAll |
|
423 @released |
|
424 */ |
|
425 { |
|
426 public: |
|
427 /** Session event type. |
|
428 |
|
429 @see EMsvMediaUnavailable |
|
430 @see TDriveNumber |
|
431 */ |
|
432 enum TMsvSessionEvent |
|
433 { |
|
434 /** One or more entries have been created. |
|
435 |
|
436 aArg1 is a CMsvEntrySelection of the new entries. aArg2 is the TMsvId of the |
|
437 parent entry. */ |
|
438 EMsvEntriesCreated, |
|
439 /** One or more index entries have been changed. |
|
440 |
|
441 aArg1 is a CMsvEntrySelection of the index entries. aArg2 is the TMsvId of |
|
442 the parent entry. */ |
|
443 EMsvEntriesChanged, |
|
444 /** One or more entries have been deleted. |
|
445 |
|
446 aArg1 is a CMsvEntrySelection containing the IDs of the deleted entries. aArg2 |
|
447 is the TMsvId of the parent entry. */ |
|
448 EMsvEntriesDeleted, |
|
449 /** One or more entries have been moved. |
|
450 |
|
451 aArg1 is a CMsvEntrySelection containing the IDs of the moved entries. aArg2 |
|
452 is the TMsvId of the new parent. aArg3 is the TMsvId of the old parent entry. */ |
|
453 EMsvEntriesMoved, |
|
454 /** A new MTM has been installed. |
|
455 |
|
456 aArg2 points to a TUid for the new MTM. */ |
|
457 EMsvMtmGroupInstalled, |
|
458 /** A MTM has been uninstalled. |
|
459 |
|
460 aArg2 points to a TUid of the removed MTM. */ |
|
461 EMsvMtmGroupDeInstalled, |
|
462 /** Something has happening in the server, but this client was unable to retrieve |
|
463 the information. |
|
464 |
|
465 aArg1 points to the error code. */ |
|
466 EMsvGeneralError, |
|
467 /** The client should immediately close the session with the Message Server. */ |
|
468 EMsvCloseSession, |
|
469 /** Received after a client has used CMsvSession::OpenAsyncL() to create a session. |
|
470 |
|
471 |
|
472 The session can now be used. */ |
|
473 EMsvServerReady, |
|
474 /** Received after a client has used CMsvSession::OpenAsyncL() to create a session. |
|
475 |
|
476 |
|
477 The server could not be started, and aArg1 points to the error code. */ |
|
478 EMsvServerFailedToStart, |
|
479 /** The Message Server index had been corrupted and had to be rebuilt. |
|
480 |
|
481 All local entries are recovered, but all remote entries have been lost. */ |
|
482 EMsvCorruptedIndexRebuilt, |
|
483 /** The Message Server has been terminated. |
|
484 |
|
485 All clients must close their sessions immediately. */ |
|
486 EMsvServerTerminated, |
|
487 /** The Message Server has automatically changed the index location to use the |
|
488 internal disk. |
|
489 |
|
490 aArg1 is a TDriveNumber value that identifies the drive used by the Message |
|
491 Server to hold the index prior to the change. |
|
492 |
|
493 aArg2 is also a TDriveNumber value; it identifies the new drive that the Message |
|
494 Server is using. |
|
495 |
|
496 CMsvEntry contexts either refresh themselves or mark themselves invalid. |
|
497 |
|
498 @see EMsvMediaUnavailable |
|
499 @see TDriveNumber */ |
|
500 EMsvMediaChanged, // I assume the following four are in sequential order |
|
501 /** The media (disk) containing the Message Server index has been removed. |
|
502 |
|
503 aArg1 is a TDriveNumber value that identifies the drive that is no longer |
|
504 available. |
|
505 |
|
506 Future requests may fail with KMsvMediaUnavailable. A EMsvMediaChanged event |
|
507 may be received in the future, as the Message Server switches back to the |
|
508 internal drive. */ |
|
509 EMsvMediaUnavailable, |
|
510 /** The disk containing the Message Store is available again. |
|
511 |
|
512 aArg1 is a TDriveNumber value that identifies the drive that is being used. |
|
513 |
|
514 The Message Server can now operate as normal. No client action is necessary. */ |
|
515 EMsvMediaAvailable, |
|
516 /** An incorrect disk is inserted. |
|
517 |
|
518 aArg1 is a TDriveNumber value that identifies the drive in which the incorrect |
|
519 disk has been inserted. |
|
520 |
|
521 Some requests may fail with KMsvMediaIncorrect. Clients may get an EMsvMediaChanged |
|
522 event in the future telling them that the Message Server has switched back |
|
523 to the internal drive. */ |
|
524 EMsvMediaIncorrect, |
|
525 /** The Message Server has started to rebuild its index after it has been corrupted. |
|
526 |
|
527 @see EMsvCorruptedIndexRebuilt */ |
|
528 EMsvCorruptedIndexRebuilding |
|
529 }; |
|
530 public: |
|
531 /** Indicates an event has occurred. |
|
532 |
|
533 The type of event is indicated by the value of aEvent. The interpretation |
|
534 of the TAny arguments depends on this type. |
|
535 |
|
536 For most event types, the action that is taken, for example, updating the |
|
537 display, is client-specific. All clients though should respond to EMsvCloseSession |
|
538 and EMsvServerTerminated events. |
|
539 |
|
540 @param aEvent Indicates the event type. |
|
541 @param aArg1 Event type-specific argument value |
|
542 @param aArg2 Event type-specific argument value |
|
543 @param aArg3 Event type-specific argument value */ |
|
544 virtual void HandleSessionEventL(TMsvSessionEvent aEvent, TAny* aArg1, TAny* aArg2, TAny* aArg3)=0; |
|
545 }; |
|
546 |
|
547 //********************************** |
|
548 // CMsvSession |
|
549 //********************************** |
|
550 // |
|
551 // |
|
552 // |
|
553 |
|
554 class TCapabilitySet; |
|
555 |
|
556 const TInt KMsvSessionObserverGranularity=4; //??? |
|
557 |
|
558 class CMsvSession: public CActive |
|
559 /** Represents a channel of communication between a client thread (Client-side |
|
560 MTM, User Interface MTM, or message client application) and the Message Server |
|
561 thread. |
|
562 |
|
563 The class provides the means by which clients are notified when important |
|
564 Message Server events occur. |
|
565 |
|
566 Note the following significant groups of functions: |
|
567 |
|
568 Creation functions: a message client application must use OpenSyncL() or OpenASyncL() |
|
569 to create a session object, before it can instantiate any MTM or CMsvEntry |
|
570 object. Only a single session should be created within a thread. As Client-side |
|
571 MTM, User Interface MTM, and CMsvEntry objects are created in the client thread, |
|
572 these use the client session, and do not create their own. Note that to close |
|
573 a session, delete all objects relying on that session, and then the session |
|
574 object itself. |
|
575 |
|
576 Cleanup functions: CMsvSession provides the ability to handle the cleanup |
|
577 of entries in the event of a leave occurring, in a very similar manner to |
|
578 the standard cleanup stack. The difference is that, on a leave, any entries |
|
579 that are on the entry cleanup stack are removed from the Message Server. The |
|
580 implementation uses the standard cleanup stack, so entry push and pop functions |
|
581 should be used in the same order as all other types of push and pop. The functions |
|
582 can be used both by MTM implementations and message client applications. |
|
583 @publishedAll |
|
584 @released |
|
585 */ |
|
586 { |
|
587 public: |
|
588 IMPORT_C static CMsvSession* OpenSyncL(MMsvSessionObserver& aObserver); |
|
589 IMPORT_C static CMsvSession* OpenAsyncL(MMsvSessionObserver& aObserver); |
|
590 IMPORT_C static CMsvSession* OpenAsObserverL(MMsvSessionObserver& aObserver); |
|
591 |
|
592 IMPORT_C static CMsvSession* OpenSyncL(MMsvSessionObserver& aObserver, RFs& aFs); |
|
593 IMPORT_C static CMsvSession* OpenAsyncL(MMsvSessionObserver& aObserver, RFs& aFs); |
|
594 IMPORT_C static CMsvSession* OpenAsObserverL(MMsvSessionObserver& aObserver, RFs& aFs); |
|
595 |
|
596 IMPORT_C static CMsvSession* OpenSyncL(MMsvSessionObserver& aObserver, TInt aPriority); |
|
597 IMPORT_C static CMsvSession* OpenAsyncL(MMsvSessionObserver& aObserver, TInt aPriority); |
|
598 IMPORT_C static CMsvSession* OpenAsObserverL(MMsvSessionObserver& aObserver, TInt aPriority); |
|
599 |
|
600 IMPORT_C static CMsvSession* OpenSyncL(MMsvSessionObserver& aObserver, RFs& aFs, TInt aPriority); |
|
601 IMPORT_C static CMsvSession* OpenAsyncL(MMsvSessionObserver& aObserver, RFs& aFs, TInt aPriority); |
|
602 IMPORT_C static CMsvSession* OpenAsObserverL(MMsvSessionObserver& aObserver, RFs& aFs, TInt aPriority); |
|
603 |
|
604 ~CMsvSession(); |
|
605 // --- Observer functions --- |
|
606 IMPORT_C void AddObserverL(MMsvSessionObserver& aObserver); |
|
607 IMPORT_C void RemoveObserver(MMsvSessionObserver& aObserver); |
|
608 IMPORT_C TInt SetReceiveEntryEvents(TBool aReceive); |
|
609 // --- Utility functions --- |
|
610 IMPORT_C CMsvEntry* GetEntryL(TMsvId aEntId); |
|
611 IMPORT_C TInt GetEntry(TMsvId aId, TMsvId& aService, TMsvEntry& aEntry); |
|
612 |
|
613 IMPORT_C CMsvOperation* TransferCommandL(const CMsvEntrySelection& aSelection, TInt aCommandId, const TDesC8& aParameter, TRequestStatus& aStatus); |
|
614 IMPORT_C void TransferCommandL(const CMsvEntrySelection& aSelection, TInt aCommandId, const TDesC8& aParameter, TDes8& aProgress); |
|
615 IMPORT_C void IncPcSyncCountL(const CMsvEntrySelection& aSelection); |
|
616 IMPORT_C void DecPcSyncCountL(const CMsvEntrySelection& aSelection); |
|
617 IMPORT_C void GetChildIdsL(TMsvId aId, const CMsvEntryFilter& aFilter, CMsvEntrySelection& aSelection); |
|
618 IMPORT_C void ChangeAttributesL(const CMsvEntrySelection& aSelection, TUint aSetAttributes, TUint aClearAttributes); |
|
619 IMPORT_C CMsvOperation* ChangeDriveL(TInt aDrive, TRequestStatus& aStatus); |
|
620 IMPORT_C TInt OutstandingOperationsL(); |
|
621 IMPORT_C CMsvOperation* CopyStoreL(const TDriveUnit& aDrive, TRequestStatus& aStatus); |
|
622 IMPORT_C CMsvOperation* DeleteStoreL(const TDriveUnit& aDrive, TRequestStatus& aStatus); |
|
623 // --- cleanup functions |
|
624 IMPORT_C static void CleanupEntry(TAny* aPtr); |
|
625 IMPORT_C void CleanupEntryPushL(TMsvId aId); |
|
626 IMPORT_C void CleanupEntryPop(TInt aCount=1); |
|
627 |
|
628 IMPORT_C void RemoveEntry(TMsvId aId); |
|
629 /// MTM functions |
|
630 IMPORT_C TInt InstallMtmGroup(const TDesC& aFullName); |
|
631 IMPORT_C TInt DeInstallMtmGroup(const TDesC& aFullName); |
|
632 |
|
633 IMPORT_C TInt StopService(TMsvId aServiceId); |
|
634 IMPORT_C TBool ServiceActive(TMsvId aServiceId); |
|
635 IMPORT_C TInt ServiceProgress(TMsvId aServiceId, TDes8& aProgress); |
|
636 |
|
637 IMPORT_C void CloseMessageServer(); |
|
638 IMPORT_C RFs& FileSession(); |
|
639 |
|
640 IMPORT_C void GetMtmRequiredCapabilitiesL(TUid aMtmTypeUid, TCapabilitySet& aCapSet) const; |
|
641 MMsvStoreManager& StoreManager(); |
|
642 |
|
643 IMPORT_C TBool GetAndClearIndexCorruptFlagL(); |
|
644 IMPORT_C TDriveUnit CurrentDriveL(); |
|
645 IMPORT_C TBool DriveContainsStoreL(TDriveUnit aDrive); |
|
646 IMPORT_C TBool MessageStoreDrivePresentL(); |
|
647 |
|
648 IMPORT_C TInt ServiceAccessPointId(TMsvId aServiceId, TUint32& aAccessPointId); |
|
649 |
|
650 protected: |
|
651 CMsvSession(MMsvSessionObserver& aObserver); |
|
652 CMsvSession(MMsvSessionObserver& aObserver, RFs& aFs); |
|
653 CMsvSession(MMsvSessionObserver& aObserver, TInt aPriority); |
|
654 CMsvSession(MMsvSessionObserver& aObserver, RFs& aFs, TInt aPriority); |
|
655 |
|
656 void ConstructL(TBool aSyncOpening); |
|
657 void ConstructAsObserverL(); |
|
658 // |
|
659 IMPORT_C TInt OperationId(); |
|
660 IMPORT_C RMsvServerSession& Session(); |
|
661 |
|
662 void CheckDrive(); |
|
663 // |
|
664 // from CActive |
|
665 void RunL(); |
|
666 void DoCancel(); |
|
667 TInt RunError(TInt aError); |
|
668 // |
|
669 private: |
|
670 void NotifyAllObserversL(MMsvSessionObserver::TMsvSessionEvent aEvent, TAny* aArg1, TAny* aArg2, TAny* aArg3); |
|
671 void CleanupEntryDelete(); |
|
672 void DoRunL(TMsvNotifBuffer& aBuffer); |
|
673 void HandleNotifyL(); |
|
674 void DoHandleNotifyL(TMsvNotifBuffer& aBuffer); |
|
675 void GetMessageFolderL(); |
|
676 // |
|
677 private: |
|
678 TInt iOperationId; |
|
679 RFs iFs; |
|
680 RMsvServerSession iSession; |
|
681 TMsvNotifBuffer iChange; |
|
682 MMsvSessionObserver& iMainObserver; |
|
683 CArrayPtrFlat<MMsvSessionObserver>* iObservers; |
|
684 CMsvEntrySelection* iCleanupList; |
|
685 TInt iSyncStart; |
|
686 HBufC* iMessageFolder; |
|
687 TDriveNumber iDrive; |
|
688 CMsvEntrySelection* iNotifSelection; |
|
689 TPckgBuf<TUint32> iSequenceBuf; |
|
690 TUint32 iNotifySequence; |
|
691 TBool iReceiveEntryEvents; |
|
692 /** Specifies whether to use the shared file server session */ |
|
693 TBool iUseSharedFs; |
|
694 // |
|
695 #ifndef _NO_SESSION_LOGGING_ |
|
696 void CreateSessionLogL(); |
|
697 void Log(TRefByValue<const TDesC> aFmt, ...); |
|
698 |
|
699 // must be the last data member in the class to preserve BC. |
|
700 mutable RFileLogger iLog; |
|
701 #endif |
|
702 // |
|
703 friend class CSendAs; |
|
704 friend class CMsvEntry; |
|
705 friend class CMsvOperation; |
|
706 friend class CMsvEntryOperation; |
|
707 friend class CObserverRegistry; |
|
708 // |
|
709 }; |
|
710 |
|
711 |
|
712 |
|
713 |
|
714 //********************************** |
|
715 // MMsvEntryObserver |
|
716 //********************************** |
|
717 // |
|
718 // |
|
719 // |
|
720 |
|
721 class MMsvEntryObserver |
|
722 /** Provides the interface for notification of events associated with an entry. |
|
723 |
|
724 The types of event are given in the enumeration TMsvEntryEvent. Clients can |
|
725 provide an object that implements the interface, and set it to be notified |
|
726 through CMsvEntry::AddObserverL(). |
|
727 @publishedAll |
|
728 @released |
|
729 */ |
|
730 { |
|
731 public: |
|
732 /** Defines entry event types. |
|
733 @publishedAll |
|
734 @released |
|
735 */ |
|
736 enum TMsvEntryEvent |
|
737 { |
|
738 /** The entry has been changed, either as a result of a CMsvEntry::ChangeL() or |
|
739 by another client. */ |
|
740 EMsvEntryChanged, |
|
741 /** New children have been created. aArg1 points to a CMsvEntrySelection contain |
|
742 the ID of the new children. */ |
|
743 EMsvNewChildren, |
|
744 /** Children have been deleted. aArg1 points to a CMsvEntrySelection contain the |
|
745 ID of the deleted children. */ |
|
746 EMsvDeletedChildren, |
|
747 /** One or more of the children have been changed. aArg1 points to a CMsvEntrySelection |
|
748 containing the IDs of the changed children. */ |
|
749 EMsvChildrenChanged, |
|
750 /** The entry has been deleted by another client. The context is now invalid. */ |
|
751 EMsvEntryDeleted, |
|
752 /** The context has become invalid. The entry has been changed, but the CMsvEntry |
|
753 was unable to update the context. The context will only become valid by a |
|
754 successful CMsvEntry::SetEntryL() call. aArg1 points to a TInt containing |
|
755 the error code for the invalid context. */ |
|
756 EMsvContextInvalid, |
|
757 /** Some new children have been created, but CMsvEntry was unable to retrieve the |
|
758 data from the Message Server. The children will be correct only after a successful |
|
759 call to CMsvEntry::SetEntryL(). */ |
|
760 EMsvChildrenMissing, |
|
761 /** An error has occurred such that the status of the children is unknown and probably |
|
762 invalid. aArg1 points to a TInt containing the error code for the invalid |
|
763 context */ |
|
764 EMsvChildrenInvalid, |
|
765 /** The current entry has been moved by another client. The CMsvEntry has already |
|
766 been updated to reflect the new parent. */ |
|
767 EMsvEntryMoved}; |
|
768 public: |
|
769 /** Indicates when called by a CMsvEntry object that an event has occurred. |
|
770 |
|
771 The type of event is indicated by the value of aEvent. The interpretation of the aArg1-3 values depends on this type. |
|
772 For most event types, the action that is taken, for example, updating the display, is client-specific. Most clients will |
|
773 need to handle events that make the current context invalid: EMsvContextInvalid and EMsvEntryDeleted. |
|
774 |
|
775 An implementation can leave if an error occurs. The leave is not trapped by the framework, so |
|
776 the error code may be displayed to the user. |
|
777 |
|
778 @param aEvent Indicates the event type. |
|
779 @param aArg1 Event-specific argument value |
|
780 @param aArg2 Event-specific argument value |
|
781 @param aArg3 Event-specific argument value |
|
782 */ |
|
783 virtual void HandleEntryEventL(TMsvEntryEvent aEvent, TAny* aArg1, TAny* aArg2, TAny* aArg3)=0; |
|
784 }; |
|
785 |
|
786 |
|
787 |
|
788 //********************************** |
|
789 // CMsvEntry |
|
790 //********************************** |
|
791 // |
|
792 // |
|
793 // |
|
794 |
|
795 class CMsvEntry: public CBase, public MMsvSessionObserver, public MMsvStoreObserver |
|
796 /** Accesses and acts upon a particular Message Server entry. The current entry |
|
797 that a CMsvEntry object relates is referred to as its context. |
|
798 |
|
799 It may be helpful to consider CMsvEntry functions in two broad groups. The |
|
800 first provides means to access the various types of storage associated with |
|
801 an entry. The second provides a means to discover and access other entries |
|
802 that the entry owns (its children). |
|
803 |
|
804 Message client applications, Client-side MTMs, and User Interface MTMs all |
|
805 commonly use CMsvEntry objects. CMsvEntry objects though represent a lower |
|
806 level of access to an entry than that provided by a Client-side MTM or User |
|
807 Interface MTM. In particular, any MTM-specific functionality, such as address |
|
808 lists or subject fields, must be accessed by a message client application |
|
809 through an MTM inteface. |
|
810 |
|
811 A CMsvEntry object is relatively expensive in RAM usage, as it caches its |
|
812 children, updating them as necessary when notified of changes. They should |
|
813 therefore be created sparingly. |
|
814 |
|
815 Note that Server-side MTMs do not use this class, but a similar one, CMsvServerEntry. |
|
816 |
|
817 @publishedAll |
|
818 @released |
|
819 */ |
|
820 { |
|
821 public: // Public member functions |
|
822 IMPORT_C static CMsvEntry* NewL(CMsvSession& aMsvSession, TMsvId aMsvId, const TMsvSelectionOrdering& aOrdering); |
|
823 IMPORT_C ~CMsvEntry(); |
|
824 // |
|
825 // --- Observer functions --- |
|
826 IMPORT_C void AddObserverL(MMsvEntryObserver& aObserver); |
|
827 IMPORT_C void RemoveObserver(MMsvEntryObserver& aObserver); |
|
828 // |
|
829 // --- Accessor for associated session --- |
|
830 inline CMsvSession& Session(); |
|
831 // |
|
832 // --- Accessors the associated message store --- |
|
833 IMPORT_C CMsvStore* ReadStoreL(); |
|
834 IMPORT_C CMsvStore* EditStoreL(); |
|
835 // |
|
836 // --- Synchronous Current Entry functions --- |
|
837 inline TMsvId EntryId() const; |
|
838 inline const TMsvEntry& Entry() const; |
|
839 inline const TMsvSelectionOrdering& SortType() const; |
|
840 inline TMsvId OwningService() const; |
|
841 IMPORT_C void SetSortTypeL(const TMsvSelectionOrdering& aOrdering); |
|
842 IMPORT_C void SetMtmListL(const CArrayFix<TUid>& aMtmList); |
|
843 IMPORT_C void SetEntryL(TMsvId aId); |
|
844 IMPORT_C void ChangeL(const TMsvEntry& aEntry); |
|
845 IMPORT_C void ChangeL(const TMsvEntry& aEntry, TSecureId aOwnerId); |
|
846 |
|
847 |
|
848 // |
|
849 // --- Asynchronous Current Entry functions --- |
|
850 IMPORT_C CMsvOperation* ChangeL(const TMsvEntry& aEntry, TRequestStatus& aStatus); |
|
851 IMPORT_C CMsvOperation* ChangeL(const TMsvEntry& aEntry, TSecureId aOwnerId, TRequestStatus& aStatus); |
|
852 // |
|
853 // --- Asynchronous Child Entry functions --- |
|
854 IMPORT_C CMsvOperation* CreateL(const TMsvEntry& aEntry, TRequestStatus& aStatus); |
|
855 IMPORT_C CMsvOperation* CreateL(const TMsvEntry& aEntry, TSecureId aOwnerId, TRequestStatus& aStatus); |
|
856 IMPORT_C CMsvOperation* DeleteL(const CMsvEntrySelection& aSelection, TRequestStatus& aStatus); |
|
857 IMPORT_C CMsvOperation* DeleteL(TMsvId aMsvId, TRequestStatus& aStatus); |
|
858 IMPORT_C CMsvOperation* CopyL(const CMsvEntrySelection& aSelection, TMsvId aTargetId, TRequestStatus& aStatus); |
|
859 IMPORT_C CMsvOperation* CopyL(TMsvId aMsvId, TMsvId aTargetId, TRequestStatus& aStatus); |
|
860 IMPORT_C CMsvOperation* MoveL(const CMsvEntrySelection& aSelection, TMsvId aTargetId, TRequestStatus& aStatus); |
|
861 IMPORT_C CMsvOperation* MoveL(TMsvId aMsvId, TMsvId aTargetId, TRequestStatus& aStatus); |
|
862 // |
|
863 // --- Synchronous Child Entry functions --- |
|
864 IMPORT_C CMsvEntrySelection* ChildrenL() const; |
|
865 IMPORT_C CMsvEntrySelection* ChildrenWithServiceL(TMsvId aServiceId) const; |
|
866 IMPORT_C CMsvEntrySelection* ChildrenWithMtmL(TUid aMtm) const; |
|
867 IMPORT_C CMsvEntrySelection* ChildrenWithTypeL(TUid aType) const; |
|
868 inline TInt Count() const; |
|
869 IMPORT_C const TMsvEntry& ChildDataL(TMsvId aId) const; |
|
870 IMPORT_C const TMsvEntry& operator[](TInt aIndex) const; |
|
871 IMPORT_C CMsvEntry* ChildEntryL(TMsvId aId) const; |
|
872 IMPORT_C void MoveL(TMsvId aMsvId, TMsvId aTargetId); |
|
873 IMPORT_C void MoveL(const CMsvEntrySelection& aSelection, TMsvId aTargetId, TMsvLocalOperationProgress& aProgress); |
|
874 IMPORT_C void CopyL(const CMsvEntrySelection& aSelection, TMsvId aTargetId, TMsvLocalOperationProgress& aProgress); |
|
875 IMPORT_C void CopyL(TMsvId aMsvId, TMsvId aTargetId); |
|
876 |
|
877 |
|
878 IMPORT_C void CreateL(TMsvEntry& aEntry); |
|
879 IMPORT_C void CreateL(TMsvEntry& aEntry, TSecureId aOwnerId); |
|
880 IMPORT_C void DeleteL(TMsvId aId); |
|
881 IMPORT_C void DeleteL(const CMsvEntrySelection& aSelection, TMsvLocalOperationProgress& aProgress); |
|
882 IMPORT_C void ChangeAttributesL(const CMsvEntrySelection& aSelection, TUint aSetAttributes, TUint aClearAttributes); |
|
883 // |
|
884 // from MMsvSessionObserver |
|
885 void HandleSessionEventL(TMsvSessionEvent aEvent, TAny* aArg1, TAny* aArg2, TAny* aArg3); |
|
886 // From MMsvStoreObserver |
|
887 void HandleStoreEvent(TMsvStoreEvent aEvent, TMsvId aId); |
|
888 |
|
889 |
|
890 IMPORT_C TBool HasStoreL() const; |
|
891 // |
|
892 /** @internalTechnology */ |
|
893 IMPORT_C void SetEntryNoCheckL(TMsvId aId); |
|
894 // |
|
895 private: // Private members |
|
896 CMsvEntry(CMsvSession& aMsvSession, const TMsvSelectionOrdering& aOrdering); |
|
897 void ConstructL(TMsvId aMsvId); |
|
898 // |
|
899 void NotifyAllObserversL(MMsvEntryObserver::TMsvEntryEvent aEvent, TAny* aArg1, TAny* aArg2, TAny* aArg3); |
|
900 void ContextChangedL(MMsvEntryObserver::TMsvEntryEvent aEvent); |
|
901 void NewChildrenL(const CMsvEntrySelection& aSelection); |
|
902 CMsvEntrySelection* DoGetNewChildrenL(const CMsvEntrySelection& aSelection); |
|
903 void DeletedChildrenL(const CMsvEntrySelection& aSelection); |
|
904 void ChildrenChangedL(const CMsvEntrySelection& aSelection); |
|
905 void CheckNewGrandchildrenL(TMsvId aId); |
|
906 void CheckDeletedGrandchildrenL(TMsvId aId); |
|
907 void NotifyChildChangedL(TMsvId aId); |
|
908 CMsvEntrySelection* DoMakeSelectionL(TMsvId aId); |
|
909 void CheckIfContextMovedL(const CMsvEntrySelection& aSelection); |
|
910 // |
|
911 TBool IsAChild(TMsvId aId) const; |
|
912 TBool AreChildren(const CMsvEntrySelection& aSelection) const; |
|
913 // |
|
914 CMsvOperation* DoDeleteL(const CMsvEntrySelection& aSelection, TRequestStatus& aStatus); |
|
915 CMsvClientEntry* DoGetEntryLC(TMsvId aId, TMsvId& aOwningService); |
|
916 void DoGetChildrenL(); |
|
917 CMsvEntryArray* GetNewSortedListL(const TMsvSelectionOrdering& aOrdering, const CArrayFix<TUid>& aMtmList); |
|
918 void DoSortTypeL(CMsvClientEntry* aContext); |
|
919 void ReplaceChildL(TInt pos, const TMsvEntry& aEntry); |
|
920 void DeleteChild(TInt aPosition); |
|
921 void HandleMediaChangeL(); |
|
922 |
|
923 TInt MoveOneL(TMsvId aMsvId, TMsvId aTargetId); |
|
924 TInt CopyOneL(TMsvId aMsvId, TMsvId aTargetId); |
|
925 TInt DeleteOneL(TMsvId aMsvId); |
|
926 // |
|
927 private: |
|
928 enum TEntryState { EValid, |
|
929 EInvalidChangingContext, |
|
930 EInvalidDeletedContext, |
|
931 EInvalidOldContext, |
|
932 EInvalidMissingChildren}; |
|
933 // |
|
934 #ifndef _NO_SESSION_LOGGING_ |
|
935 void Log(TRefByValue<const TDesC> aFmt, ...); |
|
936 #endif |
|
937 // |
|
938 private: |
|
939 TBool iOberserverAdded; |
|
940 TEntryState iState; |
|
941 CMsvSession& iMsvSession; |
|
942 TMsvSelectionOrdering iOrdering; |
|
943 const TMsvEntry* iEntryPtr; |
|
944 CArrayPtrFlat<MMsvEntryObserver>* iObservers; |
|
945 CArrayPtrFlat<CMsvClientEntry>* iEntries; |
|
946 CMsvEntryArray* iSortedChildren; |
|
947 CMsvStore* iStore; |
|
948 CArrayFixFlat<TUid>* iMtmList; |
|
949 TMsvId iOwningService; |
|
950 TUint32 iNotifySequence; |
|
951 }; |
|
952 |
|
953 //********************************** |
|
954 // MessageServer |
|
955 //********************************** |
|
956 // |
|
957 // |
|
958 // |
|
959 |
|
960 class MessageServer |
|
961 /** Provides various static information functions relating to the Message Server. |
|
962 |
|
963 @see TDriveNumber |
|
964 @publishedAll |
|
965 @released |
|
966 */ |
|
967 { |
|
968 public: |
|
969 IMPORT_C static TVersion Version(); |
|
970 IMPORT_C static TMsvId NullUidValue(); |
|
971 // |
|
972 IMPORT_C static TBool DriveContainsStore(RFs& aFs, TInt aDrive); |
|
973 IMPORT_C static TInt CurrentDriveL(RFs& aFs); |
|
974 IMPORT_C static TBool IsMessageStoreDrivePresentL(RFs& aFs); |
|
975 }; |
|
976 |
|
977 //********************************** |
|
978 // MtmClientUtils |
|
979 //********************************** |
|
980 // |
|
981 // |
|
982 // |
|
983 |
|
984 class McliUtils |
|
985 /** Utility class to simplify getting progress information from a messaging operation object. |
|
986 |
|
987 The functions get and unpack the progress information buffers from an operation object. |
|
988 |
|
989 @publishedAll |
|
990 @released |
|
991 */ |
|
992 { |
|
993 public: |
|
994 IMPORT_C static TMsvLocalOperationProgress GetLocalProgressL(CMsvOperation& aOperation); |
|
995 IMPORT_C static TMsvLocalOperationProgress GetFinalLocalProgress(CMsvOperation& aOperation); |
|
996 IMPORT_C static TInt GetProgressErrorL(CMsvOperation& aOperation); |
|
997 IMPORT_C static TMsvId GetProgressIdL(CMsvOperation& aOperation); |
|
998 }; |
|
999 |
|
1000 #include <msvapi.inl> |
|
1001 |
|
1002 #endif // __MSVAPI_H__ |