/*

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

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of "Eclipse Public License v1.0"

* which accompanies this distribution, and is available

* at the URL "http://www.eclipse.org/legal/epl-v10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description: Email message API

*

*/

#ifndef MEMAILMESSAGE_H

#define MEMAILMESSAGE_H

#include <emailapidefs.h>

#include <memailaddress.h>

#include <memailcontent.h>

namespace EmailInterface {

class MEmailMessageContent;

class MEmailAttachment;

/** message flags */  

enum TMsgFlag

    {

    EFlag_Read = 1,                 // Message is read (or "seen") on the server

    EFlag_Read_Locally = 2,         // Message is read on the client

    EFlag_Low = 4,                  // Message has low priority

    EFlag_Important = 8,            // Message has high priority

    EFlag_FollowUpComplete = 16,    // The message follow-up is complete

    EFlag_FollowUp = 32,            // Message is flagged (a flag is showing next to msg in Outlook)

    EFlag_Attachments = 64,         // Message has attachments

    EFlag_Multiple = 128,           // Message has more than one recipient

    EFlag_CalendarMsg = 256,        // Message is a calendar message

    EFlag_Answered = 512,           // The message was replied to

    EFlag_Forwarded = 1024,         // The message was forwarded

    EFlag_OnlyToMe = 2048,          // The message was sent only to this user

    EFlag_RemoteDeleted = 4096,     // The message has been deleted on the server

    EFlag_HasMsgSender = 8192,      // The message has one or more senders 

    };

/**

 * MEmailMessage is email message abstraction

 * @since S60 v5.0

   @code

     Create and send a message with attachment:

     using namespace EmailInterface;

     CEmailInterfaceFactory* factory = CEmailInterfaceFactory::NewL();

     CleanupStack::PushL( factory );

     MEmailClientApi* emailAPI = factory->InterfaceL( KEmailTypeClientAPI );

     CleanupReleasePushL( *emailAPI );

     RMailboxPtrArray mailboxes;

     // Cleanup for array containing mailbox pointers, 

     // calls MEmailMailbox::Release() on cleanup.

     CleanupResetAndRelease<MEmailMailbox>::PushL( mailboxes );

     if ( emailAPI->GetMailboxesL( mailboxes ) > 0 ) // at least one found

         {

         MEmailMailbox* mailbox = mailboxes[0];

         MEmailMessage* message = mailbox->CreateDraftMessageL();

         CleanupReleasePushL( *message );

         message->SetPlainTextBodyL( _L("So say we all!") );

         message->AddAttachmentL( _L( "BSG.png" ) ); 

         message->SendL();

         CleanupStack::PopAndDestroy(); // message

         }    

    CleanupStack::PopAndDestroy( 3 ); // mailboxes, emailAPI, factory

  @endcode

  *

  */

class MEmailMessage : public MEmailInterface

{

public:

    /**

     * Returns message id

     * @return message id

     */

    virtual const TMessageId& MessageId() const = 0;

    /** 

     * Returns sender address, ownership is not transferred

     * Setting role to MEmailAddress::EUndefined marks sender field "undefined"

     */

    virtual MEmailAddress* SenderAddressL() const = 0;        

    /**

     * Returns reply-to address (NULL for newly created draft message).

     * Ownership is not transferred. Setting role to MEmailAddress::EUndefined 

     * marks reply-to field "undefined".

     */    

    virtual MEmailAddress* ReplyToAddressL() const = 0;

    /**

     * Sets reply-to address, note that role of the address is ignored.

     * Ownership is not transferred.

     */

    virtual void SetReplyToAddressL( const MEmailAddress& aSender ) = 0;       

    /**

     * Returns recipients. Ownership is transferred.

     * @param aRole, if EUndefined - returns to,cc and bcc recipients in that order

     * @return number of recipients returned in array

     * @exception returns KErrArgument if aRole is EReplyTo or ESender

     */    

    virtual TInt GetRecipientsL( const MEmailAddress::TRole aRole,

        REmailAddressArray& aRecipients ) const = 0;

    /**

     * Sets and replaces recipients of specific type.

     * @param aRole to, cc or bcc, for other types leave KErrArgument

     * @return recipient added to this message. Ownership is not transferred.

     */

    virtual void SetRecipientsL( const MEmailAddress::TRole aRole, REmailAddressArray& aRecipients ) = 0;    

