/*

* Copyright (c) 2002-2006 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 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(

            TMmsMessageSenderVisibility aVisibility );

        /**

        * Get the sender visibility setting of the message.

        *

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

        *     number from the recipient. The default is show the sender's number 

        *     unless the server has a secret number.

        *

        * @return visibility setting. Possible values:

        * - EMmsSenderVisibilityDefault: Default visibility.

        * - EMmsSenderVisibilityHide: Hide the sender's number.

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

        *     secret number.

        * - 0: Sender visibilty has not been defined, use default.

        */

        virtual TInt SenderVisibility() const;

        /**

        * Set the delivery report request setting value for the message.

        *

        * If the value is not set, default value from MMS settings will be used.

        *

        * @param[in] aRequest tells if the user wants a delivery report for this 

        *    message. Possible values: 

        * - EMmsYes: The user wants a delivery report.

        * - EMmsNo:  The user does not want a delivery report.

        */

        virtual void SetDeliveryReport(

            TMmsYesNo aRequest );

        /**

        * Get the delivery report request setting of the message.

        *

        * If the value is not defined, default value from MMS settings is used.

        *

        * @return delivery report request setting. Possible values: 

        * - EMmsYes: The user wants a delivery report.

        * - EMmsNo:  The user does not want a delivery report.

        * - 0: Setting has not been defined.

        */

        virtual TInt DeliveryReport() const;

        /**

        * Set the read report request setting value for the message.

        *

        * Specifies if the user wants a read report for the current message. 

        * If this value is Yes, the recipient phone should send a read report  

        *    when the user opens the message for the first time.

        *

        * @param[in] aRequest read report request setting. Possible values:

        * - EMmsYes: The user wants a read report.

        * - EMmsNo:  The user does not want a read report.

        */

        virtual void SetReadReply( TMmsYesNo aRequest );

        /**

        * Get the read report request setting of the message.

        *

        * Specifies if the sender wants a read report for current message. 

        * If this value is yes and the message has been received by the phone 

        *     (has "KMmsMessageMobileTerminated" flag) a read report should be 

        *     sent to the sender of this message when the message is opened 

        *     for the first time.

        *

        * @return read report request setting. Possible values:

        * - EMmsYes: The user wants a read report.

        * - EMmsNo:  The user does not want a read report.

        * - 0: Setting has not been defined. Do not send a read report.

        */

        virtual TInt ReadReply() const;

        /**

        * Get the sending date and time of the message. 

        * Valid only for messages received by the phone.

        * @return the time when MMS Service Centre has received the message  

        *     from sender (in UTC time). 

        *     If the time has not been defined, returns TTime(0).

        */

        virtual TTime SendingDate() const;

        /**

        * Get the response text from the message.

        *

        * Valid only in cases a response text has been obtained from MMS Service 

        *     Centre. Possible cases are received messages and messages whose 

        *     senging has failed. The text may explain the cause of the failure.

        *

        * @return Response text string. If text is not defined, returns an empty 

        *     string.

        * @since 2.0

        */

        virtual TPtrC ResponseText() const;

        /**

        * Get the response status value from the message.

        *

        * This function returns the status MMS Service Centre has sent with a 

        *     retrieved message or as a response to a failure to send a message. 

        * The status code may be used in case of permanent failures to retrieve 

        *     or failures to send to indicate the reason of the failure.

        *

        * @return Status code sent by MMS Service Centre. Possible values are 

        *     defined in OMA MMS Encapsulations specifications, and depend on 

        *     the version of the MMS Service Centre sending the response. 

        * - Error codes 128 - 136 denote legacy errors from MMS encapsulation 

        *     version 1.0

        * - Error codes 192 - 223 denote transient failures.

        * - Error codes 224 - 255 denote permanent failures.

        * - 0 means the response status has not been set. Either the operation was 

        *     successful or the cause of the failure was not set by MMS Service Centre.

        * @since 3.0

        */

        virtual TInt ResponseStatus() const;

        /**

        * Get number of times the message has been forwarded.

        *

        * Returns the number of previous senders in case of a message that 

        *     has been forwarded from one terminal to another based on the 

        *     MMS notification only without retrieving the actual message to 

        *     the terminal first.

        *

        * @return Number of times the message has been forwarded.

        * @since 3.0

        */

        virtual TInt NumberOfPreviousSenders() const;

        /**

        * Get the address of a previous sender.

        *

        * The addresses of the previous senders are defined for messages that 

        *     have been forwarded without fetching them to the terminal first.

        *

        * @param[in] aSequenceNumber Indicates the number of the sender in the 

        *     sequence. 1 is the first sender, a higher number indicates a later 

        *     sender.

        * @return Address of the specified previous sender. If the sequence number 

        *     exceeds the number of senders or is less than 1, an empty string is 

        *     returned.

        * @since 3.0

        */

        virtual TPtrC PreviousSender( TInt aSequenceNumber ) const;

        /**

        * Get the time when the message was previously sent (in UTC time).

        *

        * The function is valid only for messages that have been forwarded 

        *     without fetching them to the terminal first.

        *

        * @param[in] aSequenceNumber Indicates the number of the sender in the 

        *     sequence. 1 is the first sender, a higher number indicates a later 

        *     sender.

        * @return Time of the previous sending (in UTC time). If the sequence 

        *     number exceeds the number of senders or is less than 1, TTime(0)  

        *     is returned.

        * @since 3.0

        */

        virtual TTime PreviousSendingDate( TInt aSequenceNumber ) const;

        /**

        * Get the time when the message was received in the terminal.

        *

        * @return Time of the arrival of the message (in UTC time). 

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

        * @since 3.0

        */

        virtual TTime MessageReceiveTime() const;

        /**

        * Get the incoming message size.

        *

        * This is valid only for a notification.

        *

        * @return Message size in octets as specified in MMS Notification.

        */

        virtual TInt MessageTransferSize() const;

        /**

        * Get the Uri from which the message can be fetched.

        *

        * This is valid only for a nofification.

        *

        * @return Content location of the actual message, the Uri from which 

        *    the message is fetched from MMS Service Centre.

        */

        virtual TPtrC8 MessageContentLocation() const;

        /**

        * Set id of the root part of the message.

        *

        * @param[in] aId Attachment Id of the message part which controls the 

        *     display of the message. Should point to the SMIL part if present.

        */

        virtual void SetMessageRootL( const TMsvAttachmentId aId );

        /**

        * Get the id of the root part of the message.

        *

        * @return Id of the attachment that starts the message display, 

        * KMsvNullIndexEntryId if the root part has not been defined.

        */

        virtual TMsvAttachmentId MessageRootAttachment() const;

        /**

        * Set the maximum size of the images that can be inserted in the message.

        *

        * @param[in] aHeight Image height in pixels.

        * @param[in] aWidth Image width in pixels.

        */

        virtual void SetMaximumImage( TInt aWidth, TInt aHeight );

        /**

        * Get the maximum size of the images that can be inserted in the message.

        *

        * The returned values are 0 if the maximum values have not been defined.

        * @param[out] aHeight image height in pixels

        * @param[out] aWidth image width in pixels

        */

        virtual void GetMaximumImage( TInt& aWidth, TInt& aHeight ) const;

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

        // GENERAL MESSAGE INFORMATION METHODS

        /**

        * Get the message size. 

        *

        * SaveMessageL and LoadMessageL updates the value. This function returns 

        * the total amount of disk space the message takes. The actual message 

        * size in transmission is smaller due to binary encoding of the headers.

        *

        * @return size of all message parts in bytes including both attachments 

        *     and internal header structures.

        */

        virtual TInt32 MessageSize();

        /**

        * Set the message description string.

        * 

        * This provides a method to override the default message description. 

        * The next SaveMessageL saves the description text in the 

        * TMsvEntry::iDescription field. This field is shown in Message Centre  

        * message lists to describe the contents of the message. Normally it is  

        * the message subject, but if there is no subject in the message, the 

        * caller may set some text from a text part of the message as the 

        * description. 

        *

        * Note that this method does not check the text length, so avoid long 

        * descriptions to minimize memory usage.

        *

        * @param[in] aText Message description

        */

        virtual void SetMessageDescriptionL( const TDesC& aText );

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

        // FUNCTIONS TO HANDLE EXTRA MESSAGE ATTRIBUTES (FOR UI USE ONLY)

        /**

        * Add attribute to an attribute array (for the use of MMS UI only).

        *

        * No duplicates are allowed. If an attribute exists, its value is changed. 

        * The attributes and their values can be arbitrary strings. There are no 

        * restrictions. The purpose is to allow the UI to store some extra 

        * information with the message. The values of the attibutes are not included 

        * when the message is sent.

        * @param[in] aName Name of the attribute (case sensitive).

        * @param[in] aValue Value of the attribute.

        *

        * @leave KErrArgument if length of aName or aValue is 0.

        * @leave KErrNoMemory if memory runs out while adding the attribute.

        */

        virtual void AddAttributeL( const TDesC& aName, const TDesC& aValue );

        /**

        * Get value of an attribute (for the use of MMS UI only).

        *

        * @param[in] aName Name of the attribute (case sensitive).

        * @return Value of the attribute.

        * @leave KErrNotFound if attribute not found or the length of aName is 0.

        */

        virtual TPtrC GetAttributeL( const TDesC& aName );

        /**

        * Check if attribute is present (for the use of MMS UI only).

        *

        * @param[in] aName Name of the attribute (case sensitive).

        * @return ETrue if the attribute is found, EFalse otherwise.

        */

        virtual TBool FindAttribute( const TDesC& aName );

        /**

        * Delete named attribute from list (for the use of MMS UI only).

        *

        * @param[in] aName Name of the attribute (case sensitive).

        */

        virtual void DeleteAttribute( const TDesC& aName );

        /**

        * Reset all attributes (for the use of MMS UI only).

        *

        * Removes all attributes (names and values) from the message.

        */

        virtual void ResetAttributes();

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

        // FUNCTIONS TO HANDLE MESSAGE ATTACHMENTS

        /**

        * Create attachment entry and copy specified file to message store.

        *

        * The user should call SaveMessageL after having added all attachments 

        *     to update TMsvEntry of the message entry.

        *

        * @param[in] aStore An open edit store for the message entry. 

        *     Caller must commit and close the store when ready. (Several 

        *     attachments can be added before committing the store.)

        * @param[in] aFile Open file handle, source of the attachment. 

        *     Caller must close the file afterwards.

        * @param[in] aMimeType Mime type (content type) of the attachmet 

        *     in format type/subtype, for example image/jpeg.

        * @param[in] aMimeHeaders Mime headers for the attachment. If the content 

        *     type is not defined in aMimeHeaders, the function adds the mime type 

        *     and subtype from aMimeType. Suggested filename in aMimeHeaders is 

        *     used as attachment name.

        * @param[in] aAttachmentInfo Attachment into structure, must be 

        *     initialized to CMsvAttachment::EMsvFile. If mime type is added 

        *     into the attachment info, it must be of format type/subtype, 

        *     for example image/jpeg. On return AttachmentInfo contains data 

        *     about the attachment. Ownership of attachmentinfo is transferred 

        *     to attachment manager, it must not be deleted by caller. It must 

        *     not be put on cleanup stack either. MMS engine keeps it safe until 

        *     the ownership has been transferred.

        * @param[out] aAttaId Attachment id of the newly created attachment.

        *

        * @pre A message entry must exist. It may be a new entry or an old entry 

        *     to be edited.

        * @pre CMsvMimeHeaders structure must have been filled in advantage. 

        *     The following values should be set:

        * - Content type, for example image 

        * - Content subtype, for example jpeg

        * - Character set IANA MIBEnum value, for example 106 (utf-8). Should be 

        *      defined only if the content type is text.

        * - Content-id if the presentation part refers to the attachments by 

        *      content-ids.

        * - Suggested filename (name only, no path), the name that should be 

        *      used to store the attachment and used as suggested filename 

        *      when sending the message. If the suggested filename is not set, the

        *      name of the attachment file will be used.

        * - Content-location if the presentation part refers to the attachments by 

        *      using content-location. The content-location string must contain only 

        *      us-ascii characters.

        * - X-type parameters (if needed). These are always handled as pairs of a 

        *      parameter name and parameter value. A descriptor at an even idex 

        *      in the array (0, 2, 4, ...) represents the parameter name and a 

        *      descriptor at an odd index (1, 3, 5, ...) represents the parameter 

        *      value. If a parameter has no value, it must be indicated by an empty 

        *      descriptor. The X-type parameter array must always contain an even 

        *      number of elements.

        *

        * @code

        * // The following code shows a short example of how the attachement

        * // creation proceeds.

        *

        * // Assume that the client entry is set to the message entry.

        * // Attachments are added to the message entry one by one

        * CMsvStore* store = iMmsClient->Entry().EditStoreL();

        * CleanupStack::PushL(store);

        *

        * CMsvAttachment* attaInfo = NULL;

        * TMsvAttachmentId attaId = 0;

        *

        * RFile attaFile;

        * // Set filename of attachment

        * TFileName name( _L("C:\\pictures\\picture123.jpg") );

        *

        * CMsvMimeHeaders* mimeHeaders = CMsvMimeHeaders::NewL();

        * CleanupStack::PushL( mimeHeaders );

        *

        * // Set values to mime headers

        * mimeHeaders->SetContentTypeL( _L8( "image") );

        * mimeHeaders->SetContentSubTypeL( _L8( "jpeg" ) );

        *

        * _LIT8(KMimeType, "image/jpeg");

        * // CreateAttachment2L will set the content type to attachment Info

        *

        * // Open the attachment file for reading

        * attaFile.Open( iFs, name, EFileShareReadersOnly | EFileRead );

        * CleanupClosePushL(attaFile);

        *

        * attaInfo = CMsvAttachment::NewL(CMsvAttachment::EMsvFile);

        * // attaInfo ownerhip will be transferred to Attachment Manager.

        * // It must not be pushed onto the cleanupStack before calling 

        * // CreateAttachment2L.

        *

        * TMsvAttachmentId attaId = 0;

        *

        * iMmsClient->CreateAttachment2L(

        *     *store,   // edit store

        *     attaFile, // open file handle

        *     KMimeType, // combination type like image/jpeg

        *     *mimeHeaders,

        *     attaInfo,

        *     attaId);

        * // Now Attachment Manager owns the attaInfo

        * attaInfo = NULL;

        *

        * CleanupStack::PopAndDestroy(); // attaFile.Close()

        * CleanupStack::PopAndDestroy(); // mimeHeaders

        *

        * // Several attachments can be added before committing the store

        *

        * // Store must be committed before it is destroyed

        * store->CommitL();

        * CleanupStack::PopAndDestroy(); // store

        * @endcode

        */

        virtual void CreateAttachment2L(

            CMsvStore& aStore,

            RFile& aFile,

            TDesC8& aMimeType,

            CMsvMimeHeaders& aMimeHeaders,

            CMsvAttachment* aAttachmentInfo,

            TMsvAttachmentId& aAttaId);

        /**

        * Create a text/plain attachment.

        *

        * Creates a text attachment from text in a 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[in] aStore An open edit store. Caller must commit and close the 

        *     store (several attachments can be added before committing store).

        * @param[out] aAttachmentId Attachment id of the new attachment entry.

        * @param[in] aText Unicode text to be added as a text/plain attachment.

        * @param[in] aFile Suggested filename for the attachment.

        * @param[in] aConvertParagraphSeparator Flag that tells the function  

        *     to search for all 0x2029 characters (Unicode paragraph 

        *     separator) and to replace them with 0x000d 0x000a (carriage return, 

        *     line feed). 

        * Possible values:

        * - ETrue: Convert paragraph separators (default).

        * - EFalse: Do not convert paragraph separators.

        *

        * @pre A message entry must exist. It may be a new entry or an old entry 

        *     to be edited.

        *

        * @code

        *

        * TFileName attachmentFile( _L("story.txt") );

        *

        * CMsvStore* store = iMmsClient->Entry().EditStoreL();

        * CleanupStack::PushL(store);

        * TMsvAttachmentId attaId = 0;

        *

        * TBufC<12> story = _L( "Hello world!" );

        *

        * iMmsClient->CreateTextAttachmentL(

        *     *store,

        *     attaId,

        *     story,

        *     attachmentFile,

        *     ETrue )

        *

        * // When the call returns the id of the attachment will be strored in attaId

        *

        * // caller must commit the store as several attachments could be added berore

        * // committing the store.

        * store->CommitL();

        * CleanupStack::PopAndDestroy(); // store

        *

        * @endcode

        */

        virtual void CreateTextAttachmentL(

            CMsvStore& aStore,

            TMsvAttachmentId& aAttachmentId,

            const TDesC& aText,

            const TDesC& aFile,

            TBool aConvertParagraphSeparator = ETrue );

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

        // MESSAGE HANDLING FUNCTIONS

        // NOTE: these are asynchronous functions

        /**

        * Send current message in the background.

        *

        * The message is automatically moved to Outbox folder before the 

        *     sending starts.

        *

        * @param[in] aCompletionStatus iStatus member of an active object. 

        *     It will be set as completed when the operating system has relayed 

        *     the request to the server side of Symbian Messaging System.

        * @param[in] aSendingTime Time at which the message is to be sent 

        *     given as UTC time. If aSending time is zero or in the past, the 

        *     message is scheduled to be sent as soon as possible.