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.
26 class TImImap4GetPartialMailInfo;
28 /** Default IMAP4 server port number. */
29 const TUint32 KIMAPDefaultPortNumber = 143;
31 /** Default inbox refresh rate in seconds. */
32 const TInt KImapDefaultInboxSyncRate = 300;
34 /** Default idle timeout in seconds. */
35 const TInt KImapDefaultIdleTimeout = 1740;
37 /** Default fetch size in bytes. */
38 const TUint KImapDefaultFetchSizeBytes = 20480;
43 const TInt32 KImImapSynchroniseAll = -1;
46 const TInt32 KImImapSynchroniseNone = 0;
50 Describes the folder subscription synchronisation strategy.
52 This specifies whether the local or remote folder subscription flags, or a
53 combination of both, are used to determine which mailboxes are synchronised.
54 For an overview of the synchronisation process, see CImap4ClientMtm.
56 @see CImImap4Settings::SetSynchronise()
57 @see CImImap4Settings::Synchronise()
64 /** Folders that are marked for subscription either locally or remotely are synchronised. */
66 /** Only folders marked for subscription locally are synchronised. */
68 /** Only folders marked for subscription remotely are synchronised. */
74 Specifies methods of synchronising IMAP4 subscription information with a server.
76 Subscription settings that have been set on folders on the local device, and
77 subscription settings that have been set on the corresponding mailboxes on the
78 remote server can be synchronised, as part of the synchronisation process
79 (see the overview for CImap4ClientMtm).
81 @see CImImap4Settings::SetSubscribe()
82 @see CImImap4Settings::Subscribe()
87 enum TFolderSubscribeType
89 /** Do not alter local or remote subscription information. */
91 /** Update local copy of subscription information when it is received from the
92 remote IMAP4 server at the beginning of the mail session. */
94 /** Update remote copy of subscription information so that it matches the local
95 subscription information. */
97 /** Merge local and remote subscription information, store updated information
98 on the remote server and store merged data on the local message store. */
104 Defines which components of a message to fetch when copying or moving from
107 @see CImImap4Settings::SetGetMailOptions()
108 @see CImImap4Settings::GetMailOptions()
113 enum TImap4GetMailOptions
115 /** Get message headers. */
116 EGetImap4EmailHeaders,
117 /** Get message body. */
118 EGetImap4EmailBodyText,
119 /** Get message body and attachments. */
120 EGetImap4EmailBodyTextAndAttachments,
121 /** Get message attachments. */
122 EGetImap4EmailAttachments,
123 /** Get message body, including non-plain or non-HTML alternative text parts (or attachments). */
124 EGetImap4EmailBodyAlternativeText
128 Defines which components of a message should be fetched partially when
129 fetching the message from a server.
137 enum TImImap4PartialMailOptions
139 /** No size limits, full message to be fetched.*/
141 /** Get body text only.
142 Gets text/plain part only if text/plain part size + text/html part size
143 is greater than body text size limit.
144 Gets text/plain part and text/html part if text/plain part size + text/html part size
145 is less than body text size limit of the message.*/
147 /** Gets all the attachments less than attachment size limit.*/
149 /** Gets the body text less than or equal to body text size limit and attachments
150 less than or equal to attachment size limit.*/
151 EBodyTextAndAttachments,
152 /** Gets the body text less than total size limit and also attachments whose size
153 is within total size limit minus fetched body parts.*/
155 /** Gets the body text less than total size limit and all non-HTML text attachments whose size
156 is within total size limit minus fetched body parts.*/
161 Flags to indicate what type of IMAP4 progress information is being returned.
166 enum TImap4ProgressType
168 /** Progress information is an TImap4GenericProgress object. */
169 EImap4GenericProgressType,
170 /** Progress information is an TImap4SyncProgress object. */
171 EImap4SyncProgressType
175 class TImap4GenericProgress
177 Progress information for an IMAP4 get operation.
179 For the 'get mail when already connected' operations, the progress state can
180 be obtained from TImap4GenericProgress::iState. In the case of the 'connect
181 and get mail and disconnect' and 'connect and get mail and stay online', the
182 actual progress defined in TImap4GenericProgress::iState will be of the form
183 of 'Copy New Mail', 'Populating Message Selection' etc. The sub-operation
184 state can then be obtained in the form of 'Connecting', 'Fetching', 'Disconnecting'
185 etc. from TImap4GenericProgress::iImap4SubStateProgress.
195 IMPORT_C TInt ConnectionState() const;
196 IMPORT_C TInt ConnectionIAP() const;
199 /** Operation type. */
200 enum TImap4GenericProgressOp
202 /** Connect operation. */
204 /** Disconnect operation. */
206 /** Sync operation. */
208 /** Select operation. */
210 /** Copy messages to local operation. */
212 /** Copy messages within remote server operation. */
214 /** Copy messages from local operation. */
216 /** Move messages to local operation. */
218 /** Move messages within remote server operation. */
220 /** Move messages from local operation. */
222 /** Message population operation. */
224 /** Delete operation. */
226 /** Offline delete operation. */
228 /** Offline undelete operation. */
230 /** Offline delete operation. */
232 /** Offline move messages to local operation. */
234 /** Offline copy messages from local operation. */
235 EOffLineCopyFromLocal,
236 /** Offline move messages from local operation. */
237 EOffLineMoveFromLocal,
238 /** Offline copy messages within remote server operation. */
239 EOffLineCopyWithinService,
240 /** Offline move messages within remote server operation. */
241 EOffLineMoveWithinService,
242 /** Offline message population operation. */
246 /** Operation state information. */
247 enum TImap4GenericProgressState
255 /** Selecting the folder to use. */
257 /** Fetching messages to mirror server. */
259 /** Appending local messages to remote server. */
261 /** Copying local messages to local or within service. */
263 /** Deleting an item, including expunging a folder. */
265 /** Synchronising folder after an operation. */
267 /** Disconnecting. */
269 /** Sync already in progress. */
271 /** CImImap4GetMail move operation in progress. */
273 /** CImImap4GetMail copy new mail operation in progress. */
275 /** CImImap4GetMail move new mail operation in progress. */
277 /** CImImap4GetMail copy selected messages operation in progress. */
279 /** CImImap4GetMail move selected messages operation in progress. */
281 /** CImImap4GetMail copy all messages operation in progress. */
283 /** CImImap4GetMail move all messages operation in progress. */
285 /** CImImap4GetMail populate new messages operation in progress. */
287 /** CImImap4GetMail populate all messages operation in progress. */
289 /** CImImap4GetMail populate selected messages operation in progress. */
290 EPopulateMailSelection
293 /** Progress information type: always EImap4GenericProgressType. */
294 TImap4ProgressType iType;
295 /** Operation type. */
296 TImap4GenericProgressOp iOperation;
300 For 'connect and get mail and disconnect' and 'connect and get mail and stay
301 online' type operations, additional sub-operation state can be obtained from
302 iImap4SubStateProgress.
304 TImap4GenericProgressState iState;
306 The progress sub-state.
308 This only applies to 'connect and get mail and disconnect' and 'connect and
309 get mail and stay online' type operations.
311 TImap4GenericProgressState iImap4SubStateProgress;
312 /** In the EConnecting state, this field holds the connection iap value,
313 otherwise it holds the number of messages still to be processed. */
315 /** In the EConnecting state, this field holds the connection stage value,
316 otherwise it holds the number of messages processed. */
318 /** Number of message parts still to be processed. */
320 /** Number of message parts processed. */
322 /** Number of bytes (for a multipart fetch) still to be processed. */
324 /** Number of bytes (for a multipart fetch) processed. */
328 /** Message ID returned from the operation. */
329 TMsvId iReturnedMsvId;
330 /** The total size of messages to be downloaded (bytes). */
335 class TImap4SyncProgress
337 IMAP4 synchronisation progress information.
339 The client may then use an object of this type created by the server MTM to
340 track synchronisation progress.
347 /** Synchronisation state. */
348 enum TImap4SyncProgressState
356 /** Disconnecting. */
358 /** Synchronising inbox. */
360 /** Synchronising folder tree. */
362 /** Checking remote subscription. */
363 ECheckRemoteSubscription,
364 /** Updating remote subscription. */
365 EUpdateRemoteSubscription,
366 /** Synchronising other information. */
370 /** Processing pending operations. */
371 EProcessingPendingOps
374 /** Progress information type: always EImapSyncProgressType. */
375 TImap4ProgressType iType;
376 /** Synchronisation state. */
377 TImap4SyncProgressState iState; // Where is the sync up to?
379 "Folders to do" count for synchronisation.
380 This is meaningful during the #ESyncOther and #EDeleting
381 synchronisation stages.
385 "Folders done" count for synchronisation.
386 This is meaningful during the #ESyncOther and #EDeleting
387 synchronisation stages.
391 "Message to do" count for synchronisation.
392 This is meaningful during the #ESyncInbox, #ESyncOther and #EProcessingPendingOps
393 synchronisation stages.
397 "Message done" count for synchronisation.
398 This is meaningful during the #ESyncInbox, #ESyncOther and #EProcessingPendingOps
399 synchronisation stages.
403 Number of headers fetched during synchronisation.
405 TInt iHeadersFetched;
407 Number of folders orphaned during synchronisation.
409 An orphaned folder is a local folder which existed
410 under the service, but which did not exist
411 on the remote server when synchronisation was done.
413 TInt iOrphanedFolders;
415 Number of new folders during synchronisation.
419 Number of orphaned messages during synchronisation.
421 An orphaned message is one which existed locally
422 under the service, but which did not exist
423 on the remote server when synchronisation was done.
425 TInt iOrphanedMessages;
427 Number of remote messages tagged for deletion.
429 In IMAP, messages can be flagged as deleted, before
430 they are later permanently removed.
432 TInt iRemoteMessagesDeleteTagged;
433 /** Number of messages fetched during synchronisation.
435 In the current implementation, this is always 0. Use
436 iHeadersFetched to get the number of headers fetched.
438 TInt iMessagesFetchedOK;
439 /** Number of message parts fetched during synchronisation.
441 In the current implementation, this is always 0.
443 TInt iMessagePartsFetchedOK;
444 /** Number of message parts not found during synchronisation.
446 In the current implementation, this is always 0.
448 TInt iMessagePartsNotFound;
449 /** Number of folders not found during synchronisation.
451 This can occur if the remote server returns an error when
452 a client attempts to select a folder during synchronisation.
454 TInt iFoldersNotFound;
455 /** Any error-code that the client needs to be informed of. */
459 class TImap4CompoundProgress
461 IMAP operation progress information.
463 The class supplies both the two IMAP progress types, generic and synchronisation.
465 The IMAP4 server MTM owns two IMAP4 sessions that are used independently of
466 each other to perform 'background' and 'foreground' operations. In a typical
467 situation, the user may be downloading the body parts of a message (populating)
468 in the foreground whilst in the background a full synchronisation may be underway.
469 In this scenario, the generic progress will give an indication of the 'foreground'
470 activity and the synchronisation progress will give an indication of the 'background'
471 progress. The synchronisation progress component of the compound progress
472 will always show the synchronisation progress irrespective of whether the
473 synchronisation is running in the foreground or the background.
480 /** Generic progress. */
481 TImap4GenericProgress iGenericProgress;
482 /** Synchronisation progress. */
483 TImap4SyncProgress iSyncProgress;
487 class CImImap4Settings : public CImBaseEmailSettings
489 Settings for connection to and use of an IMAP4 mail server and its mailboxes.
491 Messaging clients should use an instance of this class to specify and retrieve
492 configuration settings that are used by an IMAP4 service when executing email
495 Service settings include:
497 - server log on settings (user name and password)
498 - message header synchronisation strategy and synchronisation limits
499 - message getting options, such as maximum size. Note that these options
500 are not used by the IMAP MTM. They can be used by client applications to
501 store user preferences, and be used by the client when issuing get commands.
502 - miscelleanous settings, including whether IMAP IDLE should be used
504 CImImap4Settings objects are created and accessed through
505 CEmailAccounts. CEmailAccounts can also be used to get the
506 connection settings, such as the ISP to use, used to access an IMAP server.
508 Settings for a service are associated with a service-type entry in the Message
509 Server'smessage store. However the settings are not actually stored in the
510 message store, but in the device's Central Repository data store.
519 IMPORT_C CImImap4Settings();
520 IMPORT_C virtual ~CImImap4Settings();
521 IMPORT_C void Reset();
522 IMPORT_C const TPtrC8 LoginName() const;
523 IMPORT_C void SetLoginNameL(const TDesC8& aLoginName);
524 IMPORT_C const TPtrC8 Password() const;
525 IMPORT_C void SetPasswordL(const TDesC8& aPassword);
526 IMPORT_C const TPtrC8 FolderPath() const;
527 IMPORT_C void SetFolderPathL(const TDesC8& aFolderPath);
528 IMPORT_C const TPtrC8 SearchString() const;
529 IMPORT_C void SetSearchStringL(const TDesC8& aSearchString);
530 IMPORT_C TText8 PathSeparator() const;
531 IMPORT_C void SetPathSeparator(const TText8 aPathSeparator);
532 IMPORT_C TBool DisconnectedUserMode() const;
533 IMPORT_C void SetDisconnectedUserMode(TBool aFlag);
534 IMPORT_C void SetSynchronise(const TFolderSyncType aType);
535 IMPORT_C TFolderSyncType Synchronise() const;
536 IMPORT_C void SetSubscribe(const TFolderSubscribeType aType);
537 IMPORT_C TFolderSubscribeType Subscribe() const;
538 IMPORT_C TBool AutoSendOnConnect() const;
539 IMPORT_C void SetAutoSendOnConnect(TBool aFlag);
540 IMPORT_C TUint MaxEmailSize() const;
541 IMPORT_C void SetMaxEmailSize(const TUint aMaxEmailSize);
542 IMPORT_C TBool DeleteEmailsWhenDisconnecting() const;
543 IMPORT_C void SetDeleteEmailsWhenDisconnecting(TBool aFlag);
544 IMPORT_C TBool AcknowledgeReceipts() const;
545 IMPORT_C void SetAcknowledgeReceipts(TBool aFlag);
546 IMPORT_C TImap4GetMailOptions GetMailOptions() const;
547 IMPORT_C void SetGetMailOptions(TImap4GetMailOptions aGetMailOptions);
548 IMPORT_C CImImap4Settings& CopyL(const CImImap4Settings& aCImImap4Settings);
549 IMPORT_C TBool operator==(const CImImap4Settings& aCImImap4Settings) const;
550 IMPORT_C TInt32 InboxSynchronisationLimit() const;
551 IMPORT_C void SetInboxSynchronisationLimit(const TInt32 aInboxSyncLimit);
552 IMPORT_C TInt32 MailboxSynchronisationLimit() const;
553 IMPORT_C void SetMailboxSynchronisationLimit(const TInt32 aMailboxSyncLimit);
554 IMPORT_C TBool UpdatingSeenFlags() const;
555 IMPORT_C void SetUpdatingSeenFlags(TBool aFlag);
556 IMPORT_C TInt SyncRate() const;
557 IMPORT_C void SetSyncRateL(TInt aSyncRate);
558 IMPORT_C TUint FetchSize() const;
559 IMPORT_C void SetFetchSizeL(TUint aFetchSizeBytes);
560 IMPORT_C TBool ImapIdle() const;
561 IMPORT_C void SetImapIdle(TBool aFlag);
562 IMPORT_C TInt ImapIdleTimeout() const;
563 IMPORT_C void SetImapIdleTimeoutL(TInt aIdleTimeout);
564 IMPORT_C TImImap4PartialMailOptions PartialMailOptions() const;
565 IMPORT_C void SetPartialMailOptionsL(TImImap4PartialMailOptions aPartialMailOptions);
566 IMPORT_C TInt32 BodyTextSizeLimit() const;
567 IMPORT_C void SetBodyTextSizeLimitL(TInt32 aBodyTextSizeLimit);
568 IMPORT_C TInt32 AttachmentSizeLimit() const;
569 IMPORT_C void SetAttachmentSizeLimitL(TInt32 aAttachmentSizeLimit);
570 IMPORT_C TBool UseExpunge() const;
571 IMPORT_C void SetUseExpunge(TBool aFlag);
572 IMPORT_C void SetTlsSslDomainL(const TDesC8& aDomainName);
573 IMPORT_C TPtrC8 TlsSslDomain() const;
574 IMPORT_C void SetUseSyncDownloadRules(TBool aFlag);
575 IMPORT_C TBool UseSyncDownloadRules();
576 IMPORT_C void SetFolderSyncDisabled(TBool aFlag);
577 IMPORT_C TBool FolderSyncDisabled();
580 class TImImap4SettingsExtension
583 inline TImImap4SettingsExtension();
588 HBufC8* iSearchString;
589 HBufC8* iTlsSslDomain;
591 TInt iImapIdleTimeout;
592 TUint iFetchSizeBytes;
593 TImImap4PartialMailOptions iPartialMailOptions;
594 TInt32 iBodyTextSizeLimit;
595 TInt32 iAttachmentSizeLimit;
598 inline TImImap4SettingsExtension* Extension() const;
599 inline void CheckExtensionExistsL();
601 enum TImImap4EmailSettings
603 KImap4EmailSettingsClearFlag = 0x00000000,
604 KImap4BaseEmailSettingsLastUsedFlag = CImBaseEmailSettings::EBaseEmailSettingsLastUsedFlag, //0x00000002
605 KImap4EmailDisconnectedModeFlag = KImap4BaseEmailSettingsLastUsedFlag << 1, //0x00000004
606 KImap4EmailAutoSendFlag = KImap4EmailDisconnectedModeFlag << 1, //0x00000008
607 KImap4EmailDeleteEmailsWhenDisconnecting = KImap4EmailAutoSendFlag << 1, //0x00000010
608 KImap4EmailAcknowledgeReceipts = KImap4EmailDeleteEmailsWhenDisconnecting << 1, //0x00000020
609 KImap4EmailUpdatingSeenFlags = KImap4EmailAcknowledgeReceipts << 1, //0x00000040
610 KImap4EmailIdleFlag = KImap4EmailUpdatingSeenFlags << 1, //0x00000080
611 KImap4EmailExpungeFlag = KImap4EmailIdleFlag << 1,
612 KImap4EmailUseSyncDownloadRules = KImap4EmailExpungeFlag << 1, //0x00000200
613 KImap4EmailSettingsFolderSyncDisabled = KImap4EmailUseSyncDownloadRules << 1, //0x00000400
614 KImap4EmailSettingsLastUsedFlag = KImap4EmailSettingsFolderSyncDisabled
617 TImImap4SettingsExtension* iExtension; // renamed iReceiptAddress
619 TInt32 iInboxSyncLimit;
620 TInt32 iMailboxSyncLimit;
622 TText8 iPathSeparator;
623 TFolderSyncType iSynchroniseStrategy;
624 TFolderSubscribeType iSubscriptionStrategy;
625 TUint32 iMaxEmailSize;
626 TImap4GetMailOptions iGetMailOptions;
630 class TImImap4GetMailInfo
632 Specifies options used when retrieving messages with IMAP.
634 An TImImap4GetMailInfo is passed as a packaged parameter
635 to CImap4ClientMtm::InvokeAsyncFunctionL() when a message
636 getting command is issued.
638 Options include the maximum message size, and what
639 message parts are required.
649 /** The maximum message size (bytes).
650 Messages of greater size are not fetched. */
651 TInt32 iMaxEmailSize;
652 /** The required message parts. */
653 TImap4GetMailOptions iGetMailBodyParts;
654 /** The destination folder ID, specifying the
655 target folder when messages are copied or moved. */
656 TMsvId iDestinationFolder;
660 Specifies message criteria that are used as a filter when retrieving messages partially.
662 Options include the maximum size for the whole message,
663 the maximum size for the body of the message,
664 the maximum size for the attachments with the message, and
665 the message parts required.
667 An TImImap4GetPartialMailInfo is passed as a packaged parameter
668 to CImap4ClientMtm::InvokeAsyncFunctionL() when a message
669 populate command is issued.
678 class TImImap4GetPartialMailInfo : public TImImap4GetMailInfo
681 /** The maximum size limit for the total message (bytes). */
682 TInt32 iTotalSizeLimit;
683 /** The maximum size limit for body of the message (bytes). */
684 TInt32 iBodyTextSizeLimit;
685 /** The maximum size limit for the attachments (bytes). */
686 TInt32 iAttachmentSizeLimit;
687 /** The required message parts. */
688 TImImap4PartialMailOptions iPartialMailOptions;
691 inline CImImap4Settings::TImImap4SettingsExtension* CImImap4Settings::Extension() const
696 inline void CImImap4Settings::CheckExtensionExistsL()
699 iExtension=new (ELeave) CImImap4Settings::TImImap4SettingsExtension;
701 inline CImImap4Settings::TImImap4SettingsExtension::TImImap4SettingsExtension()
702 : iLoginName(NULL) ,iPassword(NULL) ,iFolderPath(NULL),iSearchString(NULL),iTlsSslDomain(NULL), iSyncRate(KImapDefaultInboxSyncRate), iImapIdleTimeout(KImapDefaultIdleTimeout), iFetchSizeBytes(KImapDefaultFetchSizeBytes),
703 iPartialMailOptions(ENoSizeLimits),iBodyTextSizeLimit(KMaxTInt),iAttachmentSizeLimit(KMaxTInt)
708 #endif // __IMAPSET_H__