/*

* 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  <mtclbase.h> // base client mtm

#include  <e32std.h>   // 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.<br>

        * 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.

        *

        * <PRE>

        * 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;

        * </PRE>

        */

        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. <br>

        * 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();