diff -r 000000000000 -r 8e480a14352b messagingfw/msgsrvnstore/mtmbase/inc/MTMUIBAS.H --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/messagingfw/msgsrvnstore/mtmbase/inc/MTMUIBAS.H Mon Jan 18 20:36:02 2010 +0200 @@ -0,0 +1,527 @@ +// 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: +// + +#if !defined(__MTMUIBAS_H__) +#define __MTMUIBAS_H__ + +#if !defined(__MSVSTD_H__) +#include +#endif +#if !defined(__MTCLBASE_H__) +#include +#endif + +// Forward references +class CMsvSession; +class CMsvOperation; +class CCoeEnv; + +// +// CBaseMtmUi - MTMUi base API // +// +class CBaseMtmUi : public CBase +/** Provides MTM-specific user interaction, such as editing, viewing, deleting, +and copying of message entries. + +Message client applications use the class to access such functionality polymorphically. +MTM implementers implement a derived class to provide such functionality for +their message protocol. + +The base class is largely an interface definition: it implements little important +functionality itself. For implementers, this documentation defines conditions +that any implementation must fulfil, plus suggested semantics for behaviour. +This still leaves many decisions in the hands of the implementer. A key design +time activity is to define how the particular characteristics of the implemented +protocol are best mapped to the interface. As this class is concerned with +user interfaces, implementers should be sensitive to the look and feel of +the target phone. + +Many functions are required to return an instance of a CMsvOperation-derived +class to provide asynchronous control and monitoring to the caller of the +operation being performed. + +The following are some significant groups of functions: + +Entry manipulation functions: OpenL(), CloseL(), EditL(), and ViewL() are +all available in two overloaded versions. The first version operates on the +current context. The second version operates upon groups of entries specified +by a CMsvEntrySelection argument. All entries must be in same folder and all +of the correct MTM type. The context may change after calling these functions. +Concrete User Interface MTMs can legally ignore any of the entries within +the selection - many may, for example, simply open the first entry. + +Copying and moving functions: the CopyToL(), CopyFromL(), MoveToL(), and MoveFromL() +functions are concerned with copying and moving entries to and from remote +servers. MTMs can implement these functions to provide any user interaction +needed before copying or moving can proceed, such as dialogs to confirm settings; +and, any protocol-specific setup steps that can be done at this stage: for +example, a fax MTM could render messages into the required image format. + +Progress information functions: DisplayProgressSummary() and GetProgress() +convert MTM-specific progress information about some asynchronous operation, +such as message sending, to a human-readable form. The progress information +to pass into these functions is, in general, obtained from an on-going CMsvOperation +by calling CMsvOperation::Progress(). The nature of any information provided +is MTM-specific. + +MTM-specific UI functions: MTM components can offer protocol-specific functionality +not provided by base class interface functions. MTM components define IDs +that correspond to each protocol-specific operation offered, and implement +the InvokeSyncFunctionL() and InvokeAsyncFunctionL() functions to allow clients +to access these operations by passing in the appropriate ID. Two functions +are provided to allow the MTM component to offer both synchronous and asynchronous +functionality. Message client applications can dynamically add user-interface +features for these operations using CBaseMtmUiData::MtmSpecificFunctions(). +MTM developers should document the IDs if they wish to make the operations +available to clients. +@publishedAll +@released +*/ + { +public: + // --- enums --- + /** Progress information buffer length. */ + enum { + /** Defines the maximum buffer length used in GetProgress() to hold progress information. */ + EProgressStringMaxLen=255}; + // + // --- Set up functionality --- + IMPORT_C void SetPreferences(TUint aFlags); + IMPORT_C TUint Preferences() const; + // + // --- Destruction --- + IMPORT_C virtual ~CBaseMtmUi(); + // + // --- Accessor functions --- + IMPORT_C TUid Type() const; + IMPORT_C CBaseMtm& BaseMtm() const; + // + // --- Functions NOT dependent on the current context --- + IMPORT_C virtual CMsvOperation* CreateL(const TMsvEntry& aEntry, CMsvEntry& aParent, TRequestStatus& aStatus); + // + // --- Functions dependent on the current context --- + /** Opens an entry. + + The behaviour that this implies is dependent on the current context: + + 1. for message contexts, OpenL() is the equivalent of EditL(), or for read-only + messages, ViewL(). Whether opening of remote messages is allowed is MTM-specific. + + 2. for service contexts, the function may initiate a connection to obtain the + service contents from the server, completing asynchronously + + 3. for remote folder contexts, dependent on implementation, the function may + initiate a connection to obtain the folder contents from the server, completing + asynchronously + + The returned CMsvOperation object completes when opening is complete. + + Requirements: + + If opening entries is not supported, implementations should leave with KErrNotSupported. + Otherwise, implementations should: + + 1. check aEntry.iType.iUid to ensure that they can open the requested type of + entry and leave with code KErrNotSupported if they cannot + + 2. return a CMsvOperation-derived object to provide asynchronous control and + monitoring of the operation + + 3. for remote messages, typically, copy the messages to the Inbox + + @param aStatus The request status to be completed when the operation has finished + + @leave KErrNotSupported The User Interface MTM does not support open operations, + or opening is inappropriate to the current context + @leave Other Dependent on implementation + @return If successful, this is an asynchronously completing open operation. + If failed, this is a completed operation, with status set to the relevant + error code. */ + virtual CMsvOperation* OpenL(TRequestStatus& aStatus) = 0; + /** Closes an entry. The behaviour that this implies is dependent on the current + context: + + 1. for message contexts, this usually closes any launched editors or viewers + + 2. for folder contexts, leaves with KErrNotSupported + + 3. for service contexts, causes closure of a connection to a server + + The returned CMsvOperation object completes when closing is complete. + + Requirements: + + Implementations should: + + 1. check aEntry.iType.iUid to ensure that they can close the requested type of + entry and leave with code KErrNotSupported if they cannot + + 2. return a CMsvOperation-derived object to provide asynchronous control and + monitoring of the operation + + @param aStatus The request status to be completed when the operation has finished + + @leave KErrNotSupported The User Interface MTM does not support close operations, + or closing is inappropriate to the current context + @leave Other Dependent on implementation + @return If successful, this is an asynchronously completing close operation. + If failed, this is a completed operation, with status set to the relevant + error code. */ + virtual CMsvOperation* CloseL(TRequestStatus& aStatus) = 0; + /** Edits an entry. + + The behaviour that this implies is dependent on the current + context: + + 1. for message contexts, this usually launches the appropriate message editor, + or returns status KErrReadOnly if the message is not editable + + 2. for remote folder contexts, launches a settings dialog, for example to rename + the folder, completing asynchronously + + 3. for service contexts, launches a service settings dialog, completing asynchronously + + The returned CMsvOperation object completes when editing is complete. + + Requirements: + + Implementations should: + + 1. check aEntry.iType.iUid to ensure that they can edit the requested type of + entry and leave with code KErrNotSupported if they cannot + + 2. return a CMsvOperation-derived object to provide asynchronous control and + monitoring of the operation + + 3. for remote messages, typically, copy the messages to the Inbox + + 4. follow the leave protocols described in Leave considerations below + + @param aStatus The request status to be completed when the operation has finished + @leave KErrNotSupported The User Interface MTM does not support edit operations, + or editing is inappropriate to the current context + @leave KErrReadOnly Context is read-only + @leave Other Dependent on implementation + @return If successful, this is an asynchronously completing edit operation. + If failed, this is a completed operation, with status set to the relevant + error code. */ + virtual CMsvOperation* EditL(TRequestStatus& aStatus) = 0;// Launches editor/settings dialog as appropriate + /** Views an entry. + + For message contexts, this usually launches the appropriate + message viewer. Other context types leave with KErrNotSupported. The returned + CMsvOperation object completes when viewing is complete. + + Requirements: + + Implementations should: + + 1. check aEntry.iType.iUid to ensure that they can view the requested type of + entry and leave with code KErrNotSupported if they cannot + + 2. return a CMsvOperation-derived object to provide asynchronous control and + monitoring of the operation + + @param aStatus The request status to be completed when the operation has finished + @leave KErrNotSupported The User Interface MTM does not support view operations, + or viewing is inappropriate to the current context + @leave Other Dependent on implementation + @return If successful, this is an asynchronously completing view operation. + If failed, this is a completed operation, with status set to the relevant + error code. */ + virtual CMsvOperation* ViewL(TRequestStatus& aStatus) = 0;// Launches viewer/settings dialog as appropriate + // + // --- Actions upon message selections --- + // --- Selections must be in same folder and all of the correct MTM type --- + // --- Context may change after calling these functions --- + /** Opens a selection of entries. + + The behaviour that this implies is dependent on the current context: + + 1. for message contexts, OpenL() is the equivalent of EditL(), or for read-only + messages, ViewL(). Whether opening of remote messages is allowed is MTM-specific. + + 2. for service contexts, the function may initiate a connection to obtain the + service contents from the server, completing asynchronously + + 3. for remote folder contexts, dependent on implementation, the function may + initiate a connection to obtain the folder contents from the server, completing + asynchronously + + The returned CMsvOperation object completes when opening is complete. + + Requirements: + + If opening entries is not supported, implementations should leave with KErrNotSupported. + Otherwise, implementations should: + + 1. check aEntry.iType.iUid to ensure that they can open the requested type of + entry and leave with code KErrNotSupported if they cannot + + 2. return a CMsvOperation-derived object to provide asynchronous control and + monitoring of the operation + + 3. for remote messages, typically, copy the messages to the Inbox + + @param aStatus The request status to be completed when the operation has finished + @param aSelection Selection of message entries + @leave KErrNotSupported The User Interface MTM does not support open operations, + or opening is inappropriate to the current context + @leave Other Dependent on implementation + @return If successful, this is an asynchronously completing open operation. + If failed, this is a completed operation, with status set to the relevant + error code. */ + virtual CMsvOperation* OpenL(TRequestStatus& aStatus, const CMsvEntrySelection& aSelection) = 0; + /** Closes a selection of entries. + + The behaviour that this implies is dependent on the current context: + + 1. for message contexts, this usually closes any launched editors or viewers + + 2. for folder contexts, leaves with KErrNotSupported + + 3. for service contexts, causes closure of a connection to a server + + The returned CMsvOperation object completes when closing is complete. + + Requirements: + + Implementations should: + + 1. check aEntry.iType.iUid to ensure that they can close the requested type of + entry and leave with code KErrNotSupported if they cannot + + 2. return a CMsvOperation-derived object to provide asynchronous control and + monitoring of the operation + + @param aStatus The request status to be completed when the operation has finished + @param aSelection Selection of message entries + @leave KErrNotSupported The User Interface MTM does not support close operations, + or closing is inappropriate to the current context + @leave Other Dependent on implementation + @return If successful, this is an asynchronously completing close operation. + If failed, this is a completed operation, with status set to the relevant + error code. */ + virtual CMsvOperation* CloseL(TRequestStatus& aStatus, const CMsvEntrySelection& aSelection) = 0; + /** Edits a selection of entries. + + The behaviour that this implies is dependent on the current context: + + 1. for message contexts, this usually launches the appropriate message editor, + or returns status KErrReadOnly if the message is not editable + + 2. for remote folder contexts, launches a settings dialog, for example to rename + the folder, completing asynchronously + + 3. for service contexts, launches a service settings dialog, completing asynchronously + + The returned CMsvOperation object completes when editing is complete. + + Requirements: + + Implementations should: + + 1. check aEntry.iType.iUid to ensure that they can edit the requested type of + entry and leave with code KErrNotSupported if they cannot + + 2. return a CMsvOperation-derived object to provide asynchronous control and + monitoring of the operation + + 3. for remote messages, typically, copy the messages to the Inbox + + 4. follow the leave protocols described in Leave considerations below + + @param aStatus The request status to be completed when the operation has finished + @param aSelection Selection of message entries + @leave KErrNotSupported The User Interface MTM does not support edit operations, + or editing is inappropriate to the current context + @leave KErrReadOnly Context is read-only + @leave Other Dependent on implementation + @return If successful, this is an asynchronously completing edit operation. + If failed, this is a completed operation, with status set to the relevant + error code. */ + virtual CMsvOperation* EditL(TRequestStatus& aStatus, const CMsvEntrySelection& aSelection) = 0;// Launches editor/settings dialog as appropriate + /** Views a selection of entries. + + For message contexts, this usually launches the appropriate + message viewer. Other context types leave with KErrNotSupported. The returned + CMsvOperation object completes when viewing is complete. + + Requirements: + + Implementations should: + + 1. check aEntry.iType.iUid to ensure that they can view the requested type of + entry and leave with code KErrNotSupported if they cannot + + 2. return a CMsvOperation-derived object to provide asynchronous control and + monitoring of the operation + + @param aStatus The request status to be completed when the operation has finished + @param aSelection Selection of message entries + @leave KErrNotSupported The User Interface MTM does not support view operations, + or viewing is inappropriate to the current context + @leave Other Dependent on implementation + @return If successful, this is an asynchronously completing view operation. + If failed, this is a completed operation, with status set to the relevant + error code. */ + virtual CMsvOperation* ViewL(TRequestStatus& aStatus, const CMsvEntrySelection& aSelection) = 0;// Launches viewer/settings dialog as appropriate + /** Cancels the sending of specified messages. + + @param aStatus The request status to be completed when the operation has finished + @param aSelection Selection of message entries + @leave KErrNotSupported The User Interface MTM does not support cancel operations, + or cancelling is inappropriate to the current context + @leave Other Dependent on implementation + @return If successful, this is an asynchronously completing cancel operation. + If failed, this is a completed operation, with status set to the relevant + error code. */ + virtual CMsvOperation* CancelL(TRequestStatus& aStatus, const CMsvEntrySelection& aSelection) = 0; + // + // --- Deletion --- + // --- Deletes entries from the current context, which must be a folder or service of the relevant MTM --- + IMPORT_C virtual CMsvOperation* DeleteFromL(const CMsvEntrySelection& aSelection, TRequestStatus& aStatus);//Deletes selection from current context + // --- Un-deletes entries from the current context, which must be a folder or service of the relevant MTM --- + IMPORT_C virtual CMsvOperation* UnDeleteFromL(const CMsvEntrySelection& aSelection, TRequestStatus& aStatus);//Un-deletes selection from current context + // --- Deletes service, which need not be the current context --- + IMPORT_C virtual CMsvOperation* DeleteServiceL(const TMsvEntry& aService, TRequestStatus& aStatus); // default implementation simply delegates to the server + // + // --- Message responding --- + /** Creates a reply message to the current message context, and allows the user + to edit it through a message-type specific editor. + + Some MTMs may support inclusion of elements, specified by aPartlist, from the original message in the reply. + The parent for the new entry is specified in aDestination. The returned CMsvOperation + object completes when editing the reply is complete. On completion, the context + is set to the reply message. + + Requirements: + + A typical implementation for this function would include the following steps: + + 1. create a new reply entry by calling CBaseMtm::ReplyL() + + 2. call EditL() allow the user to edit the reply + + 3. return a CMsvOperation-derived object to provide asynchronous control and + monitoring of the operation + + If message replies are not supported, implementations should leave with KErrNotSupported. + + @param aDestination The entry to which to assign the reply + @param aPartlist Defines the parts which are to be copied from the original + message into the reply. See CBaseMtm::ReplyL() for details. + @param aCompletionStatus The request status to be completed when the operation + has finished + @leave KErrNotSupported The User Interface MTM does not support reply operations + @leave Other Dependent on implementation + @return If successful, this is an asynchronously completing reply operation. + If failed, this is a completed operation, with status set to the relevant + error code. */ + virtual CMsvOperation* ReplyL(TMsvId aDestination, TMsvPartList aPartlist, TRequestStatus& aCompletionStatus) = 0; + /** + Creates a forwarded message from the current message context, and allows the user to edit it through a message-type + specific editor. + + Some MTMs may support inclusion of elements, specified by aPartlist, from the original message in the + forwarded message. The parent for the new entry is specified in aDestination. The returned CMsvOperation + object completes when editing the forwarded message is complete. On completion, the context is set to the forwarded message. + + Requirements: + + A typical implementation for this function would include the following steps: + + 1. create a new forwarded message entry by calling CBaseMtm::ForwardL() + + 2. call EditL() allow the user to edit the forwarded message + + 3. return a CMsvOperation-derived object to provide asynchronous control and monitoring of the operation + + If forwarded messages are not supported, implementations should leave with KErrNotSupported. + + @return If successful, this is an asynchronously completing forward message operation. If failed, + this is a completed operation, with status set to the relevant error code. + @param aDestination The entry to which to assign the forwarded message + @param aPartList Defines the parts which are to be copied from the original message into the forwarded message + @param aCompletionStatus The request status to be completed when the operation has finished + @leave KErrNotSupported The User Interface MTM does not support message forwarding operations + @leave Other Dependent on implementation + */ + virtual CMsvOperation* ForwardL(TMsvId aDestination, TMsvPartList aPartList, TRequestStatus& aCompletionStatus) = 0; + + // + // --- Copy and move functions --- + // --- Context should be set to folder or entry of this MTM --- + // --- Default implementations imply call the relevant CMsvEntry functions --- + IMPORT_C virtual CMsvOperation* CopyToL(const CMsvEntrySelection& aSelection, TRequestStatus& aStatus);// Context should be MTM folder/service to copy to + IMPORT_C virtual CMsvOperation* MoveToL(const CMsvEntrySelection& aSelection, TRequestStatus& aStatus);// Context should be MTM folder/service to move to + IMPORT_C virtual CMsvOperation* CopyFromL(const CMsvEntrySelection& aSelection, TMsvId aTargetId, TRequestStatus& aStatus);// Context should be MTM folder/service to copy from + IMPORT_C virtual CMsvOperation* MoveFromL(const CMsvEntrySelection& aSelection, TMsvId aTargetId, TRequestStatus& aStatus);// Context should be MTM folder/service to move from + // + // --- Interpret transfer progress --- + IMPORT_C virtual TInt DisplayProgressSummary(const TDesC8& aProgress) const;// Used for display operation summary (usually completed operations). Default implementation returns KErrNotSupported. + IMPORT_C virtual TInt GetProgress(const TDesC8& aProgress, TBuf& aReturnString, TInt& aTotalEntryCount, TInt& aEntriesDone, + TInt& aCurrentEntrySize, TInt& aCurrentBytesTrans) const;// Default implementation returns KErrNotSupported + // + // --- RTTI functions --- + IMPORT_C virtual TInt QueryCapability(TUid aCapability, TInt& aResponse); + IMPORT_C virtual void InvokeSyncFunctionL(TInt aFunctionId, const CMsvEntrySelection& aSelection, TDes8& aParameter); + IMPORT_C virtual CMsvOperation* InvokeAsyncFunctionL(TInt aFunctionId, const CMsvEntrySelection& aSelection, TRequestStatus& aCompletionStatus, + TDes8& aParameter); + +protected: + // --- Construction --- + IMPORT_C CBaseMtmUi(CBaseMtm& aBaseMtm, CRegisteredMtmDll& aRegisteredMtmDll); + IMPORT_C virtual void ConstructL(); + /** Sets the full path and name of the resource file associated with the User Interface MTM. + + Client applications do not use this function. It is relevant only to implementers of derived classes. + + Requirements: + + The function is called by CBaseMtmUi::ConstructL(), which then loads the resource + file. + + @param aFileName Filename buffer to be filled with the resource file path + and name */ + virtual void GetResourceFileName(TFileName& aFileName) const = 0; + // + // --- Utility functions --- + IMPORT_C CMsvSession& Session() const; + + // Method used for extension: called by non virtual methods that need + // to have a polymorphic behaviour. + IMPORT_C virtual TAny* GetInterface(TUid aUid); + +protected: + // --- Data --- + /** The CBaseMtm-derived object (Client-side MTM) that requested the User Interface + MTM. It is set by the constructor. */ + CBaseMtm& iBaseMtm; + /** Control environment object. It is set by the constructor. */ + CCoeEnv* iCoeEnv; + /** This flag records the preferences as set by SetPreferences(). */ + TUint iFlags; + +private: + // --- Data --- + CRegisteredMtmDll& iRegisteredMtmDll; + TInt iResourceFileOffset; + // Extra data member to allow for future extensions + TAny* iExtensionData; + }; + + +#endif // __MTMUIBAS_H__