    /** removes recipient from the message

     * @param aRecipient that has been obtained by GetRecipients().

     * Comparison of recipients and aRecipient is done based on 

     * MEmailAddress::Address() and MEmailAddress::Role().

     * @exception KErrNotFound if aRecipient doesn't match with existing 

     * recipients.

     */

    virtual void RemoveRecipientL( const MEmailAddress& aRecipient ) = 0;

    /**

     * Returns subject

     * @return subject of the message

     */

    virtual TPtrC Subject() const = 0;

    /**

     * Sets subject

     * @param subject of the message 

     */

    virtual void  SetSubjectL( const TPtrC& aSubject) = 0;    

    /**

     * Returns date and time of the message.

     * @return message date/time 

     */

    virtual TTime Date() const = 0;

    /**

     * Returns message flags

     * @return message flags

     */

    virtual TInt Flags() const = 0;

    /**

     * Sets a message flag

     * @param flag to set

     */

    virtual void SetFlag( const TUint aFlag ) = 0;

    /**

     * Resets a message flag to zero

     * @param flag to reset

     */

    virtual void ResetFlag( const TUint aFlag ) = 0;

// content

    /**      

     * Returns message body

     * Returns pointer to message content, ownership not transferred.

     * Actual type is MEmailTextContent, or MEmailMultipart (see memailcontent.h)

     * @return content of the message or NULL if content has not been set

     */    

    virtual MEmailMessageContent* ContentL() const = 0;

    /**

     * Sets content to this message. First create content object, e.g.

     * CEmailInterfaceFactory::InterfaceL( KEmailIFUidTextContent ), i.e. text/plain

     * @param aContent content to set in the message, ownership is transferred.

     * possible old content is destroyed if setting new content succeeds.

     */    

    virtual void SetContentL( const MEmailMessageContent* aContent ) = 0;

    /**

     * Convenience method for setting plain text as message body.

     * @param aPlainText text/plain content of message body. Old content

     * is destroyed.

     */

    virtual void SetPlainTextBodyL( const TDesC& aPlainText ) = 0;

    /**

     * Adds attachment to message. This may affect previously set content, e.g.

     * if SetContentL with MEmailTextContent argument was called, a new multipart

     * content is created with MEmailTextContent and attachment as child parts.

     * @param aFullpath path to file 

     * @return created attachment, ownership is not transferred

     */

    virtual MEmailAttachment* AddAttachmentL( const TDesC& aFullPath ) = 0;

    /**

     * Adds attachment to message. This may affect previously set content, e.g.

     * if SetContentL with MEmailTextContent argument was called, a new multipart

     * content is created with MEmailTextContent and attachment as child parts.

     * @param file handle to file to be attached. Handle remains open.

     * @return created attachment, ownership is not transferred

     */

    virtual MEmailAttachment* AddAttachmentL( RFile& aFile ) = 0;

    /**

     * Returns attachments, ownership is transferred    

     * @return number of attachments in aAttachments 

     */

    virtual TInt GetAttachmentsL( REmailAttachmentArray& aAttachments ) = 0;

    /**

     * Remove an attachment, ownership is not transferred. 

     * @param attachment object obtained with GetAttachmentsL

     */

    virtual void RemoveAttachmentL( const MEmailAttachment& aAttachment ) = 0;

    /**

     * Returns id of parent folder of the message

     * @return parent folder id

     */

    virtual const TFolderId& ParentFolderId() const = 0;

    /** 

     * Saves changes done with any mutator to persistent store. 

     */

    virtual void SaveChangesL() = 0;

    /** 

     * Moves message to outbox, sending may not happen immediately but

     * after next mailbox synchronization. Changes done to the message

     * are first saved before sending as if SaveChangesL was called.

     * For immediate sending use MEmailMailbox::SynchronizeL()

     */

    virtual void SendL() = 0;

    /**

     * Launches Email application and opens message in viewer

     * The method follows "fire and forget" pattern, returns immediately.

     */    

    virtual void ShowMessageViewerL( ) = 0;

    /** 

     * Launches Email application and new reply message in editor. 

     * The method follows "fire and forget" pattern, returns immediately.

     * @param boolean indicating if reply-to message is sent to all recipients.

     */

    virtual void ReplyToMessageL( const TBool aReplyToAll = ETrue ) = 0;   

    /** 

     * Launches Email application and new forward message in editor

     * The method follows "fire and forget" pattern, returns immediately.

     */    

    virtual void ForwardMessageL() = 0;

};

} // namespace EmailInterface

#endif // MEMAILMESSAGE_H