diff -r 000000000000 -r 8e480a14352b messagingfw/msgsrvnstore/server/inc/MTCLBASE.H --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/messagingfw/msgsrvnstore/server/inc/MTCLBASE.H Mon Jan 18 20:36:02 2010 +0200 @@ -0,0 +1,552 @@ +// 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: +// MTCLBASE.H +// +/** + * @file + * @publishedAll + * @released + */ + +#ifndef __MTCLBASE_H__ +#define __MTCLBASE_H__ + +#include +#include +#include + +#include +#include +#include + +class CMsvAttachmentWaiter; + +/** Specifies one or more parts of a message in message-forwarding, message-reply, +and message-validation functions. + +Standard message parts are defined by the constants that can be added (or +bitwise-or'ed) together to specify multiple parts. Some message parts may +not be meaningful for some MTMs. + +Specifies find attributes which modify the behaviour of the search text utility +provided by the Global Find API. This does not apply to v5.1 nor to v5. */ +typedef TUint TMsvPartList; + +class CParaFormatLayer; +class CCharFormatLayer; + + +// +// Prototype of expected factory function + +typedef CBaseMtm* MtmFactoryFunctionL(CRegisteredMtmDll&, CMsvSession&); + + +/** Specifies function IDs for standard MTM functions. + +The function IDs are specified such that they do not coincide +with the free area defined for MTM commands. + +If MTMs also offer their own equivalents of these functions, +they may implement these function IDs by considering the +two IDs to be the same in their client MTM. + +MTMs that support SendAs must support SendMessage. +*/ +enum TMtmStandardAsyncCommands + { + KMTMStandardFunctionsSendMessage = KMtmFirstFreeStandardMtmFunctionId + }; + + +/*********************************************** +***********************************************/ +class CBaseMtm : public CBase, public MMsvEntryObserver +/** Provides a high-level interface for accessing and manipulating a Message Server +entry. + +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 following are some significant groups of functions: + +Context functions: the SetCurrentEntryL() and SwitchCurrentEntryL() functions +change the context - the entry on which later actions are performed. After +creating a new Client-side MTM object, a message client application should +set an initial context before using other functions. Note that: any changes +made to an existing context are not automatically saved: the message client +application should ensure this itself by calling SaveMessageL(); no message +data for the new context is retrieved from the Message Server, to retrieve +entry data, call LoadMessageL() after setting the context; calling Body() +immediately after setting the context returns an empty CRichText object: this +is because the private cache of context body text that the base class maintains +is re-initialised to an empty value. MTM implementers should note that the +virtual ContextEntrySwitched() is called from these functions to allow derived +classes to also clear any caches of MTM-specific entry data. + +Store and restore entry data functions: the changes that a message client +application makes to a message context through Client-side MTM functions, +such as altering the body text obtained through Body(), are, for efficiency, +cached in memory by a Client-side MTM. The message store and restore functions +are concerned with transferring data between that cache and committed storage. +Note that, unlike message contexts, message client applications are not expected +to manipulate directly service contexts. Instead, the corresponding User Interface +MTM will provide dialogs to allow the user to alter service settings, and +call Client-side MTM functions to handle their retrieval and storage. Symbian +OS v5 expects the base class functions to handle storage and retrieval for +both message and service contexts, and their implementations must detect what +the context is, and act accordingly. Post-v5, the API is clarified by restricting +the base class functions to handle message contexts only. To handle service +contexts, a Client-side MTM must define its own functions for the User Interface +MTM to call. + +Store and restore body text functions: the base class maintains a private +CRichText object cache to store the body text for the current context. This +can be accessed for reading and writing by message client applications through +Body(). StoreBodyL() and RestoreBodyL() encapsulate for implementers of derived +classes the retrieval and storage of this CRichText object to a CMsvStore. + +Address list functions: the format and storage of message addresses is MTM-specific. +AddresseeList(), AddAddresseeL(), and RemoveAddressee() are designed to allow +clients with no MTM-specific knowledge to access address information in a +generic way. The base class has a protected data member iAddresseeList, an +array of descriptors, which these functions manipulate. Implementations should +save the address information to the appropriate place in the message store +when the message is stored. + +MTM-specific functionality: 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: + IMPORT_C ~CBaseMtm(); + IMPORT_C TUid Type() const; + // + // context related + IMPORT_C void SetCurrentEntryL(CMsvEntry* aEntry); + IMPORT_C void SwitchCurrentEntryL(TMsvId aId); + IMPORT_C CMsvEntry& Entry() const; + IMPORT_C TBool HasContext() const; + // + // + /** Commits cached changes to the storage controlled by the Message Server. + + It can only be called on message contexts. It should be called in the following circumstances: + + 1. to preserve changes when the context is changed, or when the Client-side MTM + object is deleted + + 2. to enable other parts of the Messaging to access the updated entry, as required, + for example, before sending a message + + Requirements: + + An implementation must update the store and index entry relating to the message + context. Typically, the message store should be opened for editing with CMsvEntry::EditStoreL(). + It should be updated as follows: + + 1. body text: call StoreBodyL() to update the store's body text stream + + 2. address list: update the appropriate MTM-specific area of the store from the + data in iAddresseeList + + 3. subject: if supported, update the appropriate MTM-specific area of the store + from the private cache set by SetSubjectL() + + Changes can then be committed to the store with CMsvStore::CommitL(). + + The index entry should also be updated to reflect changes. Possible fields + that may need updating include: Description (for subject changes); Details + and Multiple Recipients (for recipient changes); and Size. Index entry changes + are committed using CMsvEntry::ChangeL(). + + The function should panic for non-message contexts. */ + virtual void SaveMessageL()=0; + /** Loads the cache with the message data for the current context. + + It can only be called on message contexts. + + It is typically used after the context has been set with SetCurrentEntryL() + or SwitchCurrentEntryL(). CBaseMtm functions to manipulate the entry can only + be called after this function has been called. + + Requirements: + + An implementation must restore the store and index entry relating to the message + context. Typically, the message store should be opened for reading with CMsvEntry::ReadStoreL(). + It should be then be read to set the following: + + 1. body text: call RestoreBodyL() to update the cached body text + + 2. address list: read the appropriate MTM-specific area of the store to update + iAddresseeList + + 3. subject: if supported, read the appropriate MTM-specific area of the store + and update the cache with SetSubjectL() + + The function should panic for non-message contexts. */ + virtual void LoadMessageL()=0; + /** Validates the current message context. + + The precise validation performed is specific to the MTM, but, typically, checks + that the specified message parts are well-formed. + + Requirements: + + Implementation of this function is highly protocol-specific. A minimum step + is to check that the current context is a message. + + @param aPartList Indicates the message parts for which validation is requested + + @return If valid, KErrNone If invalid, identifies the invalid part(s). The + error value is the bitmask of the TMsvPartList IDs for each invalid part */ + virtual TMsvPartList ValidateMessage(TMsvPartList aPartList)=0; + /** Searches the specified message part(s) for the plain-text version of the text + to be found. + + If the specified part list indicates a part that is not supported, or is not + present in the current message, the function behaves as if the specified part + exists but does not contain the required text. + + Requirements: + + The parts of the entry for which searching is allowed is implementation specific. + If no searching is supported, always return 0. + + @param aTextToFind The plain-text version of the text to be found. + @param aPartList Indicates the message parts which should be searched. + @return If the text was not found, or searching is unsupported, 0. If the text + was found, a bitmask of the TMsvPartList IDs for each part in which the text + was present. */ + virtual TMsvPartList Find(const TDesC& aTextToFind, TMsvPartList aPartList)=0; + // + // + /** Creates a reply message to the current message context. + + 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 creating 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 message in the specified destination by calling CMsvEntry::CreateL() + + 2. set the entry index values as appropriate + + 3. set the properties of the message as required. The normal minimum is to set + the address to the sender of the original message. An implementation may also + follow the options specified in aPartlist to set other properties, for example, + to include the original message text. + + 4. set the context to the reply + + 5. 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. + + The implementation of this function may be similar to that of ForwardL(), + allowing opportunities for code sharing. + + @param aDestination The entry to which to assign the reply + @param aPartlist Defines the parts that are to be copied from the original + message into the reply + @param aCompletionStatus The request status to be completed when the operation + has finished + @leave KErrNotSupported The Client-side MTM does not support reply operations + @leave Other leave codes 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. + + 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 message in the specified destination by calling CMsvEntry::CreateL() + + 2. set the entry index values as appropriate + + 3. set message content as required. The normal minimum is to include the text + of the original message. An implementation may also follow the options specified + in aPartlist to include other properties of the original message. + + 4. set the context to the reply + + 5. 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. + + The implementation of this function may be similar to that of ReplyL(), allowing + opportunities for code sharing. + + @param aDestination The entry to which to assign the forwarded message + @param aPartList Defines the parts that 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 Client-side MTM does not support creation of forwarded + messages + @leave Other leave codes Dependent on implementation + @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. */ + virtual CMsvOperation* ForwardL(TMsvId aDestination, TMsvPartList aPartList, TRequestStatus& aCompletionStatus)=0; + // + // addresssee list (used by objects with no MTM knowledge) + IMPORT_C const CMsvRecipientList& AddresseeList() const; + + /** Adds an addressee for the current context. + + Addresses are not validated by checking their format by this function. Usually + that is performed by calling ValidateMessage(). + + Requirements: + + Implementations should append the address to the object's address cache + in the protected iAddresseeList data member. Some implementations may also + wish to store addresses in an internal data structure appropriate for the + protocol, for example, a class holding message header information. + + @param aRealAddress String representing an address to be added to the list + for the current message + @leave KErrNotSupported The message already has the maximum number of addressees + + @leave Other leave codes Dependent on implementation */ + virtual void AddAddresseeL(const TDesC& aRealAddress)=0; + /** Adds an addressee for the current context, and enables the client to specify + an alias, which may be useful for some protocols. For example, for fax, if + the address is the fax number, the alias could supply the recipient's name. + + Addresses are not validated by checking their format by this function. Usually + that is performed by calling ValidateMessage(). + + Requirements: + + Implementations should append the address to the object's address cache + in the protected iAddresseeList data member. Some implementations may also + wish to store addresses in an internal data structure appropriate for the + protocol, for example, a class holding message header information. + + @param aRealAddress String representing an address to be added to the list + for the current message + @param aAlias Alias information + @leave KErrNotSupported The message already has the maximum number of addressees + + @leave Other leave codes Dependent on implementation */ + virtual void AddAddresseeL(const TDesC& aRealAddress, const TDesC& aAlias)=0; + + IMPORT_C virtual void AddAddresseeL(TMsvRecipientType aType, const TDesC& aRealAddress); + IMPORT_C virtual void AddAddresseeL(TMsvRecipientType aType, const TDesC& aRealAddress, const TDesC& aAlias); + + /** Removes an address from the current address list. The address is specified + by a zero-based index into the address list. If the index is not known, applications + can use AddresseeList() to retrieve the entire list to find the item. + + Requirements: + + Implementations should call iAddresseeList->Delete(aIndex) to remove the address + from in the address list protected data member. + + @param aIndex Index of address to be removed */ + virtual void RemoveAddressee(TInt aIndex)=0; + // + // standard data accessor/mutators + IMPORT_C CRichText& Body(); + IMPORT_C const CRichText& Body() const; + IMPORT_C virtual void SetSubjectL(const TDesC& aSubject); // default leaves with KErrNotSupported + IMPORT_C virtual const TPtrC SubjectL() const; // default leaves with KErrNotSupported + // + // RTTI functions + IMPORT_C virtual TInt QueryCapability(TUid aCapability, TInt& aResponse); // default returns KErrNotSupported + /** Invokes synchronous protocol-specific operations. For asynchronous operations, + a similar function, InvokeAsyncFunctionL(), is available. + + aSelection and aParameter allow data to be passed to the operation. + + Requirements: + + For functionality that requires message transport access, such as making a + connection, the implementation should pass the request onto the corresponding + Server-side MTM. This is done through calling CMsvSession::TransferCommandL(). + Implementations may also provide protocol-specific functions themselves if + this is useful. + + @param aFunctionId ID of the requested operation + @param aSelection Selection of message entries. This is used if the operation + requires message entries to work on. + @param aParameter Buffer containing input and output parameters. The format + of this is specific to the operation. + @leave KErrNotSupported aFunctionId is not a recognised operation ID + @leave Other leave codes Dependent on implementation */ + virtual void InvokeSyncFunctionL(TInt aFunctionId,const CMsvEntrySelection& aSelection, TDes8& aParameter)=0; + /** Invokes asynchronous protocol-specific operations. For synchronous operations, + a similar function, InvokeSyncFunctionL(), is available. + + aSelection and aParameter allow data to be passed to the operation. The TRequestStatus + and CMsvOperation objects are used as normal to control and monitor the operation. + + Requirements: + + For functionality that requires message transport access, such as making a + connection, the implementation should pass the request onto the corresponding + Server-side MTM. This is done through calling CMsvSession::TransferCommandL(). + Implementations may also provide protocol-specific functions themselves if + this is useful. + + InvokeAsyncFunctionL() should return a CMsvOperation-derived object to provide + asynchronous control and monitoring of the operation. If CMsvSession::TransferCommandL() + is called, this should be the CMsvOperation object returned by that function. + + @param aFunctionId ID of the requested operation + @param aSelection Selection of message entries. This is used if the operation + requires message entries to work on. + @param aParameter Buffer containing input and output parameters. The format + of this is specific to the operation. + @param aCompletionStatus The request status to be completed when the operation + has finished + @leave KErrNotSupported aFunctionId is not a recognised operation ID + @leave Other leave codes Dependent on implementation + @return If successful, this is an asynchronously completing operation. If failed, + this is a completed operation, with status set to the relevant error code. */ + virtual CMsvOperation* InvokeAsyncFunctionL(TInt aFunctionId,const CMsvEntrySelection& aSelection, TDes8& aParameter, TRequestStatus& aCompletionStatus)=0; + // + IMPORT_C CMsvSession& Session(); + + // Attachment functions to support the SendAs API + virtual inline void Filler1() {}; + virtual inline void Filler2() {}; + IMPORT_C virtual void AddAttachmentL(const TDesC& aFilePath, const TDesC8& aMimeType, TUint aCharset, TRequestStatus& aStatus); + IMPORT_C virtual void AddAttachmentL(RFile& aFile, const TDesC8& aMimeType, TUint aCharset, TRequestStatus& aStatus); + IMPORT_C virtual void AddLinkedAttachmentL(const TDesC& aFilePath, const TDesC8& aMimeType, TUint aCharset, TRequestStatus& aStatus); + IMPORT_C virtual void AddEntryAsAttachmentL(TMsvId aAttachmentId, TRequestStatus& aStatus); + IMPORT_C virtual void CreateAttachmentL(const TDesC& aFileName, RFile& aAttachmentFile, const TDesC8& aMimeType, TUint aCharset, TRequestStatus& aStatus); + IMPORT_C virtual void CancelAttachmentOperation(); + + IMPORT_C virtual void CreateMessageL(TMsvId aServiceId); + + // BIO functions to support the SendAs API + // Entry().Entry().iBioType will be set by SendAs if this function does not leave. + // The default implementation in CBaseMtm is to do nothing. + IMPORT_C virtual void BioTypeChangedL(TUid aBioTypeUid); + + IMPORT_C virtual TMsvId DefaultServiceL() const; + IMPORT_C virtual void RemoveDefaultServiceL(); + IMPORT_C virtual void ChangeDefaultServiceL(const TMsvId& aService); + + //For setting the character encoding value, options are 7-bit, 8-bit and 16-bit Unicode. + IMPORT_C TInt SetMessageCharacterSet(TUint aCharSet); + IMPORT_C void SetExtensionData(TAny* aSortData); + IMPORT_C TAny* GetExtensionData(); + +protected: + IMPORT_C CBaseMtm(CRegisteredMtmDll& aRegisteredMtmDll, CMsvSession& aSession); + // + IMPORT_C void StoreBodyL(CMsvStore& aStore); + IMPORT_C void RestoreBodyL(CMsvStore& aStore); + // + /** Called by the base class functions SwitchCurrentEntryL() and SetCurrentEntryL() + when the context is changed to another entry. + + Client applications do not use this function. It is relevant only to implementers + of derived classes. + + Requirements: + + An implementation should clear: + + 1. address data stored in iAddresseeList + + 2. any caches of MTM-specific entry data relating to a previous context. For + example, if the implementation has a private buffer storing a message subject, + for access through Subject(), this buffer should be cleared. */ + virtual void ContextEntrySwitched()=0; // called after the context of this instance has been changed to another entry + // + IMPORT_C void HandleEntryEventL(TMsvEntryEvent aEvent, TAny* aArg1, TAny* aArg2, TAny* aArg3); + + // Method used for extension: called by non virtual methods that need + // to have a polymorphic behaviour. + IMPORT_C virtual TAny* GetInterface(TUid aUid); + + // From CBase + IMPORT_C virtual TInt Extension_(TUint aExtensionId, TAny*& a0, TAny* a1); + +private: + void DeleteEntry(); + + void AddFilePathAttachmentL(const TDesC& aFilePath, const TDesC8& aMimeType, TUint aCharset, CMsvAttachment::TMsvAttachmentType aType, TRequestStatus& aStatus); + + + +protected: + /** The current context. */ + CMsvEntry* iMsvEntry; + /** The address list for the current context. */ + CMsvRecipientList* iAddresseeList; + + /** Paragraph formatting applied to the CRichText object for the body text, as + returned by Body(). This is set to an empty CParaFormatLayer instance whenever + the context is set. + + Implementations can modify this if they wish to apply particular formatting + to body text. */ + CParaFormatLayer* iParaFormatLayer; + /** Character formatting applied to the CRichText object for the body text, as + returned by Body(). + + Implementations can modify this if they wish to apply particular formatting + to body text. */ + CCharFormatLayer* iCharFormatLayer; + + + +private: + TMsvId iEntryId; + CRichText* iRichTextBody; + CRegisteredMtmDll& iRegisteredMtmDll; + CMsvSession& iSession; + CMsvAttachmentWaiter* iAttachmentWaiter; + + // Extra data member to allow for future extensions + TAny* iExtensionData; + }; + + +#endif // __MTCLBASE_H__