|
1 /* |
|
2 * Copyright (c) 2010 Nokia Corporation and/or its subsidiary(-ies). |
|
3 * All rights reserved. |
|
4 * This component and the accompanying materials are made available |
|
5 * under the terms of "Eclipse Public License v1.0" |
|
6 * which accompanies this distribution, and is available |
|
7 * at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
8 * |
|
9 * Initial Contributors: |
|
10 * Nokia Corporation - initial contribution. |
|
11 * |
|
12 * Contributors: |
|
13 * |
|
14 * Description: Email message API |
|
15 * |
|
16 */ |
|
17 |
|
18 #ifndef MEMAILMESSAGE_H |
|
19 #define MEMAILMESSAGE_H |
|
20 |
|
21 #include <emailapidefs.h> |
|
22 #include <memailaddress.h> |
|
23 #include <memailcontent.h> |
|
24 |
|
25 namespace EmailInterface { |
|
26 |
|
27 class MEmailMessageContent; |
|
28 class MEmailAttachment; |
|
29 |
|
30 /** message flags */ |
|
31 enum TMsgFlag |
|
32 { |
|
33 EFlag_Read = 1, // Message is read (or "seen") on the server |
|
34 EFlag_Read_Locally = 2, // Message is read on the client |
|
35 EFlag_Low = 4, // Message has low priority |
|
36 EFlag_Important = 8, // Message has high priority |
|
37 EFlag_FollowUpComplete = 16, // The message follow-up is complete |
|
38 EFlag_FollowUp = 32, // Message is flagged (a flag is showing next to msg in Outlook) |
|
39 EFlag_Attachments = 64, // Message has attachments |
|
40 EFlag_Multiple = 128, // Message has more than one recipient |
|
41 EFlag_CalendarMsg = 256, // Message is a calendar message |
|
42 EFlag_Answered = 512, // The message was replied to |
|
43 EFlag_Forwarded = 1024, // The message was forwarded |
|
44 EFlag_OnlyToMe = 2048, // The message was sent only to this user |
|
45 EFlag_RemoteDeleted = 4096, // The message has been deleted on the server |
|
46 EFlag_HasMsgSender = 8192, // The message has one or more senders |
|
47 }; |
|
48 /** |
|
49 * MEmailMessage is email message abstraction |
|
50 * @since S60 v5.0 |
|
51 @code |
|
52 Create and send a message with attachment: |
|
53 |
|
54 using namespace EmailInterface; |
|
55 CEmailInterfaceFactory* factory = CEmailInterfaceFactory::NewL(); |
|
56 CleanupStack::PushL( factory ); |
|
57 MEmailClientApi* emailAPI = factory->InterfaceL( KEmailTypeClientAPI ); |
|
58 CleanupReleasePushL( *emailAPI ); |
|
59 RMailboxPtrArray mailboxes; |
|
60 // Cleanup for array containing mailbox pointers, |
|
61 // calls MEmailMailbox::Release() on cleanup. |
|
62 CleanupResetAndRelease<MEmailMailbox>::PushL( mailboxes ); |
|
63 if ( emailAPI->GetMailboxesL( mailboxes ) > 0 ) // at least one found |
|
64 { |
|
65 MEmailMailbox* mailbox = mailboxes[0]; |
|
66 MEmailMessage* message = mailbox->CreateDraftMessageL(); |
|
67 CleanupReleasePushL( *message ); |
|
68 message->SetPlainTextBodyL( _L("So say we all!") ); |
|
69 message->AddAttachmentL( _L( "BSG.png" ) ); |
|
70 message->SendL(); |
|
71 CleanupStack::PopAndDestroy(); // message |
|
72 } |
|
73 CleanupStack::PopAndDestroy( 3 ); // mailboxes, emailAPI, factory |
|
74 @endcode |
|
75 * |
|
76 */ |
|
77 class MEmailMessage : public MEmailInterface |
|
78 { |
|
79 public: |
|
80 /** |
|
81 * Returns message id |
|
82 * @return message id |
|
83 */ |
|
84 virtual const TMessageId& MessageId() const = 0; |
|
85 |
|
86 /** |
|
87 * Returns sender address, ownership is not transferred |
|
88 * Setting role to MEmailAddress::EUndefined marks sender field "undefined" |
|
89 */ |
|
90 virtual MEmailAddress* SenderAddressL() const = 0; |
|
91 |
|
92 /** |
|
93 * Returns reply-to address (NULL for newly created draft message). |
|
94 * Ownership is not transferred. Setting role to MEmailAddress::EUndefined |
|
95 * marks reply-to field "undefined". |
|
96 */ |
|
97 virtual MEmailAddress* ReplyToAddressL() const = 0; |
|
98 |
|
99 /** |
|
100 * Sets reply-to address, note that role of the address is ignored. |
|
101 * Ownership is not transferred. |
|
102 */ |
|
103 virtual void SetReplyToAddressL( const MEmailAddress& aSender ) = 0; |
|
104 |
|
105 /** |
|
106 * Returns recipients. Ownership is transferred. |
|
107 * @param aRole, if EUndefined - returns to,cc and bcc recipients in that order |
|
108 * @return number of recipients returned in array |
|
109 * @exception returns KErrArgument if aRole is EReplyTo or ESender |
|
110 */ |
|
111 virtual TInt GetRecipientsL( const MEmailAddress::TRole aRole, |
|
112 REmailAddressArray& aRecipients ) const = 0; |
|
113 |
|
114 /** |
|
115 * Sets and replaces recipients of specific type. |
|
116 * @param aRole to, cc or bcc, for other types leave KErrArgument |
|
117 * @return recipient added to this message. Ownership is not transferred. |
|
118 */ |
|
119 virtual void SetRecipientsL( const MEmailAddress::TRole aRole, REmailAddressArray& aRecipients ) = 0; |
|
120 |
|
121 /** removes recipient from the message |
|
122 * @param aRecipient that has been obtained by GetRecipients(). |
|
123 * Comparison of recipients and aRecipient is done based on |
|
124 * MEmailAddress::Address() and MEmailAddress::Role(). |
|
125 * @exception KErrNotFound if aRecipient doesn't match with existing |
|
126 * recipients. |
|
127 */ |
|
128 virtual void RemoveRecipientL( const MEmailAddress& aRecipient ) = 0; |
|
129 |
|
130 /** |
|
131 * Returns subject |
|
132 * @return subject of the message |
|
133 */ |
|
134 virtual TPtrC Subject() const = 0; |
|
135 |
|
136 /** |
|
137 * Sets subject |
|
138 * @param subject of the message |
|
139 */ |
|
140 virtual void SetSubjectL( const TPtrC& aSubject) = 0; |
|
141 |
|
142 /** |
|
143 * Returns date and time of the message. |
|
144 * @return message date/time |
|
145 */ |
|
146 virtual TTime Date() const = 0; |
|
147 |
|
148 /** |
|
149 * Returns message flags |
|
150 * @return message flags |
|
151 */ |
|
152 virtual TInt Flags() const = 0; |
|
153 |
|
154 /** |
|
155 * Sets a message flag |
|
156 * @param flag to set |
|
157 */ |
|
158 virtual void SetFlag( const TUint aFlag ) = 0; |
|
159 |
|
160 /** |
|
161 * Resets a message flag to zero |
|
162 * @param flag to reset |
|
163 */ |
|
164 virtual void ResetFlag( const TUint aFlag ) = 0; |
|
165 |
|
166 // content |
|
167 /** |
|
168 * Returns message body |
|
169 * Returns pointer to message content, ownership not transferred. |
|
170 * Actual type is MEmailTextContent, or MEmailMultipart (see memailcontent.h) |
|
171 * @return content of the message or NULL if content has not been set |
|
172 */ |
|
173 virtual MEmailMessageContent* ContentL() const = 0; |
|
174 |
|
175 /** |
|
176 * Sets content to this message. First create content object, e.g. |
|
177 * CEmailInterfaceFactory::InterfaceL( KEmailIFUidTextContent ), i.e. text/plain |
|
178 * @param aContent content to set in the message, ownership is transferred. |
|
179 * possible old content is destroyed if setting new content succeeds. |
|
180 */ |
|
181 virtual void SetContentL( const MEmailMessageContent* aContent ) = 0; |
|
182 |
|
183 /** |
|
184 * Convenience method for setting plain text as message body. |
|
185 * @param aPlainText text/plain content of message body. Old content |
|
186 * is destroyed. |
|
187 */ |
|
188 virtual void SetPlainTextBodyL( const TDesC& aPlainText ) = 0; |
|
189 |
|
190 /** |
|
191 * Adds attachment to message. This may affect previously set content, e.g. |
|
192 * if SetContentL with MEmailTextContent argument was called, a new multipart |
|
193 * content is created with MEmailTextContent and attachment as child parts. |
|
194 * @param aFullpath path to file |
|
195 * @return created attachment, ownership is not transferred |
|
196 */ |
|
197 virtual MEmailAttachment* AddAttachmentL( const TDesC& aFullPath ) = 0; |
|
198 |
|
199 /** |
|
200 * Adds attachment to message. This may affect previously set content, e.g. |
|
201 * if SetContentL with MEmailTextContent argument was called, a new multipart |
|
202 * content is created with MEmailTextContent and attachment as child parts. |
|
203 * @param file handle to file to be attached. Handle remains open. |
|
204 * @return created attachment, ownership is not transferred |
|
205 */ |
|
206 virtual MEmailAttachment* AddAttachmentL( RFile& aFile ) = 0; |
|
207 |
|
208 /** |
|
209 * Returns attachments, ownership is transferred |
|
210 * @return number of attachments in aAttachments |
|
211 */ |
|
212 virtual TInt GetAttachmentsL( REmailAttachmentArray& aAttachments ) = 0; |
|
213 |
|
214 /** |
|
215 * Remove an attachment, ownership is not transferred. |
|
216 * @param attachment object obtained with GetAttachmentsL |
|
217 */ |
|
218 virtual void RemoveAttachmentL( const MEmailAttachment& aAttachment ) = 0; |
|
219 |
|
220 /** |
|
221 * Returns id of parent folder of the message |
|
222 * @return parent folder id |
|
223 */ |
|
224 virtual const TFolderId& ParentFolderId() const = 0; |
|
225 |
|
226 /** |
|
227 * Saves changes done with any mutator to persistent store. |
|
228 */ |
|
229 virtual void SaveChangesL() = 0; |
|
230 |
|
231 /** |
|
232 * Moves message to outbox, sending may not happen immediately but |
|
233 * after next mailbox synchronization. Changes done to the message |
|
234 * are first saved before sending as if SaveChangesL was called. |
|
235 * For immediate sending use MEmailMailbox::SynchronizeL() |
|
236 */ |
|
237 virtual void SendL() = 0; |
|
238 |
|
239 /** |
|
240 * Launches Email application and opens message in viewer |
|
241 * The method follows "fire and forget" pattern, returns immediately. |
|
242 */ |
|
243 virtual void ShowMessageViewerL( ) = 0; |
|
244 |
|
245 /** |
|
246 * Launches Email application and new reply message in editor. |
|
247 * The method follows "fire and forget" pattern, returns immediately. |
|
248 * @param boolean indicating if reply-to message is sent to all recipients. |
|
249 */ |
|
250 virtual void ReplyToMessageL( const TBool aReplyToAll = ETrue ) = 0; |
|
251 |
|
252 /** |
|
253 * Launches Email application and new forward message in editor |
|
254 * The method follows "fire and forget" pattern, returns immediately. |
|
255 */ |
|
256 virtual void ForwardMessageL() = 0; |
|
257 |
|
258 }; |
|
259 |
|
260 } // namespace EmailInterface |
|
261 |
|
262 #endif // MEMAILMESSAGE_H |