epoc32/include/mw/mtsr.h
author William Roberts <williamr@symbian.org>
Wed, 31 Mar 2010 12:27:01 +0100
branchSymbian2
changeset 3 e1b950c65cb4
parent 2 epoc32/include/mtsr.h@2fe1408b6811
child 4 837f303aceeb
permissions -rw-r--r--
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".
     7 //
     8 // Initial Contributors:
     9 // Nokia Corporation - initial contribution.
    10 //
    11 // Contributors:
    12 //
    13 // Description:
    14 //
    15 
    16 #ifndef __MTSR_H__
    17 #define __MTSR_H__
    18 
    19 #include <e32base.h>
    20 #include <badesca.h>
    21 #include <msvstd.h>
    22 #include <msvreg.h>
    23 #include <tnonoperationmtmdata.h>
    24 
    25 // forward declarations
    26 class RWriteStream;
    27 class RReadStream;
    28 class RFs;
    29 class CDictionaryFileStore;
    30 class CInstalledMtmGroup;
    31 class CMsvServerEntry;
    32 class TMsvSystemProgress;
    33 
    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. 
    37 
    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 
    41 Server. 
    42 
    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.
    49 
    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:
    53 
    54 1. the Message Server instantiates a Server-side MTM object through the factory 
    55 function
    56 
    57 2. the Message Server calls the appropriate asynchronous function on the Server-side 
    58 MTM interface, passing a TRequestStatus argument
    59 
    60 3. the Server-side MTM function typically starts whatever asynchronous communications 
    61 it requires and returns
    62 
    63 4. the Server-side MTM is signalled when the asynchronous communications complete, 
    64 and handles the result
    65 
    66 5. the Server-side MTM signals the Message Server, through the TRequestStatus 
    67 passed earlier
    68 
    69 6. the Message Server deletes the Server-side MTM object
    70 
    71 To qualify this somewhat:
    72 
    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 
    76 important design task 
    77 
    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 
    80 steps
    81 
    82 3. for greater efficiency where further commands are shortly expected, deletion 
    83 of the Server-side MTM object can be prevented
    84 
    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.
    87 
    88 Note the following significant groups of functions:
    89 
    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 
    95 headers. 
    96 
    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. 
   100 
   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. 
   105 @publishedAll
   106 @released
   107 */
   108 	{
   109 public:
   110 	IMPORT_C ~CBaseServerMtm();
   111 	//
   112 	/** Copies a selection of entries from a remote location to a local location. This 
   113 	will only be meaningful for some protocols.
   114 	
   115 	Requirements:
   116 	
   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. 
   120 	
   121 	Implementations of this function have three fundamental steps:
   122 	
   123 	1. doing the transfer operation using the appropriate communications protocols 
   124 	
   125 	2. converting protocol-specific data into the three-part storage format (index 
   126 	entry, message store, binary files) required by the Message Server
   127 	
   128 	3. updating entries in the Message Server
   129 	
   130 	@param aSelection The collection of message index entries for which the copy/moving 
   131 	is required. 
   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. 
   138 	
   139 	Requirements:
   140 	
   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. 
   144 	
   145 	Implementations of this function have three fundamental steps:
   146 	
   147 	1. reading entry data
   148 	
   149 	2. converting entry data from the Message Server format into that required by 
   150 	the protocol
   151 	
   152 	3. doing the transfer operation using the appropriate communications protocols 
   153 	
   154 	@param aSelection The collection of message index entries for which the copy 
   155 	is required 
   156 	@param aDestination The entry ID of the service by which the entries should 
   157 	be transferred 
   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. 
   163 	
   164 	Requirements:
   165 	
   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. 
   169 	
   170 	@param aSelection The collection of message index entries for which the copy 
   171 	is required 
   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.
   180 	
   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. 
   184 	
   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.
   191 	 
   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.
   195 	
   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:
   203 	
   204 	1. check for a folder type entry
   205 	
   206 	2. get the folder name and parent details from aNewEntry
   207 	
   208 	3. initiate a protocol-specific action to create the remote folder
   209 	
   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.
   216 	 
   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. 
   220 	
   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 
   227 	could:
   228 	
   229 	1. check for a folder type entry
   230 	
   231 	2. extract the folder name from aNewEntry.iDetails
   232 	
   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
   235 	
   236 	4. initiate a protocol-specific action to rename the remote folder
   237 	
   238 	The implementation should also always update the local Message Server index 
   239 	through CMsvServerEntry::ChangeL().
   240 	
   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;
   246 	//
   247 	/** Executes an MTM-specific operation on a selection of entries when called by 
   248 	the Message Server.
   249 	
   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.
   256 	
   257 	@param aSelection A selection of message entries on which the command is to 
   258 	be executed 
   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;
   263 	//
   264 	/** Tests if the Server-side MTM object should be deleted when called by the Message 
   265 	Server
   266 	
   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 
   269 	go online. 
   270 	
   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.
   273 	
   274 	@return ETrue: the MTM object should not be deleted EFalse: the MTM object 
   275 	can be deleted */
   276 	virtual TBool CommandExpected()=0;
   277 	//
   278 	/** This function is called by the Message Server to get progress information for 
   279 	the current asynchronous operation. 
   280 	
   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.
   285 	
   286 	The progress buffer should have a maximum size of 256 bytes.
   287 	
   288 	@return Progress information on current asynchronous operation 
   289 	@see CBaseMtmUi::DisplayProgressSummary()
   290 	@see CBaseMtmUi::GetProgress() */
   291 	virtual const TDesC8& Progress()=0;
   292 	//
   293 	/** Moves a selection of entries from a remote location to a local location. 
   294 	
   295 	Requirements:
   296 	
   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. 
   300 	
   301 	Implementations of this function have three fundamental steps:
   302 	
   303 	1. doing the transfer operation using the appropriate communications protocols 
   304 	
   305 	2. converting protocol-specific data into the three-part storage format (index 
   306 	entry, message store, binary files) required by the Message Server
   307 	
   308 	3. updating entries in the Message Server
   309 	
   310 	MoveToLocalL() should differ from CopyToLocalL() in additionally deleting 
   311 	the original remote data. 
   312 	
   313 	@param aSelection The collection of message index entries for which the moving 
   314 	is required. 
   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. 
   321 	
   322 	Requirements:
   323 	
   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. 
   327 	
   328 	Implementations of this function have three fundamental steps:
   329 	
   330 	1. reading entry data
   331 	
   332 	2. converting entry data from the Message Server format into that required by 
   333 	the protocol
   334 	
   335 	3. doing the transfer operation using the appropriate communications protocols 
   336 	
   337 	The implementation of MoveFromLocalL() should differ from CopyFromLocalL() 
   338 	in additionally deleting the original local data. 
   339 	
   340 	@param aSelection The collection of message index entries for which the move 
   341 	is required 
   342 	@param aDestination The entry ID of the service by which the entries should 
   343 	be transferred 
   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. 
   349 	
   350 	Requirements:
   351 	
   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. 
   355 	
   356 	The implementation of MoveWithinServiceL() should differ from CopyWithinServiceL() 
   357 	in additionally deleting the original data. 
   358 	
   359 	@param aSelection The collection of message index entries for which the move 
   360 	is required 
   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;
   366 
   367 	IMPORT_C TInt SystemProgress(TMsvSystemProgress& aOutSysProg);
   368 	TInt GetNonOperationMtmData(TNonOperationMtmDataType& aMtmDataType, TPtrC8& aResultBuffer);
   369 
   370 protected:
   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() .
   374 	
   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. 
   379 	
   380 	It should be implemented to handle this error. For example, progress information 
   381 	could be updated to reflect the problem.
   382 	
   383 	@param aError The leave code given by DoRunL(). */
   384 	virtual void DoComplete(TInt aError)=0;
   385 	//
   386 	IMPORT_C TInt Extension_(TUint aExtensionId, TAny *&a0, TAny *a1);
   387 	//
   388 private:
   389 	// from CActive
   390 	IMPORT_C void RunL();
   391 	IMPORT_C TInt RunError(TInt aError);
   392 	//
   393 protected:
   394 	/** The entry on which to operate. It is set in the constructor.
   395 	
   396 	The destructor deletes this member. */
   397 	CMsvServerEntry* iServerEntry;
   398 	
   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);
   402 	//
   403 private:
   404 	CRegisteredMtmDll& iRegisteredMtmDll;
   405 
   406 private:
   407 	// Extra data member to allow for future extensions
   408 	TAny* iExtensionData;
   409 	};
   410 
   411 
   412 class CServerMtmDllRegistry : public CMtmDllRegistry
   413 /**
   414 @publishedAll
   415 @released
   416 */
   417 	{
   418 friend class CMtmRegistryControl;
   419 public:
   420 	IMPORT_C static CServerMtmDllRegistry* NewL(RFs& aFs,TTimeIntervalMicroSeconds32 aTimeoutMicroSeconds32=KMsvDefaultTimeoutMicroSeconds32);
   421 	IMPORT_C ~CServerMtmDllRegistry();
   422 	IMPORT_C CBaseServerMtm* NewServerMtmL(TUid aMtmTypeUid, CMsvServerEntry* aInitialEntry);
   423 	//
   424 protected:
   425 	CServerMtmDllRegistry(RFs& aFs,TTimeIntervalMicroSeconds32 aTimeoutMicroSeconds32);
   426 	//
   427 private:
   428 	CBaseServerMtm* NewMtmL(const RLibrary& aLib, CMsvServerEntry* aServerEntry, CRegisteredMtmDll& aReg) const;
   429 	};
   430 
   431 
   432 class CInstalledMtmGroupArray : public CArrayPtrFlat<CInstalledMtmGroup>
   433 /**
   434 @internalComponent
   435 @released
   436 */
   437 	{
   438 public:
   439 	CInstalledMtmGroupArray();
   440 	~CInstalledMtmGroupArray();
   441 	void AddInstalledMtmGroupL(CInstalledMtmGroup* aInstalledMtmGroup);
   442 	};
   443 
   444 //**********************************
   445 // CMsvMtmCache
   446 //**********************************
   447 
   448 
   449 //**********************************
   450 // CMtmRegistryControl
   451 //**********************************
   452 
   453 class CMtmRegistryControl : public CBase, public MRegisteredMtmDllObserver
   454 /**
   455 @publishedAll
   456 @released
   457 */
   458 	{
   459 public:
   460 	IMPORT_C static CMtmRegistryControl* NewL(RFs& anFs,CServerMtmDllRegistry& aServerMtmDllRegistry);
   461 	IMPORT_C ~CMtmRegistryControl();
   462 
   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
   466 
   467 	IMPORT_C TInt UseMtmGroup(TUid aMtmTypeUid);
   468 	IMPORT_C TInt ReleaseMtmGroup(TUid aMtmTypeUid);  
   469 	IMPORT_C TBool IsInUse(TUid aMtmTypeUid) const;
   470 
   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;  
   474 
   475 	IMPORT_C void StoreRegistryL() const;
   476 	IMPORT_C void RestoreRegistryL();
   477 
   478 	IMPORT_C void InternalizeL(RReadStream& aStream);
   479 	IMPORT_C void ExternalizeL(RWriteStream& aStream) const;
   480 
   481 private:
   482 	CMtmRegistryControl(RFs& anFs,CServerMtmDllRegistry& aServerMtmDllRegistry);
   483 	void ConstructL();
   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;
   494 	
   495 	CMtmGroupData *LoadMTMFileL(const TDesC& aFullName, TUid &aUid);
   496 	CMtmGroupData *LoadDatFileL(const TDesC& aFullName, TUid &aUid);
   497 	CMtmGroupData *LoadResFileL(const TDesC& aFullName, TUid &aUid);	
   498 private:
   499 	RFs& iFs;
   500 	CInstalledMtmGroupArray iInstalledMtmGroupArray;
   501 	CServerMtmDllRegistry& iServerMtmDllRegistry;
   502 	};
   503 
   504 #endif	// __MTSR_H__