Attempt to represent the S^2->S^3 header reorganisation as a series of "hg rename" operations
1 // Copyright (c) 1998-2009 Nokia Corporation and/or its subsidiary(-ies).
2 // All rights reserved.
3 // This component and the accompanying materials are made available
4 // under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
5 // which accompanies this distribution, and is available
6 // at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
8 // Initial Contributors:
9 // Nokia Corporation - initial contribution.
14 // Client MTM for the IMAP4 protocol
19 #if !defined (__IMPCMTM_H__)
22 #if !defined (__MTCLBASE_H_)
26 #if !defined (__MIUTHDR_H_)
30 #if !defined (__MIUTPARS_H__)
31 #include <miutpars.h> //TImMessageField
34 #if !defined (__IMAPSET_H__)
38 #if !defined (__IMAPCMDS_H__)
42 #if !defined(__OFFOP_H__)
46 #if !defined(__MIUTMSG_H__)
52 // Forward declarations.
53 class CImap4ClientSessionObserver;
54 class CImImap4GetMail;
55 class CImEmailAutoSend;
57 /////////////////////////////////////////////////////////////////////////////
59 class CImap4ClientMtm : public CBaseMtm, public MImUndoOffLineOperation
61 /** IMAP4 client MTM interface, providing access to the email services using the IMAP4
64 The class provides support for:
66 - connecting to remote IMAP4 mail servers
67 - synchronising message headers with mailboxes on these servers
68 - getting message bodies and attachments
69 - copying and moving messages
70 - creating messages that forward or reply to IMAP4 messages
71 - server notification of new messages using IMAP IDLE
72 - queueing operations requested when there is no connection to a mail server, to be
73 performed when a connection is made (offline operations).
75 Note that CImap4ClientMtm does not support many of the generic functions defined by
76 the @c CBaseMtm base class. In particular:
78 - Message address information, body, subjects, and attachments are not manipulated
79 through CImap4ClientMtm. Consequently, SaveMessageL() has an empty
80 implementation, and is not used. Message access and manipulation is instead done
81 through CImEmailMessage, which understands the email specific message formats,
82 including MHTML (RFC 2557). The RFC 822 email header, which includes subject and
83 address information, is encapsulated in a CImHeader object, which can be obtained from
84 a CImEmailMessage object. IMAP also has its own specific flags, such as draft,
85 answered, and deleted: this can be accessed through TMsvEmailEntry, which extends the
86 message server's generic TMsvEntry to add email-specific information.
88 - The idea of a default service used by base class functions DefaultServiceL(),
89 ChangeDefaultServiceL(), and RemoveDefaultServiceL() is not supported.
91 IMAP specific commands are issued through the InvokeAsyncFunctionL() function, with
92 the commands defined in the #TImap4Cmds enumeration. Details of particular commands
93 are given in the documentation for that enumeration, but the following describes some of
94 the key concepts required to use those commands. Note that usually these commands do
95 not correspond directly to the IMAP protocol commands described in RFC 3501. Instead,
96 they are at a higher level, to simplify the logic required for an email client program.
98 --------------------------------------
100 Connection and services
102 Settings for connection to and use of an IMAP4 mail server and its mailboxes are
103 encapsulated in an CImImap4Settings object, created and accessed through
104 CEmailAccounts. Preferences for the network connection (e.g. the ISP to use) to be made
105 to access an IMAP server are also accessed through CEmailAccounts.
107 The settings are associated with a service-type entry in the Message Server's message
108 store. Message and folder type entries under the service entry store a local copy of the
109 mailboxes and messages that are present on an IMAP server. For this reason, the service
110 is sometimes referred to as the local mirror of an IMAP server.
112 By default, it is assumed that the user has a primary mailbox on the server called INBOX,
113 though this can be changed if necessary using CImImap4Settings::SetFolderPathL(). (To
114 avoid confusion, the term "Inbox" used in the IMAP MTM documentation refers to this
115 mailbox, rather than the Message Server's standard local Inbox folder.)
117 The settings store the user's log-in details required to access the IMAP server, and other
118 settings not related to connection, but which affect the behaviour of commands, such as
119 synchronisation, made to the service.
121 --------------------------------------
125 The IMAP4 MTM provides the means to synchronise message headers on a remote
126 IMAP mailboxes with the messages headers on the phone. Note that synchronisation only
127 refers to message headers. Once headers are synchronised, populate operations (i.e.
128 getting the message bodies) can be done.
130 The basic steps involved in a full synchronisation are:
132 - The headers of messages in the Inbox are synchronised.
133 - The local list of folders is synchronised with those existing on the remote IMAP service.
134 Depending on the service settings, the local or remote settings of subscribed mailboxes
135 may be updated (see below for more information).
136 - The headers of messages in subscribed folders are synchronised.
138 Queued offline operations (see below) pending on the Inbox or subscribed folders are
139 performed prior to the relevant folder being synchronised.
141 Synchronisations can be performed in the background or the foreground. A foreground
142 synchronisation means no other requests, such as message fetching, can be made to the
143 MTM, until the synchronisation is complete. A background synchronisation allows some
144 types of command to be given while it is in progress. Commands that write to the remote
145 server are not allowed however while a background synchronisation is in progress. A
146 client is informed of the state of a background synchronisation through the
147 MMsvImapConnectionObserver callback interface.
149 Synchronisations commands are made through
150 CImap4ClientMtm::InvokeAsyncFunctionL(). There a variety of commands available
151 that give different options for compounding synchronisation
152 with other commands, such as connection, and synchronising only particular folders. See
153 TImap4Cmds for details. Progress information for synchronisation commands can be
154 obtained from the CMsvOperation object returned by the InvokeAsyncFunctionL().
155 Synchronisation progress information is encapsulated in a TImap4SyncProgress object.
157 Settings that affect how a synchronisation is performed include:
159 - Subscriptions: when an IMAP service had been synchronised, the Messaging server will
160 contain entries for all folders on the remote server. These entries will be marked invisible
161 within the TMsvEntry for the folder, implying that they should be invisible to the user.
162 Messages in these folders are not synchronised unless the folder has been subscribed to.
163 Note a folder subscription can be set either locally (i.e. just on the phone), using
164 the #KIMAP4MTMLocalSubscribe command, or remotely (on the server), possibly through email
165 clients on other devices. A service can be set to synchronise folders using either or both
166 of these types of subscription (CImImap4Settings::SetSynchronise()). Local and remote
167 subscriptions can themselves be synchronised in various ways (CImImap4Settings::SetSuscribe()).
169 - Filters: a filter prevents certain e-mail messages from being synchronised onto the
170 device when a client requests a synchronisation. Filters can include anything permitted by
171 the IMAP Search command, including date, size, content, and message flags.
173 - Limits: service settings can limit the number of emails synchronised to the inbox
174 (CImImap4Settings::SetInboxSynchronisationLimit()), and to other folders
175 (CImImap4Settings::SetMailboxSynchronisationLimit()).
177 - Sync rate: one of the synchronisation commands
178 (KIMAP4MTMConnectAndSyncCompleteAfterDisconnect) periodically resynchronises
179 the Inbox until the service is disconnected. CImImap4Settings::SyncRate() sets the
182 --------------------------------------
184 Getting and copying messages
186 After messages headers have been synchronised, message bodies and attachments can be
187 fetched from the remote email server. Getting message parts and saving them in the
188 mirror service is calling populating them.
190 Commands for these actions can be made through
191 CImap4ClientMtm::InvokeAsyncFunctionL(). There are a large number of commands,
192 for different combinations of these options:
194 - action type: whether to just populate messages, or to also copy or move them to a local
196 - message selection: whether to get all, new, or selected messages
197 - connection: whether to make a new connection or assume an existing connection
198 - disconnect: whether to disconnect or stay online after operation is complete
200 For the populate type commands, further options can be set that control the message
201 getting behaviour. Basic options control, encapsulated in TImImap4GetMailInfo, specify
202 whether body text and/or attachments are fetched, and a maximum message size. There
203 are also options, encapsulated in TImImap4GetPartialMailInfo, that allow size limits to
204 be separately specified for body text and/or attachments. If the the body is larger than the
205 limit, then the body is partially downloaded up to the limit. Only attachments smaller
206 than the specified size are downloaded. A partially downloaded message can later be
209 For the copy or move type commands, a TImImap4GetMailInfo parameter is supplied, in
210 order to specify the destination folder for the messages, and a maximum message size.
212 Progress information for getting commands can be obtained from the CMsvOperation
213 object returned by the InvokeAsyncFunctionL(). Progress information is encapsulated in
214 a TImap4GenericProgress object.
216 Fetching and then copying or moving specified messages can also be performed by using
217 the standard Messaging Framework @c CMsvEntry::CopyL() and @c
218 CMsvEntry::MoveL() functions on entries under the remote service. If these functions are
219 used, then the entire message is fetched without size limits.
221 CMsvEntry functions can also be used to:
223 - create a folder on a remote server
225 - copy or move messages from a local folder into a remote folder
226 - copy or move messages between remote folders
228 Note that changing an existing entry through CMsvEntry is not supported. An MTM-
229 specific command #KIMAP4MTMRenameFolder is instead provided to rename a remote
232 The page "CMsvEntry functions for IMAP4 message entries", linked to in the "See also"
233 section below, provides more details on using CMsvEntry.
235 --------------------------------------
239 Some operations can only be performed while online, while other commands may
240 be stored while offline for processing when next connected. An attempt to perform a
241 command while offline that requires the MTM to be connected results in immediate
242 completion with the error code KErrDisconnected.
244 Permitted offline operations include:
250 Queued offline operations are usually performed when a connection is made, prior to the
251 relevant folder being synchronised. Delete operations can alternatively be set to be done
252 on disconnection using the service setting
253 CImImap4Settings::SetDeleteEmailsWhenDisconnecting().
256 - Offline operations are only permitted if the service setting SetDisconnectedUserMode()
258 - It is possible to undo pending offline operations using the commands
259 #KIMAP4MTMCancelOffLineOperations and #KIMAP4MTMUndeleteAll.
261 --------------------------------------
265 IMAP IDLE (RFC 2177) is an optional expansion of the IMAP email accessing protocol
266 that allows the server to send updates to the client that messages have been created or
267 deleted in real time. The IDLE command is sent from the client to the server when the
268 client is ready to accept unsolicited mailbox update messages. Whether the client requests
269 the server to provide IDLE support is set in the CImImap4Settings::SetImapIdle() service
270 setting. When the IMAP MTM receives such a notification, it synchronises the changed
271 folder. Email clients can be notified of such changes by setting a MMsvEntryObserver
272 observer on a folder.
279 IMPORT_C static CImap4ClientMtm* NewL(CRegisteredMtmDll& aRegisteredMtmDll, CMsvSession& aSession);
282 void HandleEntryEvent(TMsvEntryEvent aEvent, TAny* aArg1, TAny* aArg2, TAny* aArg3);
283 void StoreL(); // uses a CMsvStore from the Session
285 CMsvOperation* ReplyL(TMsvId aDestination, TMsvPartList aPartList, TRequestStatus& aCompletionStatus);
286 CMsvOperation* ForwardL(TMsvId aDestination, TMsvPartList aPartList, TRequestStatus& aCompletionStatus);
287 TUint ValidateMessage(TUint aPartList);
288 TMsvPartList Find(const TDesC& aTextToFind, TMsvPartList aPartList);
291 IMPORT_C void StoreSettingsL(); // uses a CMsvStore from the session
292 IMPORT_C void RestoreSettingsL();
294 // --- RTTI functions ---
295 TInt QueryCapability(TUid aCapability, TInt& aResponse);
296 void InvokeSyncFunctionL(TInt aFunctionId, const CMsvEntrySelection& aSelection, TDes8& aParameter);
297 CMsvOperation* InvokeAsyncFunctionL(TInt aFunctionId, const CMsvEntrySelection& aSelection, TDes8& aParameter, TRequestStatus& aCompletionStatus);
298 // Addressees have no meaning in the text mtm.
299 void AddAddresseeL(const TDesC& aRealAddress);
300 void AddAddresseeL(const TDesC& aRealAddress, const TDesC& aAlias);
301 void RemoveAddressee(TInt aIndex);
303 // Attachment functions to support the SendAs API
305 IMPORT_C virtual void AddAttachmentL(const TDesC& aFilePath, const TDesC8& aMimeType, TUint aCharset, TRequestStatus& aStatus);
306 IMPORT_C virtual void AddAttachmentL(RFile& aFile, const TDesC8& aMimeType, TUint aCharset, TRequestStatus& aStatus);
307 IMPORT_C virtual void AddLinkedAttachmentL(const TDesC& aFilePath, const TDesC8& aMimeType, TUint aCharset, TRequestStatus& aStatus);
308 IMPORT_C virtual void AddEntryAsAttachmentL(TMsvId aAttachmentId, TRequestStatus& aStatus);
309 IMPORT_C virtual void CreateAttachmentL(const TDesC& aFileName, RFile& aAttachmentFile, const TDesC8& aMimeType, TUint aCharset, TRequestStatus& aStatus);
310 IMPORT_C void CreateMessageL(TMsvId aServiceId);
312 IMPORT_C virtual TMsvId DefaultServiceL() const;
313 IMPORT_C virtual void RemoveDefaultServiceL();
314 IMPORT_C virtual void ChangeDefaultServiceL(const TMsvId& aService);
316 public: // Returning a list of all the offline operations for a service entry.
317 IMPORT_C CImOperationQueueList* QueueListL(CMsvEntry& aServiceEntry);
318 public: // Wrapper to settings
319 IMPORT_C const CImImap4Settings& Imap4Settings() const;
320 IMPORT_C void SetImap4SettingsL(const CImImap4Settings& aSettings);
321 public: // inherited from MUndoOffLine
322 virtual void UndoOffLineChangesL(const CImOffLineOperation& aDeleted, TMsvId aFolderId);
324 CImap4ClientMtm(CRegisteredMtmDll& aRegisteredMtmDll, CMsvSession& aSession);
326 void ContextEntrySwitched(); // called after the context of this instance has been changed to another entry
329 TBool ValidateAddress(const TPtrC& anAddress);
330 void SendOnNextConnectionL();
331 TMsvPartList DoFindL(const TDesC& aTextToFind, TMsvPartList aPartList);
332 void FilterAllOrNewMailsL(TInt aFunctionId,const CMsvEntrySelection& aSelection,TDes8& aParameter);
333 void FilterMailSelectionL(const CMsvEntrySelection& aSelection,TDes8& aParameter);
334 CMsvOperation* CopyMoveOrPopulateL(TInt aFunctionId,TDes8& aParameter,TRequestStatus& aCompletionStatus);
335 void ConvertToPartialPopulate(TDes8& aParameter);
336 // To check whether a partial fetch or full fetch of message has to be done.
337 TBool IsPartialPopulate(TDes8& aParameter);
340 CImImap4Settings iImImap4Settings;
341 TImMessageField iTImMessageField;
342 CImap4ClientSessionObserver* iImap4ClientSessionObserver;
343 HBufC* iEmailAddressFormatString; // defines format of email address used by "Send as" API eg _L("/"%S/" <%S>")
345 CMsvEntrySelection* iMsvEntrySelection;
346 CImImap4GetMail* iImIMAP4GetMail;
347 CImEmailOperation* iImEmailOperation;
348 TPckgBuf<TImImap4GetPartialMailInfo> iImap4GetPartialMailInfo;
351 class CImImap4GetMail : public CMsvOperation
352 /** Encapsulates an operation to copy, move, and populate (i.e. download the full
353 message body) IMAP4 emails from the remote inbox to any local folder.
355 Note that the same operations are available by calling CImap4ClientMtm::InvokeAsyncFunctionL()
356 with a suitable command.
363 IMPORT_C CMsvOperation* GetMailL(TInt aFunctionId, CImap4ClientMtm& aImap4ClientMtm, const CMsvEntrySelection& aMsvEntrySelection, TDes8& aImap4GetMailInfo, TRequestStatus& aObserverRequestStatus);
367 const TDesC8& ProgressL();
368 const TDesC8& FinalProgress();
370 CImImap4GetMail(CMsvSession& aMsvSession, CImap4ClientMtm& aImap4ClientMtm, TRequestStatus& aObserverRequestStatus);
371 void ConstructL(TInt aFunctionId, const CMsvEntrySelection& aMsvEntrySelection, TDes8& aImap4GetMailInfo);
372 void SelectNextStateL(); // selects next state to go to
373 void ChangeStateL(); // initiates the next state operation
374 void SelectAndChangeToNextStateL();
375 void RequestComplete(TInt aError);
377 void ConnectToMailboxL();
378 void CopyMoveNewMessagesL(TBool aCopy);
379 void CopyMoveMessageSelectionL(TBool aCopy);
380 void CopyMoveAllMessagesL(TBool aCopy);
381 void PopulateNewMessagesL();
382 void PopulateAllMessagesL();
383 void PopulateMessageSelectionL();
384 void DisconnectFromMailboxL();
385 void ResetProgress();
386 void StoreProgressL();
388 enum TImImap4GetMailState
393 EPopulateNewMessages,
394 ECopyMessageSelection,
395 EMoveMessageSelection,
396 EPopulateMessageSelection,
399 EPopulateAllMessages,
400 EDisconnectFromMailbox,
404 CImap4ClientMtm& iImap4ClientMtm;
405 CMsvEntrySelection* iMsvEntrySelection;
406 CMsvOperation* iMsvOperation;
408 TImap4GenericProgress iProgress;
409 TImap4GenericProgress iErrorProgress;
410 TImImap4GetMailState iState;
412 TPckgBuf<TImap4GenericProgress> iProgressBuf;
413 TPckgBuf<TImImap4GetPartialMailInfo> iImap4GetPartialMailInfo;
416 #endif // __IMPCMTM_H__