/*

* Copyright (c) 2002-2006 Nokia Corporation and/or its subsidiary(-ies).

* All rights reserved.

* This component and the accompanying materials are made available

* which accompanies this distribution, and is available

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:  

*     Client Mtm for multimedia messaging.

*     This is the API for accessing multimedia messaging engine.

*

*/

#ifndef MMSCLIENT_H

#define MMSCLIENT_H

//  INCLUDES

#include  <mtclbase.h> // base client mtm

#include  <e32std.h>   // TTimeInterval & TTime

#include  "mmsconst.h" // common constants

// CONSTANTS

// MACROS

// DATA TYPES

typedef struct

    {

    const TUint SymbianCharsetUID;

    const TUint IANAMIBEnum;

    }TMmsCharacterSetLookup;

// FUNCTION PROTOTYPES

// FORWARD DECLARATIONS

class CMmsSettings;

class CMmsHeaders;

class CMsvMimeHeaders;

class CMsvFindText;

class CMmsAttachmentWaiter;

// CLASS DECLARATION

/**

*  Client Mtm for multimedia messaging subsystem. 

*

*  This class will be the interface to the UI component and other 

*  messaging component that might want to handle multimedia messages 

*  (For example SendAs interface).

* 

*  This class provides access to MMS specific headers in the message.

*

*  Note: new functions are added as the last virtual functions in order

*  not to to break the vtable

*

* @code

*  // Example of getting access to this class:

*

*  // Called by an application that implements

*  // MMsvSessionObserver interface

*

*  iSession = CMsvSession::OpenSyncL(*this);

*  CleanupStack::PushL(iSession);

*  iClientMtmRegistry = CClientMtmRegistry::NewL(*iSession);

*  CleanupStack::PushL(iClientMtmRegistry);

*  iMmsClient = (CMmsClientMtm *) iClientMtmRegistry->

*               NewMtmL(KUidMsgTypeMultimedia);

*  CleanupStack::PushL(iMmsClient);

*

*  // - do other initialization

*

*  CleanupStack::Pop(3); //iSession, iClientMtmRegistry, iMmsClient

*

*  // - call any public functions in CMmsClientMtm

*

*  // When the application finishes,

*  // it must delete the objects in reverse order:

*  delete iMmsClient;

*  delete iClientMtmRegistry;

*  delete iSession;

* @endcode

*/

