45 * @section sec2 Typical Usage From UI |
44 * @section sec2 Typical Usage From UI |
46 * |
45 * |
47 * // Initialize the access to the mail framework |
46 * // Initialize the access to the mail framework |
48 * CFSMailClient* mail = CFSMailClient::NewL(); |
47 * CFSMailClient* mail = CFSMailClient::NewL(); |
49 * CleanupClosePushL(*mail); |
48 * CleanupClosePushL(*mail); |
50 * |
49 * |
51 * // List mailboxes for user to select which one to open |
50 * // List mailboxes for user to select which one to open |
52 * RPointerArray<CFSMailBox> mailBoxes; |
51 * RPointerArray<CFSMailBox> mailBoxes; |
53 * mailBoxes.Reset(); |
52 * mailBoxes.Reset(); |
54 * TFSMailMsgId plugin; // null id if all mailboxes required |
53 * TFSMailMsgId plugin; // null id if all mailboxes required |
55 * mail->ListMailBoxes(plugin,mailBoxes); |
54 * mail->ListMailBoxes(plugin,mailBoxes); |
56 * // Lets select the first one this time |
55 * // Lets select the first one this time |
57 * CFSMailBox * currentMailbox = mailboxes[0]; |
56 * CFSMailBox * currentMailbox = mailboxes[0]; |
58 * |
57 * |
59 * // list all mailbox folders for user |
58 * // list all mailbox folders for user |
60 * RPointerArray<CFSMailFolder> folders = currentMailBox->ListFolders( ); |
59 * RPointerArray<CFSMailFolder> folders = currentMailBox->ListFolders( ); |
61 * |
60 * |
62 * // or get default folder, for example inbox |
61 * // or get default folder, for example inbox |
63 * TFSMailMsgId folderId; |
62 * TFSMailMsgId folderId; |
65 * CFSMailFolder* inbox = mail->GetFolderByUid(currentMailBox->GetId(),folderId); |
64 * CFSMailFolder* inbox = mail->GetFolderByUid(currentMailBox->GetId(),folderId); |
66 * |
65 * |
67 * // List messages in inbox |
66 * // List messages in inbox |
68 * // select message details to be listed |
67 * // select message details to be listed |
69 * TFSMailDetails details(EFSMsgDataStructure); |
68 * TFSMailDetails details(EFSMsgDataStructure); |
70 * |
69 * |
71 * // set sorting criteria |
70 * // set sorting criteria |
72 * TFSMailSortCriteria criteria; |
71 * TFSMailSortCriteria criteria; |
73 * criteria.iField = EFSMailSortByDate; |
72 * criteria.iField = EFSMailSortByDate; |
74 * criteria.iOrder = EFSMailAscending; |
73 * criteria.iOrder = EFSMailAscending; |
75 * RArray<TFSMailSortCriteria> sorting; |
74 * RArray<TFSMailSortCriteria> sorting; |
81 * // list all messages from folder |
80 * // list all messages from folder |
82 * TFSMailMsgId currentMessageId; // first call contains NULL id as begin id |
81 * TFSMailMsgId currentMessageId; // first call contains NULL id as begin id |
83 * RPointerArray<CFSMailMessage> messages; |
82 * RPointerArray<CFSMailMessage> messages; |
84 * messages.Reset(); |
83 * messages.Reset(); |
85 * iterator->NextL(currentMessageId, folder->GetMessageCount(), messages); |
84 * iterator->NextL(currentMessageId, folder->GetMessageCount(), messages); |
86 * |
85 * |
87 * // Show the first 5 messages to in the UI |
86 * // Show the first 5 messages to in the UI |
88 * for(TInt i=0;i<messages.Count() && i<5;i++) |
87 * for(TInt i=0;i<messages.Count() && i<5;i++) |
89 * { |
88 * { |
90 * MyHeaderShowMethod(messages[i]->GetSender().GetEmailAddress(), |
89 * MyHeaderShowMethod(messages[i]->GetSender().GetEmailAddress(), |
91 * messages[i]->GetSubject() |
90 * messages[i]->GetSubject() |
97 * { |
96 * { |
98 * TBuf<n> text; |
97 * TBuf<n> text; |
99 * TInt startOffset = 0; |
98 * TInt startOffset = 0; |
100 * body->GetContentToBufferL(text,startOffset); |
99 * body->GetContentToBufferL(text,startOffset); |
101 * MyPlainTextBodyShowMethod(text); |
100 * MyPlainTextBodyShowMethod(text); |
102 * delete body; |
101 * delete body; |
103 * } |
102 * } |
104 * |
103 * |
105 * //list email attachments |
104 * //list email attachments |
106 * RPointerArray<CFSMailMessagePart> attachments; |
105 * RPointerArray<CFSMailMessagePart> attachments; |
107 * attachments.Reset(); |
106 * attachments.Reset(); |
151 * |
150 * |
152 * @section sec_info More Information |
151 * @section sec_info More Information |
153 * |
152 * |
154 * Copyright © 2006 Nokia. All rights reserved. |
153 * Copyright © 2006 Nokia. All rights reserved. |
155 * |
154 * |
156 * This material, including documentation and any related computer programs, |
155 * This material, including documentation and any related computer programs, |
157 * is protected by copyright controlled by Nokia. All rights are reserved. |
156 * is protected by copyright controlled by Nokia. All rights are reserved. |
158 * Copying, including reproducing, storing, adapting or translating, any or |
157 * Copying, including reproducing, storing, adapting or translating, any or |
159 * all of this material requires the prior written consent of Nokia. This |
158 * all of this material requires the prior written consent of Nokia. This |
160 * material also contains confidential information which may not be disclosed |
159 * material also contains confidential information which may not be disclosed |
161 * to others without the prior written consent of Nokia. |
160 * to others without the prior written consent of Nokia. |
162 */ |
161 */ |
163 |
162 |
164 NONSHARABLE_CLASS(CFSMailClient) : public CExtendableEmail |
163 NONSHARABLE_CLASS(CFSMailClient) : public CExtendableEmail |
165 { |
164 { |
166 public: |
165 public: |
167 |
166 |
168 /** |
167 /** |
169 * Creates a new CFSMailClient singleton instance or increments |
168 * Creates a new CFSMailClient singleton instance or increments |
170 * reference count if singleton already exists |
169 * reference count if singleton already exists |
171 * |
170 * |
172 * @return CFSMailClient pointer |
171 * @return CFSMailClient pointer |
178 * reference count if singleton already exists |
177 * reference count if singleton already exists |
179 * |
178 * |
180 * @return CFSMailClient pointer |
179 * @return CFSMailClient pointer |
181 */ |
180 */ |
182 IMPORT_C static CFSMailClient* NewL( TInt aConfiguration ); |
181 IMPORT_C static CFSMailClient* NewL( TInt aConfiguration ); |
183 |
182 |
184 /** |
183 /** |
185 * Creates a new CFSMailClient singleton instance or increments |
184 * Creates a new CFSMailClient singleton instance or increments |
186 * reference count if singleton already exists |
185 * reference count if singleton already exists |
187 * |
186 * |
188 * @return CFSMailClient pointer |
187 * @return CFSMailClient pointer |
209 */ |
208 */ |
210 IMPORT_C TInt ListMailBoxes(const TFSMailMsgId aPluginId, RPointerArray<CFSMailBox>& aMailboxes); |
209 IMPORT_C TInt ListMailBoxes(const TFSMailMsgId aPluginId, RPointerArray<CFSMailBox>& aMailboxes); |
211 |
210 |
212 /** |
211 /** |
213 * returns email mailbox object related to given mailbox id |
212 * returns email mailbox object related to given mailbox id |
214 * |
|
215 * @param aMailBoxId mailbox id |
|
216 * @return mailbox object ( CFSMailBox ) |
|
217 * or NULL if no matching mailbox found. |
|
218 * Ownership is transferred to user! |
|
219 */ |
|
220 IMPORT_C CFSMailBox* GetMailBoxByUidL( const TFSMailMsgId aMailBoxId); |
|
221 |
|
222 |
|
223 /** |
|
224 * returns email mailbox object related to given mailbox id. Otherwise |
|
225 * identical to GetMailBoxByUidL but mailbox object is stored to cleanup |
|
226 * stack. |
|
227 * |
213 * |
228 * @param aMailBoxId mailbox id |
214 * @param aMailBoxId mailbox id |
229 * @return mailbox object ( CFSMailBox ) |
215 * @return mailbox object ( CFSMailBox ) |
230 * or NULL if no matching mailbox found. |
216 * or NULL if no matching mailbox found. |
231 * CFSMailBox pointer is stored to cleanup stack (even if NULL). |
217 * Ownership is transferred to user! |
232 * Ownership is transferred to user! |
218 */ |
233 */ |
219 IMPORT_C CFSMailBox* GetMailBoxByUidL( const TFSMailMsgId aMailBoxId); |
234 IMPORT_C CFSMailBox* GetMailBoxByUidLC( const TFSMailMsgId aMailBoxId); |
220 |
235 |
|
236 |
|
237 /** |
221 /** |
238 * returns email folder object related to given folder id |
222 * returns email folder object related to given folder id |
239 * |
223 * |
240 * @param aMailBoxId id of mailbox containing folder |
224 * @param aMailBoxId id of mailbox containing folder |
241 * @param aFolderId folder id |
225 * @param aFolderId folder id |
253 * @param aDetails defines which details are included in email object |
237 * @param aDetails defines which details are included in email object |
254 * |
238 * |
255 * @return email object (CFSMailMessage), ownership is transferred to user |
239 * @return email object (CFSMailMessage), ownership is transferred to user |
256 */ |
240 */ |
257 IMPORT_C CFSMailMessage* GetMessageByUidL(const TFSMailMsgId aMailBoxId, const TFSMailMsgId aFolderId, |
241 IMPORT_C CFSMailMessage* GetMessageByUidL(const TFSMailMsgId aMailBoxId, const TFSMailMsgId aFolderId, |
258 const TFSMailMsgId aMessageId, const TFSMailDetails aDetails ); |
242 const TFSMailMsgId aMessageId, const TFSMailDetails aDetails ); |
259 /** |
243 /** |
260 * deletes emails defined in message id list |
244 * deletes emails defined in message id list |
261 * |
245 * |
262 * @param aMailBoxId id of mailbox containing emails |
246 * @param aMailBoxId id of mailbox containing emails |
263 * @param aFolderId id of folder containing email |
247 * @param aFolderId id of folder containing email |
264 * @param aMessageIds defines ids of email to be deleted |
248 * @param aMessageIds defines ids of email to be deleted |
265 */ |
249 */ |
266 IMPORT_C void DeleteMessagesByUidL( const TFSMailMsgId aMailBoxId, const TFSMailMsgId aFolderId, |
250 IMPORT_C void DeleteMessagesByUidL( const TFSMailMsgId aMailBoxId, const TFSMailMsgId aFolderId, |
267 const RArray<TFSMailMsgId>& aMessageIds ); |
251 const RArray<TFSMailMsgId>& aMessageIds ); |
268 |
252 |
269 /** |
253 /** |
270 * Deletes mail account. This asynchronous operation returns id that can |
254 * Deletes mail account. This asynchronous operation returns id that can |
271 * be later used for cancelling the operation. |
255 * be later used for cancelling the operation. |
294 const TFSMailMsgId aFolderId, |
278 const TFSMailMsgId aFolderId, |
295 const TFSMailDetails aDetails, |
279 const TFSMailDetails aDetails, |
296 const RArray<TFSMailSortCriteria>& aSorting); |
280 const RArray<TFSMailSortCriteria>& aSorting); |
297 |
281 |
298 /** |
282 /** |
299 * returns branding manager to handle branding elements |
|
300 * |
|
301 * @return branding manager (ownership in framework) |
|
302 */ |
|
303 IMPORT_C MFSMailBrandManager& GetBrandManagerL( void ); |
|
304 |
|
305 /** |
|
306 * Adds a new event observer. There can be several observers active at |
283 * Adds a new event observer. There can be several observers active at |
307 * the same time. Caller MUST call RemoveObserver before destroying given |
284 * the same time. Caller MUST call RemoveObserver before destroying given |
308 * observer object. |
285 * observer object. |
309 * |
286 * |
310 * @param aObserver observer implementation |
287 * @param aObserver observer implementation |
311 */ |
288 */ |
312 IMPORT_C void AddObserverL(MFSMailEventObserver& aObserver); |
289 IMPORT_C void AddObserverL(MFSMailEventObserver& aObserver); |
313 |
290 |
314 /** |
291 /** |
315 * Removes event observer |
292 * Removes event observer |
316 * |
293 * |
317 * @param aObserver observer to be removed |
294 * @param aObserver observer to be removed |
318 */ |
295 */ |
319 IMPORT_C void RemoveObserver(MFSMailEventObserver& aObserver); |
296 IMPORT_C void RemoveObserver(MFSMailEventObserver& aObserver); |
320 |
297 |
321 /** |
|
322 * unregisters plugin request observer to cancel pending events |
|
323 * |
|
324 * @param aRequestId request id of the pending asynchronous request |
|
325 */ |
|
326 IMPORT_C void UnregisterRequestObserver(TInt aRequestId); |
|
327 |
298 |
328 /** |
299 /** |
329 * Subscribes events from given mailbox |
300 * Subscribes events from given mailbox |
330 * |
301 * |
331 * @param aMailboxId id of target mailbox |
302 * @param aMailboxId id of target mailbox |
341 * @param aObserver observer implementation |
312 * @param aObserver observer implementation |
342 */ |
313 */ |
343 IMPORT_C void UnsubscribeMailboxEvents(TFSMailMsgId aMailboxId, MFSMailEventObserver& aObserver); |
314 IMPORT_C void UnsubscribeMailboxEvents(TFSMailMsgId aMailboxId, MFSMailEventObserver& aObserver); |
344 |
315 |
345 /** |
316 /** |
346 * Sends notification to all protocol plugins that there is |
|
347 * Email Wizard data available for some of them. |
|
348 * |
|
349 * Can return any of the standard Symbian error codes if |
|
350 * one of the plugins reports failed mailbox configuration. |
|
351 */ |
|
352 IMPORT_C TInt WizardDataAvailableL(); |
|
353 |
|
354 /** |
|
355 * Client can call this function to immediately initialize authentications that are mandatory |
|
356 * to get services from protocol plugins. This means e.g. store authentications. FW will |
|
357 * internally ask authentication from all existing plugins before this operations completes. |
|
358 * |
|
359 * @param aOperationObserver is client provided observer that will receive progress |
|
360 * notifications during the operation. |
|
361 */ |
|
362 IMPORT_C TInt AuthenticateL(MFSMailRequestObserver& aOperationObserver); |
|
363 |
|
364 /** |
|
365 * get framework temp directory |
|
366 */ |
|
367 IMPORT_C TDesC& GetTempDirL( ); |
|
368 |
|
369 /** |
|
370 * clean framework temp directory |
|
371 */ |
|
372 IMPORT_C void CleanTempDirL( ); |
|
373 |
|
374 /** |
|
375 * cancels single pending asynchronous request |
317 * cancels single pending asynchronous request |
376 * |
318 * |
377 * @param aRequestId identifies request |
319 * @param aRequestId identifies request |
378 */ |
320 */ |
379 IMPORT_C void CancelL( const TInt aRequestId ); |
321 IMPORT_C void CancelL( const TInt aRequestId ); |
380 |
|
381 /** |
|
382 * cancels all pending asynchronous requests |
|
383 */ |
|
384 IMPORT_C void CancelAllL( ); |
|
385 |
|
386 /** |
|
387 * Calls plugin to change the name of the mailbox |
|
388 * |
|
389 * @param aMailboxId mailbox id |
|
390 * @param aMailboxName new name for the mailbox |
|
391 */ |
|
392 IMPORT_C void SetMailboxName( const TFSMailMsgId aMailboxId, const TDesC& aMailboxName ); |
|
393 |
|
394 |
322 |
395 //<qmail> |
323 //<qmail> |
396 /** |
324 /** |
397 * increments reference count to framework singleton |
325 * increments reference count to framework singleton |
398 * visibility change to public by Qmail |
326 * visibility change to public by Qmail |
399 */ |
327 */ |
400 IMPORT_C TInt IncReferenceCount(); |
328 IMPORT_C TInt IncReferenceCount(); |
401 //</qmail> |
329 |
402 |
|
403 |
|
404 /** |
330 /** |
405 * Prepares and sets the MR description by converting HTML body to Plain text |
331 * Prepares and sets the MR description by converting HTML body to Plain text |
406 * |
332 * |
407 * @param aMailboxId mailbox id |
333 * @param aMailboxId mailbox id |
408 * @param aMessageId message id |
334 * @param aMessageId message id |
409 */ |
335 */ |
410 IMPORT_C virtual void PrepareMrDescriptionL( const TFSMailMsgId& aMailBoxId, |
336 IMPORT_C virtual void PrepareMrDescriptionL( const TFSMailMsgId& aMailBoxId, |
411 const TFSMailMsgId& aMessageId ); |
337 const TFSMailMsgId& aMessageId ); |
412 // <qmail> |
|
413 /** |
338 /** |
414 * Gets the signature for the given mailbox. |
339 * Gets the signature for the given mailbox. |
415 * |
340 * |
416 * @param aMailBoxId mailbox id |
341 * @param aMailBoxId mailbox id |
417 */ |
342 */ |
418 IMPORT_C HBufC* GetSignatureL( const TFSMailMsgId& aMailBoxId ); |
343 IMPORT_C HBufC* GetSignatureL( const TFSMailMsgId& aMailBoxId ); |
419 // </qmail> |
344 // </qmail> |
420 |
345 |
421 public: // from CExtendableEmail |
346 public: // from CExtendableEmail |
422 |
347 |
423 /** |
348 /** |
424 * @see CExtendableEmail::ReleaseExtension |
349 * @see CExtendableEmail::ReleaseExtension |
425 */ |
350 */ |