diff -r 000000000000 -r 72b543305e3a mobilemessaging/unieditor/mtm/inc/UniClientMtm.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mobilemessaging/unieditor/mtm/inc/UniClientMtm.h Thu Dec 17 08:44:11 2009 +0200 @@ -0,0 +1,735 @@ +/* +* Copyright (c) 2005-2007 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: +* Client Mtm for uni messaging. +* This is the API for accessing uni messages. An uni message ends up to be a sms or mms message. +* +*/ + + + +#ifndef __UNICLIENTMTM_H__ +#define __UNICLIENTMTM_H__ + +// INCLUDES +#include // base client mtm +#include // TTimeInterval & TTime + + +// CONSTANTS + +// MACROS + +// DATA TYPES + +enum TUniMessageTypeSetting + { + EUniMessageTypeSettingAutomatic = 0, + EUniMessageTypeSettingSms, // This includes also fax & pager + EUniMessageTypeSettingMms + }; + +enum TUniMessageTypeLocking + { + EUniMessageTypeLockingNotSet = 0, // This means it's not handled yet by anyone + EUniMessageTypeLocked, + EUniMessageTypeNotLocked + }; + +// FUNCTION PROTOTYPES + +// FORWARD DECLARATIONS + +class CUniHeaders; +class CMsvMimeHeaders; +class CMsvFindText; +class CMmsAttachmentWaiter; +class CMsgTextUtils; + +// CLASS DECLARATION + +/** +* Client Mtm for unified messaging subsystem. +* This class will be the interface to the UI component +* and other messaging component that might want to handle unified messages +* (For example SendAs interface). +* +* Note: new functions has to be added as last virtual functions in order +* not to to break the vtable +*/ +class CUniClientMtm :public CBaseMtm + { + public: // Constructors and destructor + // constructor is private! + + /** + * Factory function. + * The only function exported by this polymorphic interface dll.
+ * This function is not directly called by the application that needs + * access, it is called by an instance of CClientMtmRegistry class. + * @param aRegisteredMtmDll Reference to Mtm Dll registry class + * @param aSession Reference to a Message Server session. + * @return Pointer to CUniClientMtm class. + * + * 
+        * Example of getting access to this class:
+        *
+        * // Called by a Uikon application that implements
+        * // MMsvSessionObserver interface
+        *
+        * iSession = CMsvSession::OpenSyncL(*this);
+        * CleanupStack::PushL(iSession);
+        * iClientMtmRegistry = CClientMtmRegistry::NewL(*iSession);
+        * CleanupStack::PushL(iClientMtmRegistry);
+        * iClientMtm = (CUniClientMtm *) iClientMtmRegistry->
+        *               NewMtmL(KUidUniMtm);
+        * CleanupStack::PushL(iClientMtm);
+        *
+        * // - do other initialization -
+        *
+        * CleanupStack::Pop(3);    //iSession, iClientMtmRegistry, iClientMtm
+        *
+        * // - call any public functions in CUniClientMtm
+        *
+        * // When the application finishes,
+        * // it must delete the objects in reverse order:
+        * delete iClientMtm;
+        * delete iClientMtmRegistry;
+        * delete iSession;
+        *
+ */ + IMPORT_C static CUniClientMtm* NewL( + CRegisteredMtmDll& aRegisteredMtmDll, + CMsvSession& aSession ); + + /** + * Destructor. + */ + virtual ~CUniClientMtm(); + + public: // New functions + + // ---------------------------------------------------------- + // Functions to create and modify message entries + + /** + * Create a new message entry + * + * @param aDestination target folder + * @return Id of the created message + */ + virtual TMsvId CreateNewEntryL( TMsvId aDestination ); + + // ------------------------------------------------------------------- + // GENERAL MESSAGE INFORMATION METHODS + + /** + * Message size accessor. SaveMessageL and LoadMessageL updates the + * value. + * @return size of all message parts in bytes including both + * attachments and internal header structures. The actual message + * size in transmission is smaller due to the header + * binary encoding. + */ + virtual TInt32 MessageSize(); + + /** + * Message description mutator. + * This provides a method to override the default message description. + * The next SaveMessageL saves the description text in the + * TMsvEntry::iDescription. + * Note that this method does not check the text length, so avoid long + * descriptions to minimize memory usage. + * @param aText message description + */ + virtual void SetMessageDescriptionL( const TDesC& aText ); + + // ------------------------------------------------------------------- + // FUNCTIONS TO HANDLE MESSAGE ATTACHMENTS + + /** + * Create text/plain attachment.
+ * Creates a text attachment from descriptor. + * Has option to convert all unicode paragraph separator marks to + * line feeds. + * Converts text from unicode (ucs-2) to utf-8 before storing it. + * @param aStore an open EditStore. Caller must commit store + * (several attachments can be added before committing store) + * @param aAttachmentId returned ID of the new attachment entry + * @param aText UNICODE text to be added as a text/plain attachment. + * @param aFile suggested filename for the attachment + * @param aConvertParagraphSeparator flag to tell if the function + * will search for all 0x2029 characters (Unicode paragraph + * separator) and replace them with 0x000a (line feed). + * aConvertParagraphSeparator == ETrue: convert + * aConvertParagraphSeparator == EFalse: do not convert + */ + virtual void CreateTextAttachmentL( + CMsvStore& aStore, + TMsvAttachmentId& aAttachmentId, + const TDesC& aText, + const TDesC& aFile, + TBool aConvertParagraphSeparator = ETrue ); + + /** + * Accessor for message type setting + * @return Message type setting + */ + virtual TUniMessageTypeSetting MessageTypeSetting() const; + + /** + * Mutator for message type setting + * @param aSetting Message type setting + */ + virtual void SetMessageTypeSetting( TUniMessageTypeSetting aSetting ); + + /** + * Accessor for message type locking + * @return Message type locking + */ + virtual TUniMessageTypeLocking MessageTypeLocking() const; + + /** + * Mutator for message type locking + * @param aLocking Message type locking + */ + virtual void SetMessageTypeLocking( TUniMessageTypeLocking aLocking ); + + /** + * Accessor for message root + * @return Message root + */ + virtual TMsvAttachmentId MessageRoot() const; + + /** + * Mutator for message root + * @param aLocking Message root + */ + virtual void SetMessageRoot( TMsvAttachmentId aRoot ); + + /** + * From CBaseMtm: Store current entry data. + * The caller must set the message to complete and visible when it is ready. + */ + virtual void SaveMessageL( CMsvStore& aEditStore, TMsvEntry& aEntry ); + + public: // FUNCTIONS FROM BASE CLASSES + + /** + * From CBaseMtm: Return type of this Mtm + * @return Registered Mtm type + */ + inline TUid Type() const; + + // Context specific functions + + /** + * From CBaseMtm: Set current context + * @param aEntry Pointer to entry instance + */ + inline void SetCurrentEntryL( CMsvEntry* aEntry ); + + /** + * From CBaseMtm: Switch context to entry defined by aId. + * @param aId Entry id in message store. + */ + inline void SwitchCurrentEntryL( TMsvId aId ); + + /** + * From CBaseMtm: return reference to current entry + * @return reference to entry instance + */ + inline CMsvEntry& Entry() const; + + /** + * From CBaseMtm: Query if entry context has been set + * @return ETrue, if context has been set, EFalse, if not + */ + inline TBool HasContext() const; + + // Message specific functions + + /** + * From CBaseMtm: Store current entry data. + * The caller must set the message to complete and visible when it is ready. + */ + void SaveMessageL(); + + /** + * From CBaseMtm: Restore current entry data. + */ + void LoadMessageL(); + + /** + * From CBaseMtm: Validates that selected parts of current message are + * legal. + * @param aPartList Flags specifying which parts to validate. + * (defined in MTMDEF.H). + * KMsvMessagePartPartBody is ignored. + * KMsvMessagePartRecipient is supported. + * KMsvMessagePartOriginator is supported. + * KMsvMessagePartDescription is ignored. + * KMsvMessagePartDate is ignored. + * KMsvMessagePartAttachments is supported. + * @return Flags that specify which or the specified parts were valid. + */ + TMsvPartList ValidateMessage( TMsvPartList aPartList ); + + /** + * From CBaseMtm: Searches for specified text in selected parts of + * current message. + * @param aPartList Flags specifying which parts to search. + * (defined in MTMDEF.H). + * KMsvMessagePartPartBody is ignored. + * KMsvMessagePartRecipient is supported. + * KMsvMessagePartOriginator is supported. + * KMsvMessagePartDescription is supported. + * KMsvMessagePartDate is ignored. + * KMsvMessagePartAttachments is ignored. + * Following find attributes are supported: + * KMsvFindCaseSensitive + * KMsvFindWholeWord + * @return Flags that specify in which of the specified parts the text + * was found. + */ + TMsvPartList Find( const TDesC& aTextToFind, TMsvPartList aPartList ); + + /** + * From CBaseMtm + * Not supported. + * @leave KErrNotSupported + */ + CMsvOperation* ReplyL( + TMsvId aDestination, + TMsvPartList aPartlist, + TRequestStatus& aCompletionStatus ); + + /** + * From CBaseMtm + * Not supported. + * @leave KErrNotSupported + */ + CMsvOperation* ForwardL( + TMsvId aDestination, + TMsvPartList aPartList, + TRequestStatus& aCompletionStatus ); + + /** + * From CBaseMtm: Adds an addressee. Cannot distiguish To, Cc, and Bcc. + * New addresses are handled as To type of addresses. + * @param aRealAddress Reference to an address string + */ + void AddAddresseeL( const TDesC& aRealAddress ); + + /** + * From CBaseMtm: Adds an addressee. Cannot distiguish To, Cc, and Bcc. + * New addresses are handled as To type of addresses. + * @param aRealAddress Reference to an address string + * @param aAlias Reference to a descriptive name (not a real address) + */ + void AddAddresseeL( const TDesC& aRealAddress, const TDesC& aAlias ); + + /** + * From CBaseMtm: Adds a typed addressee (To, Cc or Bcc ) + * @param aType recipient type (EMsvRecipientTo, EMsvRecipientCc, + * or EMsvRecipientBcc) + * @param aRealAddress Reference to an address string + */ + virtual void AddAddresseeL( + TMsvRecipientType aType, + const TDesC& aRealAddress); + + /** + * From CBaseMtm: Adds a typed addressee (To, Cc or Bcc ) + * @param aType recipient type (EMsvRecipientTo, EMsvRecipientCc, + * or EMsvRecipientBcc) + * @param aRealAddress Reference to an address string + * @param aAlias Reference to a descriptive name (not a real address) + */ + virtual void AddAddresseeL( + TMsvRecipientType aType, + const TDesC& aRealAddress, + const TDesC& aAlias); + + /** + * From CBaseMtm: Removes an entry from addressee list. + * Cannot distinguish To, Cc and Bcc. + * @param aIndex Index to the array of addresses. + */ + void RemoveAddressee( TInt aIndex ); + + /** + * From CBaseMtm Rich text body accessor + * @return reference to the rich text body + */ + inline CRichText& Body(); + + /** + * From CBaseMtm Rich text body accessor + * @return reference to the rich text body + */ + inline const CRichText& Body() const; + + /** + * From CBaseMtm: Sets the message subject + * @param aSubject Subject as text string. + */ + void SetSubjectL( const TDesC& aSubject ); + + /** + * From CBaseMtm: Subject accessor + * @return Constant pointer descriptor pointing to subject + */ + const TPtrC SubjectL() const; + + // General MTM-specific functionality + + /** + * From CBaseMtm: + * @param aCapability Uid specifying which capablity is queried + * @param aResponse reference to an integer that will contain the value + * describing the capability at return. + * @return error code, KErrNone, if specified capability is known + * to Mtm, + * KErrNotSupported, if capability Uid is unknown + */ + TInt QueryCapability( TUid aCapability, TInt& aResponse ); + + /** + * From CBaseMtm + * Not supported. + * @leave KErrNotSupported + */ + void InvokeSyncFunctionL( + TInt aFunctionId, + const CMsvEntrySelection& aSelection, + TDes8& aParameter ); + + /** + * From CBaseMtm + * Not supported. + * Returns operation with status: KErrNotSupported + */ + CMsvOperation* InvokeAsyncFunctionL( + TInt aFunctionId, + const CMsvEntrySelection& aSelection, + TDes8& aParameter, + TRequestStatus& aCompletionStatus ); + + /** + * From CBaseMtm: Return session that was set at initialization + * @return Reference to session object + */ + inline CMsvSession& Session(); + + // Functions for SendAs support + // These functions get the edit store from the current entry. + // The caller should not hold the store open. + // The store is committed and closed after each operation + + /** + * From CBaseMtm Adds a file attachment to the current message entry. + * The attachment is referenced by its file path and is copied into the + * message store. + * Only one asynchronous operation can be run at any one time. + * @param aFilePath The full path specification of the attachment file. + * @param aMimeType The mime type of the attachment file. + * @param aCharset The character set in case the attachment is of text type + * if not relevant for current attachment type, set aCharset to 0 + * @param aStatus The request status to complete. + * @leave System-wide error codes. + */ + void AddAttachmentL( const TDesC& aFilePath, + const TDesC8& aMimeType, + TUint aCharset, + TRequestStatus& aStatus ); + + /** + * From CBaseMtm Adds a file attachment to the current message entry. + * The attachment is referenced by an open file handle and is copied + * into the message store. + * Only one asynchronous operation can be run at any one time. + * @param aFile An open file handle for the file attachment. + * The function closes the file handle when done. + * The caller should not attempt to close the handle afterwards + * Use as follows: + * CleanupStack::CleanupClosePush( aFile ); + * AddAttachmentL( aFile, ... ); + * CleanupStack::Pop(); // get handle off cleanup stack + * @param aMimeType The mime type of the attachment file. + * @param aCharset The character set in case the attachment is of text type + * if not relevant for current attachment type, set aCharset to 0 + * @param aStatus The request status to complete. + * @leave System-wide error codes. + */ + void AddAttachmentL( RFile& aFile, + const TDesC8& aMimeType, + TUint aCharset, + TRequestStatus& aStatus ); + + /** + * From CBaseMtm Adds a file attachment to the current message entry + * as a linked file. + * The attachment is referenced by its file path and is not copied + * into the message store. The attachment file is always used from + * its original location on disk indicated by the aFilePath + * parameter. Only one asynchronous operation can be run at any + * one time. + * @param aFilePath The full path specification of the attachment file. + * @param aMimeType The mime type of the attachment file. + * @param aCharset The character set in case the attachment is of text type + * if not relevant for current attachment type, set aCharset to 0 + * @param aStatus The request status to complete. + * @leave System-wide error codes. + */ + void AddLinkedAttachmentL( const TDesC& aFilePath, + const TDesC8& aMimeType, + TUint aCharset, + TRequestStatus& aStatus ); + + /** + * From CBaseMtm + * Not supported. + * @leave KErrNotSupported + */ + void AddEntryAsAttachmentL( TMsvId aAttachmentId, + TRequestStatus& aStatus ); + + /** + * From CBaseMtm + * @param aFileName suggested filename + * @param aAttachmentFile An open file handle for the file attachment. + * @param aMimeType The mime type of the attachment file. + * @param aCharset The character set in case the attachment is of text type + * if not relevant for current attachment type, set aCharset to 0 + * @param aStatus The request status to complete. + * @leave System-wide error codes. + */ + void CreateAttachmentL( const TDesC& aFileName, + RFile& aAttachmentFile, + const TDesC8& aMimeType, + TUint aCharset, + TRequestStatus& aStatus); + + /** + * From CBaseMtm Cancels the current attachment operation. + */ + void CancelAttachmentOperation(); + + // End of attachment funtions to support SendAs + + /** + * From CBaseMtm: Create an empty entry in the outbox
+ * and set it as current context.
+ * The entry will be invisible and under construction. + * @param aServiceId Service id for the new entry. + */ + void CreateMessageL( TMsvId aServiceId ); + + /** + * From CBaseMtm:BIO functions to support the SendAs API. + * The function is not supported. + * Entry().Entry().iBioType will be set by SendAs if this function does + * not leave. + * The default implementation in CBaseMtm is to do nothing. + */ + void BioTypeChangedL( TUid aBioTypeUid ); + + /** + * From CBaseMtm: Return id of default service. + * @return default service + */ + TMsvId DefaultServiceL() const; + + /** + * From CBaseMtm: Remove default service + * Does nothing. Deletion of service not supported + */ + void RemoveDefaultServiceL(); + + /** + * From CBaseMtm: Change default service + * Does nothing. Changing of default service not supported + */ + void ChangeDefaultServiceL(const TMsvId& aService); + + protected: // New functions + + + protected: // Functions from base classes + + /** + * From CBaseMtm: Called after the context of this instance + * has been changed to another entry. + */ + void ContextEntrySwitched(); + + /** + * From CBaseMtm: React to changes + * This functions does not do anything. + * @param aEvent Code that tells which event has occurred. + * Event codes defined in MSVAPI.H + * @param arg1 Depends on Event + * @param arg2 Depends on Event + * @param arg3 Depends on Event + */ + void HandleEntryEventL( + TMsvEntryEvent aEvent, + TAny* arg1, + TAny* arg2, + TAny* arg3 ); + + /** + * By default Symbian OS constructor is private. + * @param aRegisteredMtmDll Reference to Mtm Dll registry class + * @param aSession Reference to a Message Server session. + */ + CUniClientMtm( + CRegisteredMtmDll& aRegisteredMtmDll, + CMsvSession& aSession ); + + void ConstructL(); + + private: + + /** + * This method builds the iAddresseeList from the iUniHeaders data. + */ + void BuildAddresseeListL(); + + /** + * This methods adds entries from the the specified array to + * iAddresseeList. + * @param aArray recipient array. + */ + void BuildAddresseeListL( + const CDesCArray& aArray, TMsvRecipientType aValue); + + /** + * Attachments size + * @return size of all attachments, binary data + mime headers. + */ + TInt32 AttachmentsSizeL(); + + /** + * Attachments size + * @return size of all attachments, binary data + mime headers. + */ + TInt32 AttachmentsSizeL( CMsvStore& aStore ); + + /** + * Find text from the given recipient list. + * @param aTextToFind a text to be searched + * @param aPartList message part list + * @param aRecipients the recipient list + * @param aFindText CMsvFindText object to help in the find + * @return ETrue if match found. + */ + TBool FindInRecipientL( + const TDesC& aTextToFind, + TMsvPartList aPartlist, + const CDesCArray& aRecipients, + CMsvFindText& aFindText ); + + /** + * Add an attachment from public location either as copied file or + * linked file. + * @param aFilePath The full path specification of the attachment file. + * @param aMimeType The mime type of the attachment file. + * @param aType CMsvAttachment::EMsvFile or + * CMsvAttachment::EMsvLinkedFile + * @param aStatus The request status to complete when request has + * completed. + * @param aCharacter set IANA MIBEnum of the character set for the + * attachment if needed. + */ + void AddFilePathAttachmentL(const TDesC& aFilePath, + const TDesC8& aMimeType, + CMsvAttachment::TMsvAttachmentType aType, + TRequestStatus& aStatus, + const TUint aCharacterSet = 0 ); + + /** + * Tries to recognize character set of the given file. + * @since 3.0 + * @param aFile IN File to be recognized + * @return MIB id of the character set + */ + TUint RecognizeCharSetL( RFile& aFile ); + + /** + * Sets the needed data fields for CMsvAttachment. + * Creates and initializes CMsvMimeHeaders for the attachment. + * + * @return Size of the mime headers in bytes + */ + TInt InitializeAttachmentL( + MMsvAttachmentManager& aManager, + CMsvAttachment& aAttachment, + const TDesC& aFileName, + const TDesC8& aMimeType, + TInt aFileSize, + TUint aCharset ); + + /** + * Sets the content location mime header. + * This function needs to be called when attachments have been converted + * from ucs-2 to utf8. + * Other mime headers have been correctly set by the conversion routine + * + * @param aStore edit store + * @param aAttaId attchement if for the attachment to be handled + * @param aFilename suggested filename + */ + void SetContentLocationForConvertedAttL( + CMsvStore& aStore, + TMsvAttachmentId aAttaId, + const TDesC& aFileName ); + + + /** + * See function Find. DoFind is called in TRAP in Find function. + */ + TMsvPartList DoFindL( const TDesC& aTextToFind, TMsvPartList aPartList ); + + + + public: // Data + + protected: // Data + + CUniHeaders* iUniHeaders; // Unified message headers + TInt iMessageDrive; // messages are on C: drive by default, + // may be moved to other drive + CMsgTextUtils* iTextUtils; + + private: // Data + // active object that commits the store when attachment operation + // is complete + CMmsAttachmentWaiter* iAttaWaiter; + + public: // Friend classes + + protected: // Friend classes + + private: // Friend classes + + }; + +#include "UniClientMtm.inl" + +#endif // __UNICLIENTMTM_H__ + +// End of File +