--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/messagingfw/msgsrvnstore/server/inc/MTSR.H Mon Jan 18 20:36:02 2010 +0200
@@ -0,0 +1,509 @@
+// Copyright (c) 1998-2009 Nokia Corporation and/or its subsidiary(-ies).
+// All rights reserved.
+// This component and the accompanying materials are made available
+// under the terms of "Eclipse Public License v1.0"
+// which accompanies this distribution, and is available
+// at the URL "http://www.eclipse.org/legal/epl-v10.html".
+//
+// Initial Contributors:
+// Nokia Corporation - initial contribution.
+//
+// Contributors:
+//
+// Description:
+// MTSR.H
+//
+/**
+ @file
+ @publishedAll
+ @released
+*/
+#ifndef __MTSR_H__
+#define __MTSR_H__
+
+#include <e32base.h>
+#include <badesca.h>
+#include <msvstd.h>
+#include <msvreg.h>
+#include <tnonoperationmtmdata.h>
+#ifndef SYMBIAN_ENABLE_SPLIT_HEADERS
+#include "cinstalledmtmgroup.h"
+#endif
+
+// forward declarations
+class RWriteStream;
+class RReadStream;
+class RFs;
+class CDictionaryFileStore;
+class CInstalledMtmGroup;
+class CMsvServerEntry;
+class TMsvSystemProgress;
+class CInstalledMtmGroupArray;
+
+#if (defined SYMBIAN_USER_PROMPT_SERVICE)
+const TUint KUIDMsgClientThreadInfo = 0x10283090;
+#endif
+
+class CBaseServerMtm : public CActive
+/** Base class for Server-side MTM components. Server-side MTMs provide all message
+transport functionality for a particular messaging protocol.
+
+MTM implementers implement a derived class to provide such functionality for
+their message protocol. Writers of message client applications are never concerned
+with this class and its sub-classes, as these are only accessed by the Message
+Server.
+
+Each MTM interprets the generic commands in different ways. For example, a
+Fax MTM would transmit a fax when asked to copy a fax from a local folder
+to a fax service. For the same function, an IMAP MTM would create a copy of
+the message on the remote server and update the message index to show the
+copy of the message on the remote server. An important initial design task
+is to the map the functions to the functionality provided by the protocol.
+
+Server-side MTM functions are called by the Message Server as a result of
+a client request that requires some remote operation with the MTM's protocol.
+The following steps give a simplified view of the usual sequence of events:
+
+1. the Message Server instantiates a Server-side MTM object through the factory
+function
+
+2. the Message Server calls the appropriate asynchronous function on the Server-side
+MTM interface, passing a TRequestStatus argument
+
+3. the Server-side MTM function typically starts whatever asynchronous communications
+it requires and returns
+
+4. the Server-side MTM is signalled when the asynchronous communications complete,
+and handles the result
+
+5. the Server-side MTM signals the Message Server, through the TRequestStatus
+passed earlier
+
+6. the Message Server deletes the Server-side MTM object
+
+To qualify this somewhat:
+
+1. it is up to the Server-side MTM implementation to decide how to translate
+data back and forth between the formats used by Message Server (index entry,
+message store, binary files), and that required by the protocol; this is another
+important design task
+
+2. depending on the protocol being used, the communications sequence can be of
+considerable complexity; typically it requires division into a number of asynchronous
+steps
+
+3. for greater efficiency where further commands are shortly expected, deletion
+of the Server-side MTM object can be prevented
+
+For asynchronous requests, a Server-side MTM should always complete the TRequestStatus
+with KErrNone. Any errors should be returned in the progress information.
+
+Note the following significant groups of functions:
+
+1. Copy and move from remote functions: CopyToLocalL() and MoveToLocalL() are
+called by the Message Server to get a selection of entries from a remote location.
+For many protocols, this should be interpreted as message retrieval. For protocols
+where messages exist on a remote server, this function is typically used to
+download specific messages, after an initial connection has downloaded message
+headers.
+
+2. Copy and move to remote functions: CopyFromLocalL() and MoveFromLocalL() are
+called by the Message Server to copy/move a selection of entries to a remote
+location. For many protocols, this should be interpreted as message sending.
+
+3. Copy and move within remote functions: CopyWithinServiceL() and MoveWithinServiceL()
+are called by the Message Server to copy a selection of entries within a remote
+service. An example of their use might be for a user rearranging messages
+within remote folders.
+@publishedAll
+@released
+*/
+ {
+public:
+ IMPORT_C ~CBaseServerMtm();
+ //
+ /** Copies a selection of entries from a remote location to a local location. This
+ will only be meaningful for some protocols.
+
+ Requirements:
+
+ Implementations should provide this function if the messaging protocol supports
+ retrieval of remote entries. If this is not supported, implementations should
+ leave with KErrNotSupported.
+
+ Implementations of this function have three fundamental steps:
+
+ 1. doing the transfer operation using the appropriate communications protocols
+
+ 2. converting protocol-specific data into the three-part storage format (index
+ entry, message store, binary files) required by the Message Server
+
+ 3. updating entries in the Message Server
+
+ @param aSelection The collection of message index entries for which the copy/moving
+ is required.
+ @param aDestination The entry ID to which the selection is to be copied
+ @param aStatus Asynchronous completion word for the operation
+ @leave KErrNotSupported The Server-side MTM does not support this operation
+ @leave Other leave codes Dependent on implementation */
+ virtual void CopyToLocalL(const CMsvEntrySelection& aSelection,TMsvId aDestination, TRequestStatus& aStatus)=0;
+ /** Copies a selection of entries from a local location to a remote location.
+
+ Requirements:
+
+ Implementations should provide this function if the messaging protocol supports
+ retrieval of remote entries. If this is not supported, implementations should
+ leave with KErrNotSupported.
+
+ Implementations of this function have three fundamental steps:
+
+ 1. reading entry data
+
+ 2. converting entry data from the Message Server format into that required by
+ the protocol
+
+ 3. doing the transfer operation using the appropriate communications protocols
+
+ @param aSelection The collection of message index entries for which the copy
+ is required
+ @param aDestination The entry ID of the service by which the entries should
+ be transferred
+ @param aStatus Asynchronous completion word for the operation
+ @leave KErrNotSupported The Server-side MTM does not support this operation
+ @leave Other leave codes Dependent on implementation */
+ virtual void CopyFromLocalL(const CMsvEntrySelection& aSelection,TMsvId aDestination, TRequestStatus& aStatus)=0;
+ /** Copies a selection of entries within a remote location.
+
+ Requirements:
+
+ Implementations should provide this function if the messaging protocol supports
+ the ability to copy entries within a remote service. If this is not supported,
+ implementations should leave with KErrNotSupported.
+
+ @param aSelection The collection of message index entries for which the copy
+ is required
+ @param aDestination The server entry ID to which the selection is to be copied
+ @param aStatus Asynchronous completion word for the operation
+ @leave KErrNotSupported The Server-side MTM does not support this operation
+ @leave Other leave codes Dependent on implementation */
+ virtual void CopyWithinServiceL(const CMsvEntrySelection& aSelection,TMsvId aDestination, TRequestStatus& aStatus)=0;
+ /** Deletes each entry in the supplied selection when called by the message Server.
+ If any of the entries in the selection is a parent entry, then all its children
+ should also be deleted, recursively to the bottom of the ownership tree.
+
+ Implementations should provide this function if the messaging protocol supports
+ deletion of remote entries. If this is not supported, implementations should
+ leave with KErrNotSupported.
+
+ @param aSelection The collection of entries that are to be deleted.
+ @param aStatus Asynchronous completion object.
+ @leave KErrNotSupported The Server-side MTM does not support this operation
+ @leave Other leave codes Dependent on implementation */
+ virtual void DeleteAllL(const CMsvEntrySelection& aSelection, TRequestStatus& aStatus)=0;
+ /** Creates a new remote entry with relevant data when called by the Message Server.
+
+ Implementations should provide this function if the messaging protocol supports
+ creation of remote entries. If this is not supported, implementations should
+ leave with KErrNotSupported.
+
+ As with ChangeL(), the Server-side MTM implementation must decide what information
+ in the TMsvEntry is relevant to the remote entry, and translate it appropriately
+ for the specific protocol. Most of the data contained in the TMsvEntry is
+ specific to the Message Server, and would probably have no direct correlation
+ with the protocol's own storage format. For example, for a folder, probably
+ only the name and parent are needed, so if the protocol supports creation
+ of remote folders, the implementation could:
+
+ 1. check for a folder type entry
+
+ 2. get the folder name and parent details from aNewEntry
+
+ 3. initiate a protocol-specific action to create the remote folder
+
+ @param aNewEntry Data by which to create entry
+ @param aStatus Asynchronous completion word for the operation.
+ @leave KErrNotSupported The Server-side MTM does not support this operation
+ @leave Other leave codes Dependent on implementation */
+ virtual void CreateL(TMsvEntry aNewEntry, TRequestStatus& aStatus)=0;
+ /** Updates a remote entry with relevant data when called by the Message Server.
+
+ Implementations should provide this function if the messaging protocol supports
+ updating of remote entries. If this is not supported, implementations should
+ leave with KErrNotSupported.
+
+ The Server-side MTM implementation must decide what information in the TMsvEntry
+ is relevant to the remote entry, and translate it appropriately for the specific
+ protocol. Most of the data contained in the TMsvEntry is specific to the Symbian
+ OS Message Server, and would probably have no direct correlation with the
+ protocol's own storage format. Some entry data may however be useful. For
+ example, if the protocol supports remote renaming of folders, the implementation
+ could:
+
+ 1. check for a folder type entry
+
+ 2. extract the folder name from aNewEntry.iDetails
+
+ 3. check if the folder name has changed by comparing the new name with iDetails
+ in the index entry currently; if not, complete with KErrNone
+
+ 4. initiate a protocol-specific action to rename the remote folder
+
+ The implementation should also always update the local Message Server index
+ through CMsvServerEntry::ChangeL().
+
+ @param aNewEntry Data by which to update entry
+ @param aStatus Asynchronous completion word for the operation.
+ @leave KErrNotSupported The Server-side MTM does not support this operation
+ @leave Other leave codes Dependent on implementation */
+ virtual void ChangeL(TMsvEntry aNewEntry, TRequestStatus& aStatus)=0;
+ //
+ /** Executes an MTM-specific operation on a selection of entries when called by
+ the Message Server.
+
+ The call is made as a response to a client program invoking an MTM-specific
+ operation through CBaseMtm::InvokeSyncFunctionL()/InvokeAsyncFunctionL().
+ The aSelection, aCommand, and aParameter arguments pass the values of the
+ original aSelection, aFunctionId, and aParameter respectively arguments from
+ such a call. The use (if any) of the aSelection and aParameter arguments by
+ the function depends on the command.
+
+ @param aSelection A selection of message entries on which the command is to
+ be executed
+ @param aCommand The MTM-specific command to be carried out
+ @param aParameter Command-specific parameters
+ @param aStatus Asynchronous completion word for the operation */
+ virtual void StartCommandL(CMsvEntrySelection& aSelection, TInt aCommand, const TDesC8& aParameter, TRequestStatus& aStatus)=0;
+ //
+ /** Tests if the Server-side MTM object should be deleted when called by the Message
+ Server
+
+ It is useful to stop the MTM being deleted when more commands are expected
+ shortly. This would be the case, for example, after receiving a command to
+ go online.
+
+ If there are no more commands expected by the Server-side MTM object, then
+ the function should return EFalse, and the Message Server will delete it.
+
+ @return ETrue: the MTM object should not be deleted EFalse: the MTM object
+ can be deleted */
+ virtual TBool CommandExpected()=0;
+ //
+ /** This function is called by the Message Server to get progress information for
+ the current asynchronous operation.
+
+ The call is made as a response to a client program requesting progress information
+ through CMsvOperation::ProgressL(). The packing format used in the TDesC8
+ is MTM-specific. Only the implementation of the User Interface MTM progress
+ information functions need to understand the format.
+
+ The progress buffer should have a maximum size of 256 bytes.
+
+ @return Progress information on current asynchronous operation
+ @see CBaseMtmUi::DisplayProgressSummary()
+ @see CBaseMtmUi::GetProgress() */
+ virtual const TDesC8& Progress()=0;
+ //
+ /** Moves a selection of entries from a remote location to a local location.
+
+ Requirements:
+
+ Implementations should provide this function if the messaging protocol supports
+ retrieval of remote entries. If this is not supported, implementations should
+ leave with KErrNotSupported.
+
+ Implementations of this function have three fundamental steps:
+
+ 1. doing the transfer operation using the appropriate communications protocols
+
+ 2. converting protocol-specific data into the three-part storage format (index
+ entry, message store, binary files) required by the Message Server
+
+ 3. updating entries in the Message Server
+
+ MoveToLocalL() should differ from CopyToLocalL() in additionally deleting
+ the original remote data.
+
+ @param aSelection The collection of message index entries for which the moving
+ is required.
+ @param aDestination The entry ID to which the selection is to be copied/moved
+ @param aStatus Asynchronous completion word for the operation
+ @leave KErrNotSupported The Server-side MTM does not support this operation
+ @leave Other leave codes Dependent on implementation */
+ virtual void MoveToLocalL(const CMsvEntrySelection& aSelection,TMsvId aDestination, TRequestStatus& aStatus)=0;
+ /** Moves a selection of entries from a local location to a remote location.
+
+ Requirements:
+
+ Implementations should provide this function if the messaging protocol supports
+ retrieval of remote entries. If this is not supported, implementations should
+ leave with KErrNotSupported.
+
+ Implementations of this function have three fundamental steps:
+
+ 1. reading entry data
+
+ 2. converting entry data from the Message Server format into that required by
+ the protocol
+
+ 3. doing the transfer operation using the appropriate communications protocols
+
+ The implementation of MoveFromLocalL() should differ from CopyFromLocalL()
+ in additionally deleting the original local data.
+
+ @param aSelection The collection of message index entries for which the move
+ is required
+ @param aDestination The entry ID of the service by which the entries should
+ be transferred
+ @param aStatus Asynchronous completion word for the operation
+ @leave KErrNotSupported The Server-side MTM does not support this operation
+ @leave Other leave codes Dependent on implementation */
+ virtual void MoveFromLocalL(const CMsvEntrySelection& aSelection,TMsvId aDestination, TRequestStatus& aStatus)=0;
+ /** Moves a selection of entries within a remote location.
+
+ Requirements:
+
+ Implementations should provide this function if the messaging protocol supports
+ the ability to move entries within a remote service. If this is not supported,
+ implementations should leave with KErrNotSupported.
+
+ The implementation of MoveWithinServiceL() should differ from CopyWithinServiceL()
+ in additionally deleting the original data.
+
+ @param aSelection The collection of message index entries for which the move
+ is required
+ @param aDestination The server entry ID to which the selection is to be moved
+ @param aStatus Asynchronous completion word for the operation
+ @leave KErrNotSupported The Server-side MTM does not support this operation
+ @leave Other leave codes Dependent on implementation */
+ virtual void MoveWithinServiceL(const CMsvEntrySelection& aSelection,TMsvId aDestination, TRequestStatus& aStatus)=0;
+
+ IMPORT_C TInt SystemProgress(TMsvSystemProgress& aOutSysProg);
+#if (defined SYMBIAN_USER_PROMPT_SERVICE)
+ TInt ClientThreadInfo(TThreadId aClientInfo, TBool aCapabilityCheck);
+#endif
+
+ TInt GetNonOperationMtmData(TNonOperationMtmDataType& aMtmDataType, TPtrC8& aResultBuffer);
+
+protected:
+ IMPORT_C CBaseServerMtm(CRegisteredMtmDll& aRegisteredMtmDll, CMsvServerEntry* aServerEntry);
+ /** Handles the completion of any asynchronous requests that it makes. It is called
+ from the base class RunL() .
+
+ Note that any leaves made by this function result in DoComplete() being called
+ with the leave code. */
+ virtual void DoRunL()=0;
+ /** Called by the base class RunL() if DoRunL() leaves.
+
+ It should be implemented to handle this error. For example, progress information
+ could be updated to reflect the problem.
+
+ @param aError The leave code given by DoRunL(). */
+ virtual void DoComplete(TInt aError)=0;
+ //
+ IMPORT_C TInt Extension_(TUint aExtensionId, TAny *&a0, TAny *a1);
+ //
+private:
+ // from CActive
+ IMPORT_C void RunL();
+ IMPORT_C TInt RunError(TInt aError);
+ //
+protected:
+ /** The entry on which to operate. It is set in the constructor.
+
+ The destructor deletes this member. */
+ CMsvServerEntry* iServerEntry;
+
+ // Method used for extension: called by non virtual methods that need
+ // to have a polymorphic behaviour.
+ IMPORT_C virtual TAny* GetInterface(TUid aUid);
+ //
+private:
+ CRegisteredMtmDll& iRegisteredMtmDll;
+
+private:
+ // Extra data member to allow for future extensions
+ TAny* iExtensionData;
+ };
+
+
+class CServerMtmDllRegistry : public CMtmDllRegistry
+/**
+@publishedAll
+@released
+*/
+ {
+friend class CMtmRegistryControl;
+public:
+ IMPORT_C static CServerMtmDllRegistry* NewL(RFs& aFs,TTimeIntervalMicroSeconds32 aTimeoutMicroSeconds32=KMsvDefaultTimeoutMicroSeconds32);
+ IMPORT_C ~CServerMtmDllRegistry();
+ IMPORT_C CBaseServerMtm* NewServerMtmL(TUid aMtmTypeUid, CMsvServerEntry* aInitialEntry);
+ //
+protected:
+ CServerMtmDllRegistry(RFs& aFs,TTimeIntervalMicroSeconds32 aTimeoutMicroSeconds32);
+ //
+private:
+ CBaseServerMtm* NewMtmL(const RLibrary& aLib, CMsvServerEntry* aServerEntry, CRegisteredMtmDll& aReg) const;
+ };
+
+//**********************************
+// CMsvMtmCache
+//**********************************
+
+
+//**********************************
+// CMtmRegistryControl
+//**********************************
+
+class CMtmRegistryControl : public CBase, public MRegisteredMtmDllObserver
+/**
+@publishedAll
+@released
+*/
+ {
+public:
+ IMPORT_C static CMtmRegistryControl* NewL(RFs& anFs,CServerMtmDllRegistry& aServerMtmDllRegistry);
+ IMPORT_C ~CMtmRegistryControl();
+
+ IMPORT_C TInt InstallMtmGroup(const TDesC& aFullName,TUid& aMtmTypeUid);
+ IMPORT_C TInt FullNameToMtmTypeUid(const TDesC& aFullName,TUid& aMtmTypeUid) const;
+ IMPORT_C TInt DeInstallMtmGroup(TUid aMtmTypeUid); // returns error on storing registry
+
+ IMPORT_C TInt UseMtmGroup(TUid aMtmTypeUid);
+ IMPORT_C TInt ReleaseMtmGroup(TUid aMtmTypeUid);
+ IMPORT_C TBool IsInUse(TUid aMtmTypeUid) const;
+
+ IMPORT_C TInt FillRegisteredMtmDllArray(TUid aMtmDllTypeUid,CRegisteredMtmDllArray& aRegisteredMtmDllArray,TTimeIntervalMicroSeconds32 aTimeoutMicroSeconds32=0); // Fill array with Dlls whose second uid is aMtmDllTypeUid
+ IMPORT_C CMtmGroupData* GetMtmGroupDataL(TUid aMtmTypeUid) const;
+ const CMtmGroupData& GetMtmGroupDataReferenceL(TUid aMtmTypeUid) const;
+
+ IMPORT_C void StoreRegistryL() const;
+ IMPORT_C void RestoreRegistryL();
+
+ IMPORT_C void InternalizeL(RReadStream& aStream);
+ IMPORT_C void ExternalizeL(RWriteStream& aStream) const;
+
+private:
+ CMtmRegistryControl(RFs& anFs,CServerMtmDllRegistry& aServerMtmDllRegistry);
+ void ConstructL();
+ TInt MtmTypeUidToIndex(TUid aMtmTypeUid) const;
+ TInt UidTypeToIndex(TUidType aUidType) const;
+ void DoInstallMtmGroupL(const TDesC& aFullName,TUid& aMtmTypeUid);
+ CMtmGroupData* ReadDataFileStoreL(const TDesC& aFullName) const;
+ void DoDeInstallMtmGroupL(TUid aMtmTypeUid);
+ void DoInternalizeL(RReadStream& aStream);
+ void AddInstalledMtmGroupL(CInstalledMtmGroup* aInstalledMtmGroup);
+ void RemoveInstalledMtmGroup(TUid aMtmTypeUid);
+ TBool IsResFileL(const TDesC& aFullName) const;
+ TUid DoFindMtmTypeUidL(const TDesC& aFullName) const;
+
+ CMtmGroupData *LoadMTMFileL(const TDesC& aFullName, TUid &aUid);
+ CMtmGroupData *LoadDatFileL(const TDesC& aFullName, TUid &aUid);
+ CMtmGroupData *LoadResFileL(const TDesC& aFullName, TUid &aUid);
+private:
+ RFs& iFs;
+ CInstalledMtmGroupArray* iInstalledMtmGroupArray;
+ CServerMtmDllRegistry& iServerMtmDllRegistry;
+ TPath iPathName;
+ };
+
+#endif // __MTSR_H__