23 #include <e32base.h> |
23 #include <e32base.h> |
24 |
24 |
25 #include "CFSMailClient.hrh" |
25 #include "CFSMailClient.hrh" |
26 #include "cemailextensionbase.h" |
26 #include "cemailextensionbase.h" |
27 |
27 |
28 #include "mfsmailbrandmanager.h" |
28 #include "MFSMailBrandManager.h" |
29 #include "cfsmailplugin.h" |
29 #include "cfsmailplugin.h" |
30 |
30 |
31 |
31 |
32 class CFSFWImplementation; |
32 class CFSFWImplementation; |
33 class CFSMailPluginManager; |
33 class CFSMailPluginManager; |
34 |
34 |
35 /** |
35 /** |
36 * @mainpage Freestyle Email API |
36 * @mainpage Freestyle Email API |
37 * |
37 * |
38 * @section sec1 Introduction |
38 * @section sec1 Introduction |
39 * |
39 * |
40 * This is the mail API and framework used by the Freestyle email |
40 * This is the mail API and framework used by the Freestyle email |
41 * client. It provides access to the message store for reading email |
41 * client. It provides access to the message store for reading email |
42 * and to the sync engine for starting and stopping synchronizations. |
42 * and to the sync engine for starting and stopping synchronizations. |
43 * |
43 * |
44 * @section sec2 Typical Usage From UI |
44 * @section sec2 Typical Usage From UI |
45 * |
45 * |
46 * // Initialize the access to the mail framework |
46 * // Initialize the access to the mail framework |
47 * CFSMailClient* mail = CFSMailClient::NewL(); |
47 * CFSMailClient* mail = CFSMailClient::NewL(); |
48 * CleanupClosePushL(*mail); |
48 * CleanupClosePushL(*mail); |
49 * |
49 * |
50 * // List mailboxes for user to select which one to open |
50 * // List mailboxes for user to select which one to open |
51 * RPointerArray<CFSMailBox> mailBoxes; |
51 * RPointerArray<CFSMailBox> mailBoxes; |
52 * mailBoxes.Reset(); |
52 * mailBoxes.Reset(); |
53 * TFSMailMsgId plugin; // null id if all mailboxes required |
53 * TFSMailMsgId plugin; // null id if all mailboxes required |
54 * mail->ListMailBoxes(plugin,mailBoxes); |
54 * mail->ListMailBoxes(plugin,mailBoxes); |
55 * // Lets select the first one this time |
55 * // Lets select the first one this time |
56 * CFSMailBox * currentMailbox = mailboxes[0]; |
56 * CFSMailBox * currentMailbox = mailboxes[0]; |
57 * |
57 * |
58 * // list all mailbox folders for user |
58 * // list all mailbox folders for user |
59 * RPointerArray<CFSMailFolder> folders = currentMailBox->ListFolders( ); |
59 * RPointerArray<CFSMailFolder> folders = currentMailBox->ListFolders( ); |
60 * |
60 * |
61 * // or get default folder, for example inbox |
61 * // or get default folder, for example inbox |
62 * TFSMailMsgId folderId; |
62 * TFSMailMsgId folderId; |
63 * folderId = mailBox->GetStandardFolderId( EFSInbox ); |
63 * folderId = mailBox->GetStandardFolderId( EFSInbox ); |
64 * CFSMailFolder* inbox = mail->GetFolderByUid(currentMailBox->GetId(),folderId); |
64 * CFSMailFolder* inbox = mail->GetFolderByUid(currentMailBox->GetId(),folderId); |
65 * |
65 * |
66 * // List messages in inbox |
66 * // List messages in inbox |
67 * // select message details to be listed |
67 * // select message details to be listed |
68 * TFSMailDetails details(EFSMsgDataStructure); |
68 * TFSMailDetails details(EFSMsgDataStructure); |
69 * |
69 * |
70 * // set sorting criteria |
70 * // set sorting criteria |
71 * TFSMailSortCriteria criteria; |
71 * TFSMailSortCriteria criteria; |
72 * criteria.iField = EFSMailSortByDate; |
72 * criteria.iField = EFSMailSortByDate; |
73 * criteria.iOrder = EFSMailAscending; |
73 * criteria.iOrder = EFSMailAscending; |
74 * RArray<TFSMailSortCriteria> sorting; |
74 * RArray<TFSMailSortCriteria> sorting; |
75 * sorting.Append(criteria); |
75 * sorting.Append(criteria); |
76 * |
76 * |
77 * // get email list iterator from plugin |
77 * // get email list iterator from plugin |
78 * MFSMailIterator* iterator = folder->ListMessagesL(details,sorting); |
78 * MFSMailIterator* iterator = folder->ListMessagesL(details,sorting); |
79 * |
79 * |
80 * // list all messages from folder |
80 * // list all messages from folder |
81 * TFSMailMsgId currentMessageId; // first call contains NULL id as begin id |
81 * TFSMailMsgId currentMessageId; // first call contains NULL id as begin id |
82 * RPointerArray<CFSMailMessage> messages; |
82 * RPointerArray<CFSMailMessage> messages; |
83 * messages.Reset(); |
83 * messages.Reset(); |
84 * iterator->NextL(currentMessageId, folder->GetMessageCount(), messages); |
84 * iterator->NextL(currentMessageId, folder->GetMessageCount(), messages); |
85 * |
85 * |
86 * // Show the first 5 messages to in the UI |
86 * // Show the first 5 messages to in the UI |
87 * for(TInt i=0;i<messages.Count() && i<5;i++) |
87 * for(TInt i=0;i<messages.Count() && i<5;i++) |
88 * { |
88 * { |
89 * MyHeaderShowMethod(messages[i]->GetSender().GetEmailAddress(), |
89 * MyHeaderShowMethod(messages[i]->GetSender().GetEmailAddress(), |
90 * messages[i]->GetSubject() |
90 * messages[i]->GetSubject() |
91 * messages[i]->GetDate()); |
91 * messages[i]->GetDate()); |
92 * |
92 * |
93 * // get email body |
93 * // get email body |
94 * CFSMailMessagePart* body = messages[i]->PlainTextBodyPartL(); |
94 * CFSMailMessagePart* body = messages[i]->PlainTextBodyPartL(); |
95 * if(body) |
95 * if(body) |
96 * { |
96 * { |
97 * TBuf<n> text; |
97 * TBuf<n> text; |
98 * TInt startOffset = 0; |
98 * TInt startOffset = 0; |
99 * body->GetContentToBufferL(text,startOffset); |
99 * body->GetContentToBufferL(text,startOffset); |
100 * MyPlainTextBodyShowMethod(text); |
100 * MyPlainTextBodyShowMethod(text); |
101 * delete body; |
101 * delete body; |
102 * } |
102 * } |
103 * |
103 * |
104 * //list email attachments |
104 * //list email attachments |
105 * RPointerArray<CFSMailMessagePart> attachments; |
105 * RPointerArray<CFSMailMessagePart> attachments; |
106 * attachments.Reset(); |
106 * attachments.Reset(); |
109 * { |
109 * { |
110 * MyShowAttachmentNameMethod(attachments[i]->AttachmentName()); |
110 * MyShowAttachmentNameMethod(attachments[i]->AttachmentName()); |
111 * } |
111 * } |
112 * attachments.ResetAndDestroy(); |
112 * attachments.ResetAndDestroy(); |
113 * } |
113 * } |
114 * |
114 * |
115 * // clean iterator and tables |
115 * // clean iterator and tables |
116 * messages.ResetAndDestroy(); |
116 * messages.ResetAndDestroy(); |
117 * delete iterator; |
117 * delete iterator; |
118 * sorting.Reset(); |
118 * sorting.Reset(); |
119 * delete folder; |
119 * delete folder; |
120 * |
120 * |
121 * // User should call close when terminating mail framework usage |
121 * // User should call close when terminating mail framework usage |
122 * // when shutting down application close mail client singleton |
122 * // when shutting down application close mail client singleton |
123 * CleanupStack::PopAndDestroy(mail); |
123 * CleanupStack::PopAndDestroy(mail); |
124 * |
124 * |
125 * @section sec3 Observing Email Events. |
125 * @section sec3 Observing Email Events. |
126 * |
126 * |
127 * // To be able to observe events an user has to |
127 * // To be able to observe events an user has to |
128 * // implement MFSMailEventObserver interface. |
128 * // implement MFSMailEventObserver interface. |
129 * // Here the COwnMailObserver class implements the interface. |
129 * // Here the COwnMailObserver class implements the interface. |
130 * COwnMailObserver* ownObserver = COwnMailObserver::NewL(); |
130 * COwnMailObserver* ownObserver = COwnMailObserver::NewL(); |
131 * |
131 * |
132 * // Register to observe mail store events |
132 * // Register to observe mail store events |
133 * mail->AddObserverL(*ownObserver); |
133 * mail->AddObserverL(*ownObserver); |
134 * |
134 * |
135 * // Now callbacks are done via the EventL function defined |
135 * // Now callbacks are done via the EventL function defined |
136 * // in the MFSMailEventObserver and implemented in this case |
136 * // in the MFSMailEventObserver and implemented in this case |
137 * // by the COwnMailObserver |
137 * // by the COwnMailObserver |
138 * |
138 * |
139 * // When user does not wish to observe events anymore |
139 * // When user does not wish to observe events anymore |
140 * // he has to unregister |
140 * // he has to unregister |
141 * mail->RemoveObserver( *ownObserver ); |
141 * mail->RemoveObserver( *ownObserver ); |
142 * |
142 * |
143 * // Remember that it must be done for each observer |
143 * // Remember that it must be done for each observer |
144 * // in the end of the observation because the AddObserverL |
144 * // in the end of the observation because the AddObserverL |
145 * // does not replace the observer |
145 * // does not replace the observer |
146 * |
146 * |
147 * @section sec_groups Classes |
147 * @section sec_groups Classes |
148 * |
148 * |
149 * The following classes form the public API of the frame work. |
149 * The following classes form the public API of the frame work. |
150 * |
150 * |
151 * @section sec_info More Information |
151 * @section sec_info More Information |
152 * |
152 * |
153 * Copyright © 2006 Nokia. All rights reserved. |
153 * Copyright © 2006 Nokia. All rights reserved. |
154 * |
154 * |
155 * This material, including documentation and any related computer programs, |
155 * This material, including documentation and any related computer programs, |
156 * is protected by copyright controlled by Nokia. All rights are reserved. |
156 * is protected by copyright controlled by Nokia. All rights are reserved. |
157 * Copying, including reproducing, storing, adapting or translating, any or |
157 * Copying, including reproducing, storing, adapting or translating, any or |
158 * 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 |
159 * material also contains confidential information which may not be disclosed |
159 * material also contains confidential information which may not be disclosed |
160 * to others without the prior written consent of Nokia. |
160 * to others without the prior written consent of Nokia. |
161 */ |
161 */ |
162 |
162 |
163 NONSHARABLE_CLASS(CFSMailClient) : public CExtendableEmail |
163 NONSHARABLE_CLASS(CFSMailClient) : public CExtendableEmail |
164 { |
164 { |
165 public: |
165 public: |
166 |
166 |
234 * @param aMessageId message id |
234 * @param aMessageId message id |
235 * @param aDetails defines which details are included in email object |
235 * @param aDetails defines which details are included in email object |
236 * |
236 * |
237 * @return email object (CFSMailMessage), ownership is transferred to user |
237 * @return email object (CFSMailMessage), ownership is transferred to user |
238 */ |
238 */ |
239 IMPORT_C CFSMailMessage* GetMessageByUidL(const TFSMailMsgId aMailBoxId, const TFSMailMsgId aFolderId, |
239 IMPORT_C CFSMailMessage* GetMessageByUidL(const TFSMailMsgId aMailBoxId, const TFSMailMsgId aFolderId, |
240 const TFSMailMsgId aMessageId, const TFSMailDetails aDetails ); |
240 const TFSMailMsgId aMessageId, const TFSMailDetails aDetails ); |
241 /** |
241 /** |
242 * deletes emails defined in message id list |
242 * deletes emails defined in message id list |
243 * |
243 * |
244 * @param aMailBoxId id of mailbox containing emails |
244 * @param aMailBoxId id of mailbox containing emails |
245 * @param aFolderId id of folder containing email |
245 * @param aFolderId id of folder containing email |
246 * @param aMessageIds defines ids of email to be deleted |
246 * @param aMessageIds defines ids of email to be deleted |
247 */ |
247 */ |
248 IMPORT_C void DeleteMessagesByUidL( const TFSMailMsgId aMailBoxId, const TFSMailMsgId aFolderId, |
248 IMPORT_C void DeleteMessagesByUidL( const TFSMailMsgId aMailBoxId, const TFSMailMsgId aFolderId, |
249 const RArray<TFSMailMsgId>& aMessageIds ); |
249 const RArray<TFSMailMsgId>& aMessageIds ); |
250 |
250 |
251 /** |
251 /** |
252 * Deletes mail account. This asynchronous operation returns id that can |
252 * Deletes mail account. This asynchronous operation returns id that can |
253 * be later used for cancelling the operation. |
253 * be later used for cancelling the operation. |
254 * |
254 * |