diff -r 4e54af54a4a1 -r 6c59112cfd31 email_plat/email_client_api/inc/memailmessage.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/email_plat/email_client_api/inc/memailmessage.h Thu Sep 30 11:43:07 2010 +0300 @@ -0,0 +1,262 @@ +/* +* Copyright (c) 2010 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 +#include +#include + +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::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