Attempt to represent the S^2->S^3 header reorganisation as a series of "hg rename" operations
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".
8 // Initial Contributors:
9 // Nokia Corporation - initial contribution.
23 #include <tnonoperationmtmdata.h>
25 // forward declarations
29 class CDictionaryFileStore;
30 class CInstalledMtmGroup;
31 class CMsvServerEntry;
32 class TMsvSystemProgress;
34 class CBaseServerMtm : public CActive
35 /** Base class for Server-side MTM components. Server-side MTMs provide all message
36 transport functionality for a particular messaging protocol.
38 MTM implementers implement a derived class to provide such functionality for
39 their message protocol. Writers of message client applications are never concerned
40 with this class and its sub-classes, as these are only accessed by the Message
43 Each MTM interprets the generic commands in different ways. For example, a
44 Fax MTM would transmit a fax when asked to copy a fax from a local folder
45 to a fax service. For the same function, an IMAP MTM would create a copy of
46 the message on the remote server and update the message index to show the
47 copy of the message on the remote server. An important initial design task
48 is to the map the functions to the functionality provided by the protocol.
50 Server-side MTM functions are called by the Message Server as a result of
51 a client request that requires some remote operation with the MTM's protocol.
52 The following steps give a simplified view of the usual sequence of events:
54 1. the Message Server instantiates a Server-side MTM object through the factory
57 2. the Message Server calls the appropriate asynchronous function on the Server-side
58 MTM interface, passing a TRequestStatus argument
60 3. the Server-side MTM function typically starts whatever asynchronous communications
61 it requires and returns
63 4. the Server-side MTM is signalled when the asynchronous communications complete,
64 and handles the result
66 5. the Server-side MTM signals the Message Server, through the TRequestStatus
69 6. the Message Server deletes the Server-side MTM object
71 To qualify this somewhat:
73 1. it is up to the Server-side MTM implementation to decide how to translate
74 data back and forth between the formats used by Message Server (index entry,
75 message store, binary files), and that required by the protocol; this is another
78 2. depending on the protocol being used, the communications sequence can be of
79 considerable complexity; typically it requires division into a number of asynchronous
82 3. for greater efficiency where further commands are shortly expected, deletion
83 of the Server-side MTM object can be prevented
85 For asynchronous requests, a Server-side MTM should always complete the TRequestStatus
86 with KErrNone. Any errors should be returned in the progress information.
88 Note the following significant groups of functions:
90 1. Copy and move from remote functions: CopyToLocalL() and MoveToLocalL() are
91 called by the Message Server to get a selection of entries from a remote location.
92 For many protocols, this should be interpreted as message retrieval. For protocols
93 where messages exist on a remote server, this function is typically used to
94 download specific messages, after an initial connection has downloaded message
97 2. Copy and move to remote functions: CopyFromLocalL() and MoveFromLocalL() are
98 called by the Message Server to copy/move a selection of entries to a remote
99 location. For many protocols, this should be interpreted as message sending.
101 3. Copy and move within remote functions: CopyWithinServiceL() and MoveWithinServiceL()
102 are called by the Message Server to copy a selection of entries within a remote
103 service. An example of their use might be for a user rearranging messages
104 within remote folders.
110 IMPORT_C ~CBaseServerMtm();
112 /** Copies a selection of entries from a remote location to a local location. This
113 will only be meaningful for some protocols.
117 Implementations should provide this function if the messaging protocol supports
118 retrieval of remote entries. If this is not supported, implementations should
119 leave with KErrNotSupported.
121 Implementations of this function have three fundamental steps:
123 1. doing the transfer operation using the appropriate communications protocols
125 2. converting protocol-specific data into the three-part storage format (index
126 entry, message store, binary files) required by the Message Server
128 3. updating entries in the Message Server
130 @param aSelection The collection of message index entries for which the copy/moving
132 @param aDestination The entry ID to which the selection is to be copied
133 @param aStatus Asynchronous completion word for the operation
134 @leave KErrNotSupported The Server-side MTM does not support this operation
135 @leave Other leave codes Dependent on implementation */
136 virtual void CopyToLocalL(const CMsvEntrySelection& aSelection,TMsvId aDestination, TRequestStatus& aStatus)=0;
137 /** Copies a selection of entries from a local location to a remote location.
141 Implementations should provide this function if the messaging protocol supports
142 retrieval of remote entries. If this is not supported, implementations should
143 leave with KErrNotSupported.
145 Implementations of this function have three fundamental steps:
147 1. reading entry data
149 2. converting entry data from the Message Server format into that required by
152 3. doing the transfer operation using the appropriate communications protocols
154 @param aSelection The collection of message index entries for which the copy
156 @param aDestination The entry ID of the service by which the entries should
158 @param aStatus Asynchronous completion word for the operation
159 @leave KErrNotSupported The Server-side MTM does not support this operation
160 @leave Other leave codes Dependent on implementation */
161 virtual void CopyFromLocalL(const CMsvEntrySelection& aSelection,TMsvId aDestination, TRequestStatus& aStatus)=0;
162 /** Copies a selection of entries within a remote location.
166 Implementations should provide this function if the messaging protocol supports
167 the ability to copy entries within a remote service. If this is not supported,
168 implementations should leave with KErrNotSupported.
170 @param aSelection The collection of message index entries for which the copy
172 @param aDestination The server entry ID to which the selection is to be copied
173 @param aStatus Asynchronous completion word for the operation
174 @leave KErrNotSupported The Server-side MTM does not support this operation
175 @leave Other leave codes Dependent on implementation */
176 virtual void CopyWithinServiceL(const CMsvEntrySelection& aSelection,TMsvId aDestination, TRequestStatus& aStatus)=0;
177 /** Deletes each entry in the supplied selection when called by the message Server.
178 If any of the entries in the selection is a parent entry, then all its children
179 should also be deleted, recursively to the bottom of the ownership tree.
181 Implementations should provide this function if the messaging protocol supports
182 deletion of remote entries. If this is not supported, implementations should
183 leave with KErrNotSupported.
185 @param aSelection The collection of entries that are to be deleted.
186 @param aStatus Asynchronous completion object.
187 @leave KErrNotSupported The Server-side MTM does not support this operation
188 @leave Other leave codes Dependent on implementation */
189 virtual void DeleteAllL(const CMsvEntrySelection& aSelection, TRequestStatus& aStatus)=0;
190 /** Creates a new remote entry with relevant data when called by the Message Server.
192 Implementations should provide this function if the messaging protocol supports
193 creation of remote entries. If this is not supported, implementations should
194 leave with KErrNotSupported.
196 As with ChangeL(), the Server-side MTM implementation must decide what information
197 in the TMsvEntry is relevant to the remote entry, and translate it appropriately
198 for the specific protocol. Most of the data contained in the TMsvEntry is
199 specific to the Message Server, and would probably have no direct correlation
200 with the protocol's own storage format. For example, for a folder, probably
201 only the name and parent are needed, so if the protocol supports creation
202 of remote folders, the implementation could:
204 1. check for a folder type entry
206 2. get the folder name and parent details from aNewEntry
208 3. initiate a protocol-specific action to create the remote folder
210 @param aNewEntry Data by which to create entry
211 @param aStatus Asynchronous completion word for the operation.
212 @leave KErrNotSupported The Server-side MTM does not support this operation
213 @leave Other leave codes Dependent on implementation */
214 virtual void CreateL(TMsvEntry aNewEntry, TRequestStatus& aStatus)=0;
215 /** Updates a remote entry with relevant data when called by the Message Server.
217 Implementations should provide this function if the messaging protocol supports
218 updating of remote entries. If this is not supported, implementations should
219 leave with KErrNotSupported.
221 The Server-side MTM implementation must decide what information in the TMsvEntry
222 is relevant to the remote entry, and translate it appropriately for the specific
223 protocol. Most of the data contained in the TMsvEntry is specific to the Symbian
224 OS Message Server, and would probably have no direct correlation with the
225 protocol's own storage format. Some entry data may however be useful. For
226 example, if the protocol supports remote renaming of folders, the implementation
229 1. check for a folder type entry
231 2. extract the folder name from aNewEntry.iDetails
233 3. check if the folder name has changed by comparing the new name with iDetails
234 in the index entry currently; if not, complete with KErrNone
236 4. initiate a protocol-specific action to rename the remote folder
238 The implementation should also always update the local Message Server index
239 through CMsvServerEntry::ChangeL().
241 @param aNewEntry Data by which to update entry
242 @param aStatus Asynchronous completion word for the operation.
243 @leave KErrNotSupported The Server-side MTM does not support this operation
244 @leave Other leave codes Dependent on implementation */
245 virtual void ChangeL(TMsvEntry aNewEntry, TRequestStatus& aStatus)=0;
247 /** Executes an MTM-specific operation on a selection of entries when called by
250 The call is made as a response to a client program invoking an MTM-specific
251 operation through CBaseMtm::InvokeSyncFunctionL()/InvokeAsyncFunctionL().
252 The aSelection, aCommand, and aParameter arguments pass the values of the
253 original aSelection, aFunctionId, and aParameter respectively arguments from
254 such a call. The use (if any) of the aSelection and aParameter arguments by
255 the function depends on the command.
257 @param aSelection A selection of message entries on which the command is to
259 @param aCommand The MTM-specific command to be carried out
260 @param aParameter Command-specific parameters
261 @param aStatus Asynchronous completion word for the operation */
262 virtual void StartCommandL(CMsvEntrySelection& aSelection, TInt aCommand, const TDesC8& aParameter, TRequestStatus& aStatus)=0;
264 /** Tests if the Server-side MTM object should be deleted when called by the Message
267 It is useful to stop the MTM being deleted when more commands are expected
268 shortly. This would be the case, for example, after receiving a command to
271 If there are no more commands expected by the Server-side MTM object, then
272 the function should return EFalse, and the Message Server will delete it.
274 @return ETrue: the MTM object should not be deleted EFalse: the MTM object
276 virtual TBool CommandExpected()=0;
278 /** This function is called by the Message Server to get progress information for
279 the current asynchronous operation.
281 The call is made as a response to a client program requesting progress information
282 through CMsvOperation::ProgressL(). The packing format used in the TDesC8
283 is MTM-specific. Only the implementation of the User Interface MTM progress
284 information functions need to understand the format.
286 The progress buffer should have a maximum size of 256 bytes.
288 @return Progress information on current asynchronous operation
289 @see CBaseMtmUi::DisplayProgressSummary()
290 @see CBaseMtmUi::GetProgress() */
291 virtual const TDesC8& Progress()=0;
293 /** Moves a selection of entries from a remote location to a local location.
297 Implementations should provide this function if the messaging protocol supports
298 retrieval of remote entries. If this is not supported, implementations should
299 leave with KErrNotSupported.
301 Implementations of this function have three fundamental steps:
303 1. doing the transfer operation using the appropriate communications protocols
305 2. converting protocol-specific data into the three-part storage format (index
306 entry, message store, binary files) required by the Message Server
308 3. updating entries in the Message Server
310 MoveToLocalL() should differ from CopyToLocalL() in additionally deleting
311 the original remote data.
313 @param aSelection The collection of message index entries for which the moving
315 @param aDestination The entry ID to which the selection is to be copied/moved
316 @param aStatus Asynchronous completion word for the operation
317 @leave KErrNotSupported The Server-side MTM does not support this operation
318 @leave Other leave codes Dependent on implementation */
319 virtual void MoveToLocalL(const CMsvEntrySelection& aSelection,TMsvId aDestination, TRequestStatus& aStatus)=0;
320 /** Moves a selection of entries from a local location to a remote location.
324 Implementations should provide this function if the messaging protocol supports
325 retrieval of remote entries. If this is not supported, implementations should
326 leave with KErrNotSupported.
328 Implementations of this function have three fundamental steps:
330 1. reading entry data
332 2. converting entry data from the Message Server format into that required by
335 3. doing the transfer operation using the appropriate communications protocols
337 The implementation of MoveFromLocalL() should differ from CopyFromLocalL()
338 in additionally deleting the original local data.
340 @param aSelection The collection of message index entries for which the move
342 @param aDestination The entry ID of the service by which the entries should
344 @param aStatus Asynchronous completion word for the operation
345 @leave KErrNotSupported The Server-side MTM does not support this operation
346 @leave Other leave codes Dependent on implementation */
347 virtual void MoveFromLocalL(const CMsvEntrySelection& aSelection,TMsvId aDestination, TRequestStatus& aStatus)=0;
348 /** Moves a selection of entries within a remote location.
352 Implementations should provide this function if the messaging protocol supports
353 the ability to move entries within a remote service. If this is not supported,
354 implementations should leave with KErrNotSupported.
356 The implementation of MoveWithinServiceL() should differ from CopyWithinServiceL()
357 in additionally deleting the original data.
359 @param aSelection The collection of message index entries for which the move
361 @param aDestination The server entry ID to which the selection is to be moved
362 @param aStatus Asynchronous completion word for the operation
363 @leave KErrNotSupported The Server-side MTM does not support this operation
364 @leave Other leave codes Dependent on implementation */
365 virtual void MoveWithinServiceL(const CMsvEntrySelection& aSelection,TMsvId aDestination, TRequestStatus& aStatus)=0;
367 IMPORT_C TInt SystemProgress(TMsvSystemProgress& aOutSysProg);
368 TInt GetNonOperationMtmData(TNonOperationMtmDataType& aMtmDataType, TPtrC8& aResultBuffer);
371 IMPORT_C CBaseServerMtm(CRegisteredMtmDll& aRegisteredMtmDll, CMsvServerEntry* aServerEntry);
372 /** Handles the completion of any asynchronous requests that it makes. It is called
373 from the base class RunL() .
375 Note that any leaves made by this function result in DoComplete() being called
376 with the leave code. */
377 virtual void DoRunL()=0;
378 /** Called by the base class RunL() if DoRunL() leaves.
380 It should be implemented to handle this error. For example, progress information
381 could be updated to reflect the problem.
383 @param aError The leave code given by DoRunL(). */
384 virtual void DoComplete(TInt aError)=0;
386 IMPORT_C TInt Extension_(TUint aExtensionId, TAny *&a0, TAny *a1);
390 IMPORT_C void RunL();
391 IMPORT_C TInt RunError(TInt aError);
394 /** The entry on which to operate. It is set in the constructor.
396 The destructor deletes this member. */
397 CMsvServerEntry* iServerEntry;
399 // Method used for extension: called by non virtual methods that need
400 // to have a polymorphic behaviour.
401 IMPORT_C virtual TAny* GetInterface(TUid aUid);
404 CRegisteredMtmDll& iRegisteredMtmDll;
407 // Extra data member to allow for future extensions
408 TAny* iExtensionData;
412 class CServerMtmDllRegistry : public CMtmDllRegistry
418 friend class CMtmRegistryControl;
420 IMPORT_C static CServerMtmDllRegistry* NewL(RFs& aFs,TTimeIntervalMicroSeconds32 aTimeoutMicroSeconds32=KMsvDefaultTimeoutMicroSeconds32);
421 IMPORT_C ~CServerMtmDllRegistry();
422 IMPORT_C CBaseServerMtm* NewServerMtmL(TUid aMtmTypeUid, CMsvServerEntry* aInitialEntry);
425 CServerMtmDllRegistry(RFs& aFs,TTimeIntervalMicroSeconds32 aTimeoutMicroSeconds32);
428 CBaseServerMtm* NewMtmL(const RLibrary& aLib, CMsvServerEntry* aServerEntry, CRegisteredMtmDll& aReg) const;
432 class CInstalledMtmGroupArray : public CArrayPtrFlat<CInstalledMtmGroup>
439 CInstalledMtmGroupArray();
440 ~CInstalledMtmGroupArray();
441 void AddInstalledMtmGroupL(CInstalledMtmGroup* aInstalledMtmGroup);
444 //**********************************
446 //**********************************
449 //**********************************
450 // CMtmRegistryControl
451 //**********************************
453 class CMtmRegistryControl : public CBase, public MRegisteredMtmDllObserver
460 IMPORT_C static CMtmRegistryControl* NewL(RFs& anFs,CServerMtmDllRegistry& aServerMtmDllRegistry);
461 IMPORT_C ~CMtmRegistryControl();
463 IMPORT_C TInt InstallMtmGroup(const TDesC& aFullName,TUid& aMtmTypeUid);
464 IMPORT_C TInt FullNameToMtmTypeUid(const TDesC& aFullName,TUid& aMtmTypeUid) const;
465 IMPORT_C TInt DeInstallMtmGroup(TUid aMtmTypeUid); // returns error on storing registry
467 IMPORT_C TInt UseMtmGroup(TUid aMtmTypeUid);
468 IMPORT_C TInt ReleaseMtmGroup(TUid aMtmTypeUid);
469 IMPORT_C TBool IsInUse(TUid aMtmTypeUid) const;
471 IMPORT_C TInt FillRegisteredMtmDllArray(TUid aMtmDllTypeUid,CRegisteredMtmDllArray& aRegisteredMtmDllArray,TTimeIntervalMicroSeconds32 aTimeoutMicroSeconds32=0); // Fill array with Dlls whose second uid is aMtmDllTypeUid
472 IMPORT_C CMtmGroupData* GetMtmGroupDataL(TUid aMtmTypeUid) const;
473 const CMtmGroupData& GetMtmGroupDataReferenceL(TUid aMtmTypeUid) const;
475 IMPORT_C void StoreRegistryL() const;
476 IMPORT_C void RestoreRegistryL();
478 IMPORT_C void InternalizeL(RReadStream& aStream);
479 IMPORT_C void ExternalizeL(RWriteStream& aStream) const;
482 CMtmRegistryControl(RFs& anFs,CServerMtmDllRegistry& aServerMtmDllRegistry);
484 TInt MtmTypeUidToIndex(TUid aMtmTypeUid) const;
485 TInt UidTypeToIndex(TUidType aUidType) const;
486 void DoInstallMtmGroupL(const TDesC& aFullName,TUid& aMtmTypeUid);
487 CMtmGroupData* ReadDataFileStoreL(const TDesC& aFullName) const;
488 void DoDeInstallMtmGroupL(TUid aMtmTypeUid);
489 void DoInternalizeL(RReadStream& aStream);
490 void AddInstalledMtmGroupL(CInstalledMtmGroup* aInstalledMtmGroup);
491 void RemoveInstalledMtmGroup(TUid aMtmTypeUid);
492 TBool IsResFileL(const TDesC& aFullName) const;
493 TUid DoFindMtmTypeUidL(const TDesC& aFullName) const;
495 CMtmGroupData *LoadMTMFileL(const TDesC& aFullName, TUid &aUid);
496 CMtmGroupData *LoadDatFileL(const TDesC& aFullName, TUid &aUid);
497 CMtmGroupData *LoadResFileL(const TDesC& aFullName, TUid &aUid);
500 CInstalledMtmGroupArray iInstalledMtmGroupArray;
501 CServerMtmDllRegistry& iServerMtmDllRegistry;