1 /* |
|
2 * Copyright (c) 2006 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: Defines Framework Plugin API functions. |
|
15 * |
|
16 */ |
|
17 |
|
18 |
|
19 #ifndef M_FSMAILPLUGINAPI_H |
|
20 #define M_FSMAILPLUGINAPI_H |
|
21 |
|
22 // INCLUDES |
|
23 //<cmail> |
|
24 #include "MFSMailRequestObserver.h" |
|
25 #include "MFSMailEventObserver.h" |
|
26 #include "CFSMailBox.h" |
|
27 //</cmail> |
|
28 |
|
29 // FORWARD DECLARATIONS |
|
30 class MDesCArray; |
|
31 |
|
32 // CLASS DECLARATION |
|
33 |
|
34 /** |
|
35 * Freestyle email plugin API abstract interface. |
|
36 * |
|
37 * Plugin is identified using ecom implementation uid. |
|
38 * Framework searches existing plugins and creates plugin api instance per each plugin. |
|
39 * |
|
40 * plugin API provides methods to fetch from plugins service, mailbox, |
|
41 * folder, message and attachment objetcs, |
|
42 * which further contain more detailed data of each object to be read. |
|
43 * |
|
44 * When updating data Freestyle framework manipulates corresponding |
|
45 * service, mailbox, folder, message and attachment objetcs and |
|
46 * after manipulation stores manipulated object to plugin by calling |
|
47 * corresponding store method. |
|
48 * |
|
49 * Asynchronous requests -> framework gives request id to every async request, |
|
50 * which plugin gives to framework when calling back observer to be matched |
|
51 * request data in framework. Framework gives observer pointer in async request |
|
52 * to be called back. |
|
53 * |
|
54 * API allows Symbian leaves from plugins and will trap them, error codes are |
|
55 * expected to be symbian error codes. |
|
56 * @since ... |
|
57 */ |
|
58 class MFSMailPlugin |
|
59 { |
|
60 public: // Data |
|
61 |
|
62 public: // Methods |
|
63 |
|
64 // PLUGIN HANDLING |
|
65 /** |
|
66 * returns plugin capabilities |
|
67 * |
|
68 * @return plugin capabilities data structure |
|
69 */ |
|
70 virtual const TFSMailPluginCapabilities ReadPluginCapabilitiesL() = 0; |
|
71 |
|
72 // MAILBOX HANDLING |
|
73 /** |
|
74 * lists existing mailboxes implemented by given plugin |
|
75 * |
|
76 * @param aPlugin defines which plugin request is accessed to |
|
77 * @param aMailBoxes plugin writes results to this array |
|
78 * owned by framework |
|
79 */ |
|
80 virtual void ListMailBoxesL( RArray<TFSMailMsgId>& aMailboxes) = 0; |
|
81 |
|
82 /** |
|
83 * returns email mailbox object related to given mailbox id |
|
84 * mailbox data set by plugin : |
|
85 * - mailbox id |
|
86 * - mailbox name |
|
87 * - branding id |
|
88 * - mailbox capabilities |
|
89 * |
|
90 * @param aMailBoxId defines mailbox id |
|
91 * @return mailBox object ( CFSMailBox ) to be owned by user |
|
92 */ |
|
93 virtual CFSMailBox* GetMailBoxByUidL( const TFSMailMsgId& aMailBoxId) = 0; |
|
94 |
|
95 /** |
|
96 * removes mailbox |
|
97 * |
|
98 * @param aMailBoxId defines id of the mailbox to be removed |
|
99 */ |
|
100 virtual void DeleteMailBoxByUidL(const TFSMailMsgId& aMailBoxId) = 0; |
|
101 |
|
102 /** |
|
103 * Returns branding id for this mailbox. This function is used by Branding Manager |
|
104 * to associate mailbox to a branding definition. Plugin implementation should |
|
105 * return incoming mail server associated with this mailbox. |
|
106 * |
|
107 * @param aMailBoxId defines the target mailbox |
|
108 * @return branding id |
|
109 */ |
|
110 virtual TDesC& GetBrandingIdL(const TFSMailMsgId& aMailboxId) = 0; |
|
111 |
|
112 /** |
|
113 * Moves a messages to the given folder. |
|
114 * |
|
115 * @param aMailBoxId defines mailbox id |
|
116 * @param aMessageIds ids of the messages to be transferred |
|
117 * @param aSourceFolderId id of the folder where messages are located |
|
118 * @param aDestinationFolderId destination folder id |
|
119 * |
|
120 */ |
|
121 virtual void MoveMessagesL( const TFSMailMsgId& aMailBoxId, |
|
122 const RArray<TFSMailMsgId>& aMessageIds, |
|
123 const TFSMailMsgId& aSourceFolderId, |
|
124 const TFSMailMsgId& aDestinationFolderId ) = 0; |
|
125 /** |
|
126 * Copies a messages from one folder to another. |
|
127 * This function copies a messages to the given folder, |
|
128 * including the properties, content, and all attachments. |
|
129 * (note Only works if the store is in an authenticated state, |
|
130 * otherwise this function leaves with KErrNotReady) |
|
131 * |
|
132 * @param aMailBoxId defines mailbox id |
|
133 * @param aMessageIds ids of the messages to be copied |
|
134 * @param aNewMessages ids of the copied messages. |
|
135 * @param aSourceFolderId id of the folder where messages are located |
|
136 * @param aDestinationFolderId destination folder id |
|
137 */ |
|
138 virtual void CopyMessagesL( const TFSMailMsgId& aMailBoxId, |
|
139 const RArray<TFSMailMsgId>& aMessageIds, |
|
140 RArray<TFSMailMsgId>& aNewMessages, |
|
141 const TFSMailMsgId& aSourceFolderId, |
|
142 const TFSMailMsgId& aDestinationFolderId ) = 0; |
|
143 |
|
144 /** Get a list of most recently used addresses of desired mailbox. |
|
145 * Each MRU entry consists of two descriptors placed sequentially |
|
146 * in the array. First one is the display name and the second |
|
147 * one is the actual email address. If for example some entry does |
|
148 * not contain a name at all then a KNullDesC is found in place of |
|
149 * the name. |
|
150 * |
|
151 * The function will leave with KErrNotFound if a mailbox with |
|
152 * given id is not found. |
|
153 * |
|
154 * @param aMailBoxId defines mailbox id |
|
155 * @return Array of descriptors containing MRUs. Ownership |
|
156 * is transferred. Empty if no entries are found. |
|
157 */ |
|
158 virtual MDesCArray* GetMrusL( const TFSMailMsgId& aMailBoxId ) = 0; |
|
159 |
|
160 // old one for building purposes |
|
161 virtual MDesCArray* GetMrusL( TFSMailMsgId aMailBoxId ) const= 0; |
|
162 |
|
163 /** Set a list of most recently used addresses for given mailbox. |
|
164 * Each MRU entry consists of two descriptors placed sequentially |
|
165 * in the array. First one is the display name and the second |
|
166 * one is the actual email address. If for example some entry does |
|
167 * not contain a name at all then a KNullDesC is found in place of |
|
168 * the name. |
|
169 * |
|
170 * The function will leave with KErrNotFound if a mailbox with |
|
171 * given id is not found. |
|
172 * |
|
173 * @param aMailBoxId defines mailbox id |
|
174 * @param aNewMruList Array of descriptors containing MRUs. Empty if no entries are found. |
|
175 */ |
|
176 virtual void SetMrusL( const TFSMailMsgId& aMailBoxId, |
|
177 MDesCArray* aNewMruList ) = 0; |
|
178 |
|
179 // MAILBOX SYNC |
|
180 /** |
|
181 * DEPRECATED |
|
182 * |
|
183 */ |
|
184 virtual void GoOnlineL( ) = 0; |
|
185 |
|
186 /** |
|
187 * DEPRECATED |
|
188 * |
|
189 */ |
|
190 virtual void GoOfflineL( ) = 0; |
|
191 |
|
192 /** |
|
193 * DEPRECATED |
|
194 * |
|
195 */ |
|
196 virtual TFSProgress GetLastSyncStatusL( ) = 0; |
|
197 |
|
198 /** |
|
199 * DEPRECATED |
|
200 * |
|
201 */ |
|
202 virtual TInt RefreshNowL( ) = 0; |
|
203 |
|
204 /** |
|
205 * Enables synchronization of identified mailbox. This means |
|
206 * that the plugin can connect toserver to do synchronization |
|
207 * of the mailbox when necessary or stay connected all the time. |
|
208 * The actual functionality depends on user settings and plugin |
|
209 * implementation. |
|
210 * |
|
211 * All collections (mail etc.) supported by the plugin and |
|
212 * enabled by user settings are synchronized. |
|
213 * |
|
214 * This function sets identified mailbox online but it may |
|
215 * have a side effect that also other mailboxes of the same |
|
216 * plugin are set online. |
|
217 * |
|
218 * Connection is set offline normally by using specific function |
|
219 * for this purpose. There are also other reasons for ending up |
|
220 * in offline state like network error or scheduling. |
|
221 * |
|
222 * @param aMailBoxId defines mailbox |
|
223 * |
|
224 */ |
|
225 virtual void GoOnlineL( const TFSMailMsgId& aMailBoxId ) = 0; |
|
226 |
|
227 /** |
|
228 * Disables mailbox synchronization. Connection by the plugin |
|
229 * to synchronize identified mailbox is not allowed after this. |
|
230 * |
|
231 * If GoOnlineL has effect on other mailboxes of the |
|
232 * same plugin then this function has effect on those |
|
233 * mailboxes also. |
|
234 * |
|
235 * @param aMailBoxId defines mailbox |
|
236 * |
|
237 */ |
|
238 virtual void GoOfflineL( const TFSMailMsgId& aMailBoxId ) = 0; |
|
239 |
|
240 /** |
|
241 * Returns last sync operation status. |
|
242 * |
|
243 * @param aMailBoxId defines mailbox |
|
244 * @return Last sync operation status |
|
245 * |
|
246 */ |
|
247 virtual const TFSProgress GetLastSyncStatusL( const TFSMailMsgId& aMailBoxId ) = 0; |
|
248 |
|
249 /** |
|
250 * Forces synchronization of mailbox. This can be called |
|
251 * whether the mailbox is currently offline or online. In |
|
252 * case the mailbox is offline in the beginning, connection |
|
253 * is made up for the time of the synchronization. |
|
254 * |
|
255 * All collections (mail etc.) supported by the plugin and |
|
256 * enabled by user settings are synchronized. |
|
257 * |
|
258 * This is an asynchronous operation and the request id |
|
259 * is returned for cancelling purpose. |
|
260 * |
|
261 * Observer is given as a parameter to enable callbacks |
|
262 * related to this operation. Alternatively user can use |
|
263 * empty implementation of the observer function and rely |
|
264 * only on events. Notice that the event system is not as |
|
265 * comprehensive as the observing way do this. |
|
266 * |
|
267 * @param aMailBoxId defines mailbox |
|
268 * @param aOperationObserver is client provided observer that |
|
269 * will receive progress notifications during the |
|
270 * operation. |
|
271 * @param aRequestId identifies asynchronous request |
|
272 */ |
|
273 virtual void RefreshNowL( const TFSMailMsgId& aMailBoxId, |
|
274 MFSMailRequestObserver& aOperationObserver, |
|
275 TInt aRequestId ) = 0; |
|
276 |
|
277 // FOLDER HANDLING |
|
278 /** |
|
279 * returns email folder object related to given folder id |
|
280 * folder data set by plugin : |
|
281 * - folder id |
|
282 * - folder name |
|
283 * - folder type ; Inbox, Outbox, Sent, Drafts, Deleted, Other |
|
284 * - message count |
|
285 * - unread message count |
|
286 * - mailbox id |
|
287 * - parent folder |
|
288 * @param aMailBoxId defines mailbox id |
|
289 * @param aFolderId defines folder id |
|
290 * @return folder object (CFSMailFolder) to be owned by user |
|
291 */ |
|
292 virtual CFSMailFolder* GetFolderByUidL( const TFSMailMsgId& aMailBoxId, |
|
293 const TFSMailMsgId& aFolderId ) = 0; |
|
294 |
|
295 /** |
|
296 * creates new folder |
|
297 * |
|
298 * @param aMailBoxId defines mailbox where folder is created |
|
299 * @param aFolderId defines id of the parent folder |
|
300 * @param aFolderName defines name of the new folder |
|
301 * @param aSync defines if new folder is local only (false) |
|
302 * or if it also should sync to server (true) |
|
303 * @return new folder object CFSMailFolder to be owned by user |
|
304 */ |
|
305 virtual CFSMailFolder* CreateFolderL( const TFSMailMsgId& aMailBoxId, |
|
306 const TFSMailMsgId& aParentFolderId, |
|
307 const TDesC& aFolderName, |
|
308 const TBool aSync ) = 0; |
|
309 |
|
310 /** |
|
311 * deletes email folder related to given folder id |
|
312 * |
|
313 * @param aMailBoxId defines mailbox where folder is deleted |
|
314 * @param aFolderId defines id of folder to be deleted |
|
315 */ |
|
316 virtual void DeleteFolderByUidL( const TFSMailMsgId& aMailBoxId, |
|
317 const TFSMailMsgId& aFolderId) = 0; |
|
318 |
|
319 /** |
|
320 * List subfolders of given folder. Only direct subfolders of given folder are returned. |
|
321 * Folder data : |
|
322 * - folder id |
|
323 * - folder name |
|
324 * - folder type ; Inbox, Outbox, Sent, Drafts, Deleted, Other |
|
325 * - message count |
|
326 * - unread message count |
|
327 * - mailbox id |
|
328 * - parent folder |
|
329 * - subfolder count |
|
330 * |
|
331 * @param aMailBoxId defines mailbox where parent folder is |
|
332 * @param aFolderId defines parent folder id. TFSMailId::NullId() for root level list. |
|
333 * @param aFolderList plugin writes results in this array given by user |
|
334 */ |
|
335 virtual void ListFoldersL( const TFSMailMsgId& aMailBoxId, |
|
336 const TFSMailMsgId& aParentFolderId, |
|
337 RPointerArray<CFSMailFolder>& aFolderList) = 0; |
|
338 |
|
339 /** |
|
340 * List all subfolders of given mailbox. |
|
341 * folder data : |
|
342 * - folder id |
|
343 * - folder name |
|
344 * - folder type ; Inbox, Outbox, Sent, Drafts, Deleted, Other |
|
345 * - message count |
|
346 * - unread message count |
|
347 * - mailbox id |
|
348 * - parent folder |
|
349 * - subfolder count |
|
350 * |
|
351 * @param aMailBoxId defines mailbox |
|
352 * @param aFolderList plugin writes results in this array given by user. |
|
353 * Caller must determine tree structure by examining parent id of each returned folder. |
|
354 */ |
|
355 virtual void ListFoldersL( const TFSMailMsgId& aMailBoxId, |
|
356 RPointerArray<CFSMailFolder>& aFolderList) = 0; |
|
357 /** |
|
358 * return folder id of given folder type |
|
359 * |
|
360 * @param aMailBoxId defines mailbox where folder is |
|
361 * @param aFolderType folder type |
|
362 * |
|
363 * return folder id |
|
364 */ |
|
365 virtual TFSMailMsgId GetStandardFolderIdL( const TFSMailMsgId& aMailBoxId, |
|
366 const TFSFolderType aFolderType ) = 0; |
|
367 |
|
368 // MESSAGE FETCH AND STORE |
|
369 |
|
370 /** |
|
371 * Get message iterator for given folder |
|
372 * |
|
373 * @param aMailBoxId defines mailbox where parent folder is |
|
374 * @param aFolderId defines folder id |
|
375 * @param aDetails describes details requested to CFSMailMessage objects returned by the iterator |
|
376 * @param aSorting describes requested sort criteria. First item in array is primary sort criteria. |
|
377 * @return iterator (remember virtual destructor) |
|
378 */ |
|
379 |
|
380 virtual MFSMailIterator* ListMessagesL( const TFSMailMsgId& aMailBoxId, |
|
381 const TFSMailMsgId& aFolderId, |
|
382 const TFSMailDetails aDetails, |
|
383 const RArray<TFSMailSortCriteria>& aSorting ) = 0; |
|
384 |
|
385 /** |
|
386 * returns email message object related to given message id |
|
387 * |
|
388 * message info set by plugin : |
|
389 * - message id |
|
390 * - mailbox |
|
391 * - parent folder |
|
392 * - message size |
|
393 * - the rest is defined by message attributes ; |
|
394 * @param aMailBoxId defines mailbox where message is |
|
395 * @param aFolderId defines parent folder id where message is |
|
396 * @param aMessageId defines message id |
|
397 * |
|
398 * @param aDetails defines which message parts are included in message |
|
399 * EFSMsgDataIdOnly -> Doesn't get any data. The object just contains the ID. |
|
400 * EFSMsgDataDate -> Get received date only. To be used when showing messages sorted by date. |
|
401 * The rest would be retreived when needed but date is needed to build the list. |
|
402 * EFSMsgDataSubject -> Like above but when sorting by subject |
|
403 * EFSMsgDataSender -> Likewise for sender address. |
|
404 * EFSMsgDataEnvelope -> Date, subject, Sender, To, Cc at least. |
|
405 * EFSMsgDataStructure -> the part structure including mime type, size and name headers. |
|
406 * |
|
407 * @return message data (CFSMailMessage), ownership is transferred to user |
|
408 */ |
|
409 virtual CFSMailMessage* GetMessageByUidL( const TFSMailMsgId& aMailBoxId, |
|
410 const TFSMailMsgId& aParentFolderId, |
|
411 const TFSMailMsgId& aMessageId, |
|
412 const TFSMailDetails aDetails) = 0; |
|
413 |
|
414 /** |
|
415 * deletes email message defined by message id |
|
416 * |
|
417 * @param aMailBoxId defines mailbox |
|
418 * @param aFolderId defines message parent folder id |
|
419 * @param aMessages defines ids of messages to be deleted |
|
420 */ |
|
421 virtual void DeleteMessagesByUidL( const TFSMailMsgId& aMailBoxId, |
|
422 const TFSMailMsgId& aFolderId, |
|
423 const RArray<TFSMailMsgId>& aMessages ) = 0; |
|
424 |
|
425 /** |
|
426 * creates new message template into drafts folder |
|
427 * |
|
428 * @param aMailBoxId defines mailbox where message is created |
|
429 * @return message object to be modified by user (ownership is transferred to user) |
|
430 */ |
|
431 virtual CFSMailMessage* CreateMessageToSendL( const TFSMailMsgId& aMailBoxId ) = 0; |
|
432 |
|
433 /** |
|
434 * creates new message template to drafts folder to be forwarded |
|
435 * |
|
436 * @param aMailBoxId defines mailbox where message is created |
|
437 * @param aOriginalMessageId defines original message,which is forwarded |
|
438 * @return message object to be modified by user (ownership is transferred to user) |
|
439 */ |
|
440 virtual CFSMailMessage* CreateForwardMessageL( const TFSMailMsgId& aMailBoxId, |
|
441 const TFSMailMsgId& aOriginalMessageId ) = 0; |
|
442 |
|
443 /** |
|
444 * creates new reply message template to drafts folder |
|
445 * @param aMailBoxId defines mailbox where message is created |
|
446 * @param aOriginalMessageId defines id of original message,which is replied to |
|
447 * @param aReplyToAll |
|
448 * @return message object to be modified by user (ownership is transferred to user) |
|
449 */ |
|
450 virtual CFSMailMessage* CreateReplyMessageL( const TFSMailMsgId& aMailBoxId, |
|
451 const TFSMailMsgId& aOriginalMessageId, |
|
452 const TBool aReplyToAll ) = 0; |
|
453 |
|
454 /** |
|
455 * stores message data to message store after modifications (commit) |
|
456 * |
|
457 * @param aMailBoxId defines mailbox where message is stored |
|
458 * @param aMessage message data to be stored by plugin |
|
459 */ |
|
460 virtual void StoreMessageL( const TFSMailMsgId& aMailBoxId, |
|
461 CFSMailMessage& aMessage ) = 0; |
|
462 |
|
463 /** |
|
464 * starts asynchronous message fetching done by plugin |
|
465 * |
|
466 * @param aMailBoxId defines mailbox where message is located |
|
467 * @param aFolderId defines parent folder where message is located |
|
468 * @param aMessageIds defines ids of messages to be fetched |
|
469 * |
|
470 * @param aDetails defines which message parts are included in message |
|
471 * EFSMsgDataIdOnly -> Doesn't get any data. The object just contains the ID. |
|
472 * EFSMsgDataDate -> Get received date only. To be used when showing messages sorted by date. |
|
473 * The rest would be retreived when needed but date is needed to build the list. |
|
474 * EFSMsgDataSubject -> Like above but when sorting by subject |
|
475 * EFSMsgDataSender -> Likewise for sender address. |
|
476 * EFSMsgDataEnvelope -> Date, subject, Sender, To, Cc at least. |
|
477 * EFSMsgDataStructure -> the part structure including mime type, size and name headers. |
|
478 * |
|
479 * @param aObserver defines callback medhod, which plugin calls after |
|
480 * async request has completed |
|
481 * @param aRequestId identifies asynchronous request |
|
482 */ |
|
483 virtual void FetchMessagesL( const TFSMailMsgId& aMailBoxId, |
|
484 const TFSMailMsgId& aParentFolderId, |
|
485 const RArray<TFSMailMsgId>& aMessageIds, |
|
486 TFSMailDetails aDetails, |
|
487 MFSMailRequestObserver& aObserver, |
|
488 TInt aRequestId) = 0; |
|
489 |
|
490 /** |
|
491 * DEPRECATED |
|
492 * Fetches message part contents from server asynchronously. |
|
493 * |
|
494 * @param aMessagePartIds define message part ids of message parts that are asked to be fetched |
|
495 * @param aOperationObserver is FW provided observer that should be used to report progress notifications during the operation. |
|
496 * @param aRequestId identifies asynchronous request |
|
497 */ |
|
498 virtual void FetchMessagesPartsL( const RArray<TFSMailMsgId>& aMessagePartIds, |
|
499 MFSMailRequestObserver& aOperationObserver, |
|
500 const TInt aRequestId) = 0; |
|
501 |
|
502 /** |
|
503 * Fetches message part contents from server asynchronously. |
|
504 * |
|
505 * @param aMessagePartIds define message part ids of message parts that are asked to be fetched |
|
506 * @param aOperationObserver is FW provided observer that should be used to report |
|
507 * progress notifications during the operation. |
|
508 * @param aRequestId identifies asynchronous request |
|
509 * @param aPreferredByteCount indicates how much more content for part(s) UI wants to fetch. |
|
510 * Default value zero indicates that all content should be fetched. |
|
511 * Actual amount of data fetched may differ from requested (possibly all fetched in any case). |
|
512 */ |
|
513 virtual void FetchMessagePartsL( const RArray<TFSMailMsgId>& aMessagePartIds, |
|
514 MFSMailRequestObserver& aOperationObserver, |
|
515 const TInt aRequestId, |
|
516 const TUint aPreferredByteCount) = 0; |
|
517 |
|
518 |
|
519 /* synchronous message accessor |
|
520 * |
|
521 * @param aMailBoxId defines mailbox where message is located |
|
522 * @param aParentFolderId defines parent folder where message is located |
|
523 * @param aMessageIds defines ids of messages to be read from store |
|
524 * @param aMessageList plugin writes results into this |
|
525 * |
|
526 * @param aDetails defines which message parts are included in message |
|
527 * EFSMsgDataIdOnly -> Doesn't get any data. The object just contains the ID. |
|
528 * EFSMsgDataDate -> Get received date only. To be used when showing messages sorted by date. |
|
529 * The rest would be retreived when needed but date is needed to build the list. |
|
530 * EFSMsgDataSubject -> Like above but when sorting by subject |
|
531 * EFSMsgDataSender -> Likewise for sender address. |
|
532 * EFSMsgDataEnvelope -> Date, subject, Sender, To, Cc at least. |
|
533 * EFSMsgDataStructure -> the part structure including mime type, size and name headers. |
|
534 * |
|
535 */ |
|
536 virtual void GetMessagesL( const TFSMailMsgId& aMailBoxId, |
|
537 const TFSMailMsgId& aParentFolderId, |
|
538 const RArray<TFSMailMsgId>& aMessageIds, |
|
539 RPointerArray<CFSMailMessage>& aMessageList, |
|
540 const TFSMailDetails aDetails ) = 0; |
|
541 |
|
542 /** |
|
543 * Returns child part objects for given message part. Ownership of objects |
|
544 * is transferred to caller. |
|
545 * |
|
546 * @param aMailBoxId defines mailbox where message is located |
|
547 * @param aParentFolderId defines parent folder where message is located |
|
548 * @param aMessageId gives the id of the message that message part belongs to |
|
549 * @param aParentId gives the id of the parent message part |
|
550 * @param aParts list of child parts of given parent message part |
|
551 */ |
|
552 virtual void ChildPartsL( const TFSMailMsgId& aMailBoxId, |
|
553 const TFSMailMsgId& aParentFolderId, |
|
554 const TFSMailMsgId& aMessageId, |
|
555 const TFSMailMsgId& aParentId, |
|
556 RPointerArray<CFSMailMessagePart>& aParts) = 0; |
|
557 |
|
558 /** |
|
559 * Creates and adds a new child part to this part. |
|
560 * If aInsertBefore is NULL id then new part is added as last. |
|
561 * |
|
562 * @param aMailBoxId defines mailbox where message is located |
|
563 * @param aParentFolderId defines parent folder where message is located |
|
564 * @param aMessageId gives the id of the message that message part belongs to |
|
565 * @param aParentPartId parent of the new part |
|
566 * @param aInsertBefore id of existing part that new part should precede. |
|
567 * If NULL id then new part is added as last. |
|
568 */ |
|
569 virtual CFSMailMessagePart* NewChildPartL( const TFSMailMsgId& aMailBoxId, |
|
570 const TFSMailMsgId& aParentFolderId, |
|
571 const TFSMailMsgId& aMessageId, |
|
572 const TFSMailMsgId& aParentPartId, |
|
573 const TFSMailMsgId& aInsertBefore, |
|
574 const TDesC& aContentType) = 0; |
|
575 |
|
576 /** |
|
577 * Copies given message as new child part to this part. |
|
578 * |
|
579 * @param aMailBoxId defines mailbox where message is located |
|
580 * @param aParentFolderId defines parent folder where message is located |
|
581 * @param aMessageId gives the id of the message that message part belongs to |
|
582 * @param aParentPartId parent of the new part |
|
583 * @param aInsertBefore id of existing part that new part should precede. |
|
584 * If NULL id then new part is added as last. |
|
585 * @param aMessage specifies the message that is copied |
|
586 */ |
|
587 virtual CFSMailMessagePart* CopyMessageAsChildPartL(const TFSMailMsgId& aMailBoxId, |
|
588 const TFSMailMsgId& aParentFolderId, |
|
589 const TFSMailMsgId& aMessageId, |
|
590 const TFSMailMsgId& aParentPartId, |
|
591 const TFSMailMsgId& aInsertBefore, |
|
592 const CFSMailMessage& aMessage) = 0; |
|
593 |
|
594 /** |
|
595 * Removes child part (and its children, if any) from this part |
|
596 * |
|
597 * @param aMailBoxId defines mailbox where message is located |
|
598 * @param aParentFolderId defines parent folder where message is located |
|
599 * @param aMessageId gives the id of the message that message part belongs to |
|
600 * @param aParentPartId parent of the part |
|
601 * @param aPartId part to remove |
|
602 */ |
|
603 virtual void RemoveChildPartL( const TFSMailMsgId& aMailBoxId, |
|
604 const TFSMailMsgId& aParentFolderId, |
|
605 const TFSMailMsgId& aMessageId, |
|
606 const TFSMailMsgId& aParentPartId, |
|
607 const TFSMailMsgId& aPartId) = 0; |
|
608 |
|
609 /** |
|
610 * Returns given message part. Ownership of object is transferred to caller. |
|
611 * |
|
612 * @param aMailBoxId defines mailbox where message is located |
|
613 * @param aParentFolderId defines parent folder where message is located |
|
614 * @param aMessageId gives the id of the message that message part belongs to |
|
615 * @param aMessagePartId gives the id of the message part |
|
616 */ |
|
617 virtual CFSMailMessagePart* MessagePartL( const TFSMailMsgId& aMailBoxId, |
|
618 const TFSMailMsgId& aParentFolderId, |
|
619 const TFSMailMsgId& aMessageId, |
|
620 const TFSMailMsgId& aMessagePartId) = 0; |
|
621 |
|
622 /** |
|
623 * |
|
624 * Retrieves a read-only file handle for the content file of this message part. |
|
625 * Should return KErrNotSupported if handle can not be given directly. In that case |
|
626 * FW will next ask to copy file to a temporary location so that FW can open the RFile |
|
627 * itself. Ownership of the handle is transferred. Caller is responsible for closing the |
|
628 * handle. |
|
629 * |
|
630 * @param aMailBoxId defines mailbox where message is located |
|
631 * @param aParentFolderId defines parent folder where message is located |
|
632 * @param aMessageId gives the id of the message that message part belongs to |
|
633 * @param aMessagePartId gives the id of the message part |
|
634 * @param aFileHandle returns the opened read-only file handle |
|
635 */ |
|
636 virtual TInt GetMessagePartFileL( const TFSMailMsgId& aMailBoxId, |
|
637 const TFSMailMsgId& aParentFolderId, |
|
638 const TFSMailMsgId& aMessageId, |
|
639 const TFSMailMsgId& aMessagePartId, |
|
640 RFile& aFileHandle) = 0; |
|
641 |
|
642 /** |
|
643 * copies message part to given location |
|
644 * |
|
645 * |
|
646 * @param aMailBoxId defines mailbox where message is located |
|
647 * @param aParentFolderId defines parent folder where message is located |
|
648 * @param aMessageId gives the id of the message that message part belongs to |
|
649 * @param aMessagePartId gives the id of the message part |
|
650 * @param aFilePath message part location |
|
651 */ |
|
652 virtual void CopyMessagePartFileL( const TFSMailMsgId& aMailBoxId, |
|
653 const TFSMailMsgId& aParentFolderId, |
|
654 const TFSMailMsgId& aMessageId, |
|
655 const TFSMailMsgId& aMessagePartId, |
|
656 const TDesC& aFilePath) = 0; |
|
657 |
|
658 |
|
659 /** |
|
660 * gets message part content to given buffer |
|
661 * |
|
662 * |
|
663 * @param aMailBoxId defines mailbox where message is located |
|
664 * @param aParentFolderId defines parent folder where message is located |
|
665 * @param aMessageId gives the id of the message that message part belongs to |
|
666 * @param aMessagePartId gives the id of the message part |
|
667 * @param aBuffer |
|
668 * @param aStartOffset |
|
669 */ |
|
670 virtual void GetContentToBufferL( const TFSMailMsgId& aMailBoxId, |
|
671 const TFSMailMsgId& aParentFolderId, |
|
672 const TFSMailMsgId& aMessageId, |
|
673 const TFSMailMsgId& aMessagePartId, |
|
674 TDes& aBuffer, |
|
675 const TUint aStartOffset) = 0; |
|
676 |
|
677 /** |
|
678 * stores message part content |
|
679 * |
|
680 * |
|
681 * @param aBuffer message part content |
|
682 * @param aMailBoxId defines mailbox where message is located |
|
683 * @param aParentFolderId defines parent folder where message is located |
|
684 * @param aMessageId gives the id of the message that message part belongs to |
|
685 * @param aMessagePartId gives the id of the message part |
|
686 */ |
|
687 virtual void SetContentL( const TDesC& aBuffer, |
|
688 const TFSMailMsgId& aMailBoxId, |
|
689 const TFSMailMsgId& aParentFolderId, |
|
690 const TFSMailMsgId& aMessageId, |
|
691 const TFSMailMsgId& aMessagePartId) = 0; |
|
692 |
|
693 /** |
|
694 * Removes fetched contents of these parts. |
|
695 * |
|
696 * @param aMailBoxId defines mailbox where message is located |
|
697 * @param aParentFolderId defines parent folder where message is located |
|
698 * @param aMessageId gives the id of the message that message part belongs to |
|
699 * @param aPartIds Array of message part ids. |
|
700 */ |
|
701 virtual void RemovePartContentL( const TFSMailMsgId& aMailBoxId, |
|
702 const TFSMailMsgId& aParentFolderId, |
|
703 const TFSMailMsgId& aMessageId, |
|
704 const RArray<TFSMailMsgId>& aPartIds) = 0; |
|
705 |
|
706 /** |
|
707 * Sets contents from given file. Possible old contents are replaced. |
|
708 * |
|
709 * |
|
710 * @param aMailBoxId defines mailbox where message is located |
|
711 * @param aParentFolderId defines parent folder where message is located |
|
712 * @param aMessageId gives the id of the message that message part belongs to |
|
713 * @param aMessagePartId gives the id of the message part |
|
714 * @param aFilePath Path to source file |
|
715 */ |
|
716 virtual void SetPartContentFromFileL( const TFSMailMsgId& aMailBoxId, |
|
717 const TFSMailMsgId& aParentFolderId, |
|
718 const TFSMailMsgId& aMessageId, |
|
719 const TFSMailMsgId& aMessagePartId, |
|
720 const TDesC& aFilePath) = 0; |
|
721 /** |
|
722 * stores message part data to message store after modifications (commit) |
|
723 * |
|
724 * @param aMailBoxId defines mailbox where message part is stored |
|
725 * @param aParentFolderId defines parent folder where message is located |
|
726 * @param aMessageId gives the id of the message that message part belongs to |
|
727 * @param aMessagePart message part data to be stored by plugin |
|
728 */ |
|
729 virtual void StoreMessagePartL( const TFSMailMsgId& aMailBoxId, |
|
730 const TFSMailMsgId& aParentFolderId, |
|
731 const TFSMailMsgId& aMessageId, |
|
732 CFSMailMessagePart& aMessagePart) = 0; |
|
733 |
|
734 /** |
|
735 * unregisters plugin request observer to cancel pending events |
|
736 * |
|
737 * @param aRequestId request id of the pending asynchronous request |
|
738 */ |
|
739 virtual void UnregisterRequestObserver(TInt aRequestId) = 0; |
|
740 |
|
741 // MESSAGE SENDING |
|
742 /** |
|
743 * DEPRECATED |
|
744 * |
|
745 * starts message sending done by plugin |
|
746 * cancellation is deleting the message from outbox |
|
747 * |
|
748 * @param aMessageId defines message id to be sent |
|
749 */ |
|
750 virtual void SendL( TFSMailMsgId aMessageId ) = 0; |
|
751 |
|
752 /** |
|
753 * starts message sending done by plugin |
|
754 * cancellation is deleting the message from outbox |
|
755 * |
|
756 * @param aMessage message to be sent |
|
757 */ |
|
758 virtual void SendMessageL( CFSMailMessage& aMessage ) = 0; |
|
759 |
|
760 /** |
|
761 * method to require pending asynchronous request status |
|
762 * |
|
763 * @param aRequestId identifies request if parallel requests exists |
|
764 * @return pending request status |
|
765 */ |
|
766 virtual TFSProgress StatusL( const TInt aRequestId ) = 0; |
|
767 |
|
768 /** |
|
769 * method for canceling pending request |
|
770 * @param aRequestId identifies request if parallel requests exists |
|
771 */ |
|
772 virtual void CancelL( const TInt aRequestId ) = 0; |
|
773 |
|
774 // Search API |
|
775 // OPEN: IDS plugin nippets? |
|
776 |
|
777 /** |
|
778 * Asyncronous call for starting search for given string. Only one search can be |
|
779 * performed at a time. |
|
780 * |
|
781 * |
|
782 * This function will search for message's containing the given search string. |
|
783 * The search will be performed on the all message fields: To, Cc, Bcc, subject, body. |
|
784 * The search client will be notified of each found message, |
|
785 * and upon completion of the search. Only one search can be performed at a time. |
|
786 * |
|
787 * To change the sort order in the search result, use the same search string in the |
|
788 * but change the aSortCriteria parameter. The store "caches" the search |
|
789 * results generated by the same search string. |
|
790 * |
|
791 * The function will leave with KErrInUse if a search is already in progress. |
|
792 * |
|
793 * /note Only works if the store is in an authenticated state, |
|
794 * otherwise this function leaves with KErrNotReady |
|
795 * |
|
796 * @paran aMailBoxId mailbox where messages are to be searched |
|
797 * @param aFolderIds list of folders where messages are to be searched |
|
798 * @param aSearchStrings text strings that will be searched from different message fields. |
|
799 * @param aSortCriteria sort criteria for the results |
|
800 * @param aSearchObserver client observer that will be notified about search status. |
|
801 * |
|
802 */ |
|
803 virtual void SearchL( const TFSMailMsgId& aMailBoxId, |
|
804 const RArray<TFSMailMsgId>& aFolderIds, |
|
805 const RPointerArray<TDesC>& aSearchStrings, |
|
806 const TFSMailSortCriteria& aSortCriteria, |
|
807 MFSMailBoxSearchObserver& aSearchObserver ) = 0; |
|
808 |
|
809 |
|
810 /** |
|
811 * Cancels current search. Does nothing if there is not any search. |
|
812 * The search client will not be called back after this function is called. |
|
813 * |
|
814 * \note CancelSearch() method does NOT clear the search result cached in the store. |
|
815 * A different sort order can be used for the same search string, and the |
|
816 * cache will be utilized. Only by using a different search string can the |
|
817 * cache be cleaned. |
|
818 * |
|
819 * @paran aMailBoxId mailbox where the search should be cancelled |
|
820 * |
|
821 */ |
|
822 virtual void CancelSearch( const TFSMailMsgId& aMailBoxId ) = 0; |
|
823 |
|
824 /** Inform the store to clean up its cache for search results. |
|
825 * |
|
826 * This method cancels the the ongoing search (if exists), and then clean ups store's cache. |
|
827 * |
|
828 * This function should be called when search results are no longer in display. |
|
829 * |
|
830 * @paran aMailBoxId mailbox where the search cache should be cleared |
|
831 * |
|
832 */ |
|
833 virtual void ClearSearchResultCache( const TFSMailMsgId& aMailBoxId ) = 0; |
|
834 |
|
835 /** |
|
836 * Adds a new event observer. There can be several observers active at the same time. |
|
837 * Caller MUST call RemoveObserver before destroying given observer object. |
|
838 * |
|
839 * @param aObserver observer implementation |
|
840 */ |
|
841 virtual void AddObserverL(MFSMailEventObserver& aObserver) = 0; |
|
842 |
|
843 /** |
|
844 * Removes observer |
|
845 * |
|
846 * @param aObserver observer implementation |
|
847 */ |
|
848 virtual void RemoveObserver(MFSMailEventObserver& aObserver) = 0; |
|
849 |
|
850 /** |
|
851 * Subscribes events from given mailbox. |
|
852 * UnsubscribeMailboxEvents MUST be called before destroying given observer object. |
|
853 * |
|
854 * @param aMailboxId id of target mailbox |
|
855 * @param aObserver observer implementation |
|
856 */ |
|
857 virtual void SubscribeMailboxEventsL(const TFSMailMsgId& aMailboxId, |
|
858 MFSMailEventObserver& aObserver) = 0; |
|
859 |
|
860 /** |
|
861 * Unsubscribes events from given mailbox |
|
862 * |
|
863 * @param aMailboxId id of target mailbox |
|
864 * @param aObserver observer implementation |
|
865 */ |
|
866 virtual void UnsubscribeMailboxEvents(const TFSMailMsgId& aMailboxId, |
|
867 MFSMailEventObserver& aObserver) = 0; |
|
868 |
|
869 /** |
|
870 * Returns the current sync state for this mailbox. |
|
871 * |
|
872 * @param aMailboxId id of target mailbox |
|
873 */ |
|
874 virtual TSSMailSyncState CurrentSyncState(const TFSMailMsgId& aMailboxId) = 0; |
|
875 |
|
876 /** |
|
877 * Sets the mailbox name for this mailbox. |
|
878 * |
|
879 * @param aMailboxId id of target mailbox |
|
880 * @param aMailboxName new name for the mailbox |
|
881 */ |
|
882 virtual void SetMailboxName(const TFSMailMsgId& aMailboxId, const TDesC& aMailboxName ); |
|
883 |
|
884 }; |
|
885 |
|
886 |
|
887 #endif // M_FSMAILPLUGIN_H |
|
888 |
|
889 // End of File |
|