class CMmsClientMtm :public CBaseMtm

    {

    public:  // Constructors and destructor

        /**

        * 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[in] aRegisteredMtmDll Mtm Dll registry class

        * @param[in] aSession Message Server session.

        * @return Pointer to CMmsClientMtm class.

        */

        IMPORT_C static CMmsClientMtm* NewL(

            CRegisteredMtmDll& aRegisteredMtmDll,

            CMsvSession& aSession );

        /**

        * Destructor.

        */

        virtual ~CMmsClientMtm();

    public:  // New functions

        // ----------------------------------------------------------

        // Functions to create and modify message entries

        /**

        * Create a new message entry.

        *

        * @param[in] aDestination Target folder.

        * @param[in] aCompletionStatus Reference to the status of an active object. 

        *     This status will contain the relevant error code when the operation 

        *     completes.

        * @return Pointer to a message server operation (active object). 

        *     When the message has been created the progress information of the 

        *     operation provides the id of the created message in an 8-bit package 

        *     buffer. While the operation is in progress the package will contain a 

        *     null id (KMsvNullIndexEntryId). If there is an error while 

        *     creating the message the message will be deleted and the 

        *     package will contain a null id.

        *

        * This function is suitable when the caller is an active object or the 

        * caller does not want to immediately change current context to the 

        * new message entry.

        *

        * If the caller is not an active object and the caller wants the context 

        * of CMmsClientMtm to be immediately set to the new entry, it is simpler 

        * to call CreateMessageL.

        * @see CMmsClientMtm::CreateMessageL

        *

        * @code

        * // This example shows usage with a caller that is not an active object,

        * // so a separate waiter is needed. If the caller is an active object,

        * // the caller gives its own status to the function and continues 

        * // execution in RunL function.

        *

        * CMsvOperation* myOperation = NULL;

        * CMsvOperationActiveSchedulerWait* wait = 

        *     CMsvOperationActiveSchedulerWait::NewLC();

        *

        * // destinationId specifies the destination folder.

        * myOperation = iMmsClient->CreateNewEntryL( destinationId, wait->iStatus );

        *

        * CleanupStack::PushL( myOperation );

        *

        * wait->Start();

        *

        * if ( wait->iStatus.Int() != KErrNone )

        *     { 

        *     // error handling, e.g. leave

        *     }

        *

        * // Get the message id

        * TPckgBuf<TMsvId> pkg;

        * pkg.Copy( myOperation->ProgressL() );

        * TMsvId progress = pkg();

        * CleanupStack::PopAndDestroy(2); // myOperation, wait;

        *

        * // Load the new message

        * iMmsClient->SwitchCurrentEntryL( progress );

        *

        * // load the default values that were already intialized

        * // when the message was created 

        * iMmsClient->LoadMessageL();

        * 

        * // continue adding data to the message

        * // ...

        * @endcode

        */

        virtual CMsvOperation* CreateNewEntryL(

            TMsvId aDestination,

            TRequestStatus& aCompletionStatus);

        // -------------------------------------------------------------------

        // FUNCTIONS TO HANDLE MMSC SETTINGS

        //

        // Only one MMS service entry may be created!

        //

        // The Client MTM maintains cached MMS service settings, referred to 

        // as current service below. Some of those cached settings are used 

        // as template values when a new multimedia message is created. 

        //

        // Use Base MTM functions to get default service id.

// <DEPRECATED>

        /**

        * Create new service entry.

        *

        * Context is set to the new service entry. 

        * Currently a maximum of one service is created, and further requests 

        * do not create a new service entry.

        * @deprecated Only one MMS service is supported and it is automatically created. 

        * Use DefaultServiceL() to get the id for the default service.

        */

        virtual void CreateServiceL();

// </DEPRECATED>

        // Functions to load, save, and access MMS Settings.

        // There is no need to change the context when these functions are used.

        //

        /**

        * Get a reference to CMmsSettings class.

        *

        * This method should be used by MMS UI only. Other applications should 

        * not touch the MMS settings. The methods are needed in MMS Client API 

        * to allow MMS UI to inform MMS Client MTM about changed settings. 

        *

        * The contents of the class are those used by MMS Client MTM 

        * when constructing a message. If the settings must be changed, 

        * a copy must be made, and SetSettingsL function used to deliver 

        * the settings to MMS Client MTM.

        *

        * @return constant reference to iMmsSettings member of CMmsClientMtm.

        *

        * @code

        * // Usage:

        * 

        * CMmsSettings* settings = CMmsSettings::NewL();

        * CleanupStack::PushL( settings );

        * iMmsClient->RestoreSettingsL();

        * settings->CopyL( iMmsClient->MmsSettings() );

        * 

        * // change settings here...

        * // The settings are changed using CMmsSettings API

        * 

        * iMmsClient->SetSettingsL( *settings );

        * iMmsClient->StoreSettingsL();

        * CleanupStack::PopAndDestroy(); // settings

        *

        * @endcode

        */

        virtual const CMmsSettings& MmsSettings();

        /**

        * Copy the values from aSettings to CMmsClientMtm.

        *

        * This method should be used by MMS UI only. Other applications should 

        * not touch the MMS settings. 

        *

        * Used to provide new settings to MMS Client MTM when settings have 

        * been changed. Will affect only messages created after the settings  

        * have been changed. 

        *

        * Use function StoreSettingsL to save the settings on disk.

        *

        * @param[in] aSettings New values for CMmsSettings

        */

        virtual void SetSettingsL( const CMmsSettings& aSettings );

        /**

        * Save settings to disk.

        *

        * This method should be used by MMS UI only. Other applications should 

        * not touch the MMS settings. 

        */

        virtual void StoreSettingsL();

        /**

        * Load settings from disk.

        *

        * This method should be used by MMS UI only. Other applications should 

        * not touch the MMS settings.

        */

        virtual void RestoreSettingsL();

// <DEPRECATED>

        /**

        * Restore factory settings.

        *

        * Restore settings from ROM to the default service entry and select it 

        * as the current service entry.

        * @param aLevel Defines the operations to be done. 

        * @deprecated MMS UI should restore the factory settings directly.

        */

        virtual void RestoreFactorySettingsL(

            TMmsFactorySettingsLevel aLevel = EMmsFactorySettingsLevelNormal );

// </DEPRECATED>

        /**

        * Validate service.

        *

        * Checks that access point refers to a valid entry in comms database.

        *

        * @param[in] aServiceId Id of the MMS service

        * @return Error code. 

        * - KErrNone: The service is OK.

        * - KErrNotFound: The service id is incorrect.

        * - KMmsErrorInvalidSettings: The settings contain invalid values. 

        * This error is possible only if the settings file has been corrupted.

        * - KMmsErrorNoWAPAccessPoint: No access point has been defined.

        * - KMmsErrorAP1Invalid: MMS access point refers to an invalid entry in comms 

        * database.

        * - KMmsErrorNoURI1: Home page has not been defined for MMS access point

        */

        virtual TInt ValidateService( TMsvId aServiceId );

        // -------------------------------------------------------------------

        // FUNCTIONS TO HANDLE MMS HEADERS

        // Accessors and mutators (getters and setters) for header fields.

        // Some of these header fields have default values that are assigned

        // from cached service settings when a new header is allocated.

        // Some header fields are needed by protocol only.

        // Those headers don't have accessors and mutators here,

        // as they are used by Server MTM who accesses them directly

        // through functions offered by CMmsHeaders.

        /**

        * Set the sender of the message.

        *

        * If the sender of the message is not explicitly defined, the Proxy-Relay 

        *     or MMS Service Centre will add the sender's phone number.

        *

        * @param[in] aAlias The phone number of the sender of the message. 

        *     Maximum length 256 characters. This string will be included 

        *     as the sender of the message when the message is sent, but 

        *     the MMS Service Centre will check the validity of the 

        *     value and replace it with the actual phone number of the 

        *     sender if it is not correct.

        */

        virtual void SetSenderL( const TDesC& aAlias );

        /**

        * Get the sender of the message.

        *

        * @return Address of the sender of the message (for example phone number). 

        *     If the sender has not been defined, returns an empty string.

        */

        virtual const TPtrC Sender() const;

        /**

        * Set the message class.

        *

        * If message class is not explicitly set, the message will have 

        *     class "Personal" by default.

        *

        * @param [in] aMessageClass Message class code. Possible values: 

        * - EMmsClassPersonal: Message is a normal person-to-person message (default).

        * - EMmsClassAdvertisement: Message contains an advertisement.

        * - EMmsClassInformational: Message contains data from an information service.

        * - EMmsClassAuto: Message has been automatically generated by the phone. 

        *   This class is only valid for a message that is a read report to another message.

        */

        virtual void SetMessageClass( TMmsMessageClass aMessageClass );

        /**

        * Get the message class.

        *

        * @return Message class. Possible values: 

        * - EMmsClassPersonal: Message is a normal person-to-person message (default).

        * - EMmsClassAdvertisement: Message contains an advertisement.

        * - EMmsClassInformational: Message contains data from an information service.

        * - EMmsClassAuto: Message has been automatically generated by the phone. 

        *   This class is only valid for a message that is a read report to another message.

        * - 0: Message class has not been defined. Handle as EMmsClassPersonal.

        */

        virtual TInt MessageClass() const;

        /**

        * Set the validity period of the message.

        *

        * If the validity period is not defined for the message, default 

        * validity period from MMS settings or MMS Service Centre will be used.

        *

        * @param[in] aInterval The length of time in seconds after which the 

        *     message will be discarded by MMS Service Centre. 

        *     MMSC may limit the maximum length of the validity period. 

        */

        virtual void SetExpiryInterval( TTimeIntervalSeconds aInterval );

        /**

        * Get the validity period of the message.

        *

        * @return Storage time of the message in MMS Service Centre (in seconds). 

        *     If the message cannot be delivered to the recipient within the 

        *     validity period, it will be discarded. If the validity period is 0, 

        *     it has not been defined.

        */

        virtual TTimeIntervalSeconds ExpiryInterval() const;

        /**

        * Set the expiration date of the message.

        *

        * @param[in] aDate The date and time when the message will expire 

        *     (In UTC time). The date must be later than 1970-01-01, 00:00:00 GMT 

        *     If the MMS Service Centre cannot deliver the message to the recipient 

        *     before the expiration date, the message will be discarded. If expiration 

        *     date or validity period have not been defined, default is used.

        */

        virtual void SetExpiryDate( TTime aDate );

        /**

        * Get the expiration date of the message.

        *

        * @return The date and time when the message will expire. (in UTC time). 

        *      If the expiration date has not been defined, TTime(0) will be 

        *      returned.

        */

        virtual TTime ExpiryDate() const;

        /**

        * Set the delivery time interval for the message.

        *

        * @param[in] aInterval The length of time in seconds after which the message 

        *     will be delivered to the recipient by the MMS Service Centre. 

        *     If neither delivery time interval or delivery date have been defined,

        *     MMS Service Centre will deliver the message immediately.

        */

        virtual void SetDeliveryTimeInterval( TTimeIntervalSeconds aInterval );

        /**

        * Get the delivery time interval of the message.

        *

        * @return The length of time in seconds after which the message will be 

        *     delivered to the recipient by MMS Service Centre. If the delivery 

        *     time interval is 0, it has not been defined.

        */

        virtual TTimeIntervalSeconds DeliveryTimeInterval() const;

        /**

        * Set the delivery date for the message.

        *

        * @param[in] aDate The date and time when the message will be delivered 

        *     to the recipient by the MMSC (in UTC time). The date must be 

        *     later than 1970-01-01, 00:00:00 GMT. If neither delivery time 

        *     interval or delivery date have been defined, MMS Service Centre 

        *     will deliver the message immediately.

        */

        virtual void SetDeliveryDate( TTime aDate );

        /**

        * Get the delivery date of the message.

        *

        * @return The date and time when the message will be (or was) delivered 

        *     to the  recipient by the MMSC (in UTC time). If the delivery date 

        *     has not been defined, TTime(0) is returned.

        */

        virtual TTime DeliveryDate() const;

        /**

        * Set the priority of the message. 

        *

        * If the priority of the message is not set, the default priority will be 

        *     "normal".

        *

        * @param[in] aPriority Message priority, possible values:

        * - EMmsPriorityLow:     Low priority.

        * - EMmsPriorityNormal:  Normal priority.

        * - EMmsPriorityHigh:    High priority.

        */

        virtual void SetMessagePriority( TMmsMessagePriority aPriority );

        /**

        * Get the priority of the message.

        *

        * @return Message priority, possible values:

        * - EMmsPriorityLow:     Low priority.

        * - EMmsPriorityNormal:  Normal priority.

        * - EMmsPriorityHigh:    High priority.

        * - 0: Priority has not been defined, treat as EMmsPriorityNormal

        */

        virtual TInt MessagePriority() const;

        /**

        * Set the sender visibility setting for the message.

        *

        * Indicates whether the MMS Service Centre should hide the sender's phone 

        *     number from the recipient. If the value is not defined, default is 

        *     used. The default is to show the sender's number unless the sender 

        *     has a secret number.

        *

        * @param[in] aVisibility Visibility of the sender's phone number to the 

        *    recipient. Possible values:

        * - EMmsSenderVisibilityDefault: Use default visibility.

        * - EMmsSenderVisibilityHide: Hide the sender's number.

        * - EMmsSenderVisibilityShow: Show the sender's number even if it is a 

        *     secret number.

        */

        virtual void SetSenderVisibility(