![Symbian Developer Library](../../../../a_stock/images/mainheading.gif)
![]() |
![]() |
|
class CImap4ClientMtm : public CBaseMtm, public MImUndoOffLineOperation;
IMAP4 client MTM interface, providing access to the email services using the IMAP4 protocol.
The class provides support for:
connecting to remote IMAP4 mail servers
synchronising message headers with mailboxes on these servers
getting message bodies and attachments
copying and moving messages
creating messages that forward or reply to IMAP4 messages
server notification of new messages using IMAP IDLE
queueing operations requested when there is no connection to a mail server, to be performed when a connection is made (offline operations).
Note that CImap4ClientMtm does not support many of the generic functions defined by the CBaseMtm
base class. In particular:
Message address information, body, subjects, and attachments are not manipulated through CImap4ClientMtm. Consequently, CImap4ClientMtm::SaveMessageL()
has an empty implementation, and is not used. Message access and manipulation is instead done through CImEmailMessage
, which understands the email specific message formats, including MHTML (RFC 2557). The RFC 822 email header, which includes
subject and address information, is encapsulated in a CImHeader
object, which can be obtained from a CImEmailMessage
object. IMAP also has its own specific flags, such as draft, answered, and deleted: this can be accessed through TMsvEmailEntry
, which extends the message server's generic TMsvEntry
to add email-specific information.
The idea of a default service used by base class functions CImap4ClientMtm::DefaultServiceL()const
, CImap4ClientMtm::ChangeDefaultServiceL(const TMsvId &)
, and CImap4ClientMtm::RemoveDefaultServiceL()
is not supported.
IMAP specific commands are issued through the CImap4ClientMtm::InvokeAsyncFunctionL(TInt,const CMsvEntrySelection &,TDes8 &,TRequestStatus &)
function, with the commands defined in the TImap4Cmds
enumeration. Details of particular commands are given in the documentation for that enumeration, but the following describes
some of the key concepts required to use those commands. Note that usually these commands do not correspond directly to the
IMAP protocol commands described in RFC 3501. Instead, they are at a higher level, to simplify the logic required for an email
client program.
--------------------------------------
Connection and services
Settings for connection to and use of an IMAP4 mail server and its mailboxes are encapsulated in an CImImap4Settings
object, created and accessed through CEmailAccounts
. Preferences for the network connection (e.g. the ISP to use) to be made to access an IMAP server are also accessed through
CEmailAccounts
.
The settings are associated with a service-type entry in the Message Server's message store. Message and folder type entries under the service entry store a local copy of the mailboxes and messages that are present on an IMAP server. For this reason, the service is sometimes referred to as the local mirror of an IMAP server.
By default, it is assumed that the user has a primary mailbox on the server called INBOX, though this can be changed if necessary
using CImImap4Settings::SetFolderPathL(const TDesC8 &)
. (To avoid confusion, the term "Inbox" used in the IMAP MTM documentation refers to this mailbox, rather than the Message
Server's standard local Inbox folder.)
The settings store the user's log-in details required to access the IMAP server, and other settings not related to connection, but which affect the behaviour of commands, such as synchronisation, made to the service.
--------------------------------------
Synchronisation
The IMAP4 MTM provides the means to synchronise message headers on a remote IMAP mailboxes with the messages headers on the phone. Note that synchronisation only refers to message headers. Once headers are synchronised, populate operations (i.e. getting the message bodies) can be done.
The basic steps involved in a full synchronisation are:
The headers of messages in the Inbox are synchronised.
The local list of folders is synchronised with those existing on the remote IMAP service. Depending on the service settings, the local or remote settings of subscribed mailboxes may be updated (see below for more information).
The headers of messages in subscribed folders are synchronised.
Queued offline operations (see below) pending on the Inbox or subscribed folders are performed prior to the relevant folder being synchronised.
Synchronisations can be performed in the background or the foreground. A foreground synchronisation means no other requests,
such as message fetching, can be made to the MTM, until the synchronisation is complete. A background synchronisation allows
some types of command to be given while it is in progress. Commands that write to the remote server are not allowed however
while a background synchronisation is in progress. A client is informed of the state of a background synchronisation through
the MMsvImapConnectionObserver
callback interface.
Synchronisations commands are made through CImap4ClientMtm::InvokeAsyncFunctionL(TInt,const CMsvEntrySelection &,TDes8 &,TRequestStatus &)
. There a variety of commands available that give different options for compounding synchronisation with other commands, such
as connection, and synchronising only particular folders. See TImap4Cmds for details. Progress information for synchronisation
commands can be obtained from the CMsvOperation
object returned by the CImap4ClientMtm::InvokeAsyncFunctionL(TInt,const CMsvEntrySelection &,TDes8 &,TRequestStatus &)
. Synchronisation progress information is encapsulated in a TImap4SyncProgress
object.
Settings that affect how a synchronisation is performed include:
Subscriptions: when an IMAP service had been synchronised, the Messaging server will contain entries for all folders on the
remote server. These entries will be marked invisible within the TMsvEntry
for the folder, implying that they should be invisible to the user. Messages in these folders are not synchronised unless
the folder has been subscribed to. Note a folder subscription can be set either locally (i.e. just on the phone), using the
KIMAP4MTMLocalSubscribe
command, or remotely (on the server), possibly through email clients on other devices. A service can be set to synchronise
folders using either or both of these types of subscription (CImImap4Settings::SetSynchronise(const TFolderSyncType)
). Local and remote subscriptions can themselves be synchronised in various ways (CImImap4Settings::SetSuscribe()).
Filters: a filter prevents certain e-mail messages from being synchronised onto the device when a client requests a synchronisation. Filters can include anything permitted by the IMAP Search command, including date, size, content, and message flags.
Limits: service settings can limit the number of emails synchronised to the inbox (CImImap4Settings::SetInboxSynchronisationLimit(const TInt32)
), and to other folders (CImImap4Settings::SetMailboxSynchronisationLimit(const TInt32)
).
Sync rate: one of the synchronisation commands (KIMAP4MTMConnectAndSyncCompleteAfterDisconnect) periodically resynchronises
the Inbox until the service is disconnected. CImImap4Settings::SyncRate()const
sets the refresh period.
--------------------------------------
Getting and copying messages
After messages headers have been synchronised, message bodies and attachments can be fetched from the remote email server. Getting message parts and saving them in the mirror service is calling populating them.
Commands for these actions can be made through CImap4ClientMtm::InvokeAsyncFunctionL(TInt,const CMsvEntrySelection &,TDes8 &,TRequestStatus &)
. There are a large number of commands, for different combinations of these options:
action type: whether to just populate messages, or to also copy or move them to a local folder
message selection: whether to get all, new, or selected messages
connection: whether to make a new connection or assume an existing connection
disconnect: whether to disconnect or stay online after operation is complete
For the populate type commands, further options can be set that control the message getting behaviour. Basic options control,
encapsulated in TImImap4GetMailInfo
, specify whether body text and/or attachments are fetched, and a maximum message size. There are also options, encapsulated
in TImImap4GetPartialMailInfo
, that allow size limits to be separately specified for body text and/or attachments. If the the body is larger than the limit,
then the body is partially downloaded up to the limit. Only attachments smaller than the specified size are downloaded. A
partially downloaded message can later be fully downloaded.
For the copy or move type commands, a TImImap4GetMailInfo
parameter is supplied, in order to specify the destination folder for the messages, and a maximum message size.
Progress information for getting commands can be obtained from the CMsvOperation
object returned by the CImap4ClientMtm::InvokeAsyncFunctionL(TInt,const CMsvEntrySelection &,TDes8 &,TRequestStatus &)
. Progress information is encapsulated in a TImap4GenericProgress
object.
Fetching and then copying or moving specified messages can also be performed by using the standard Messaging Framework CMsvEntry::CopyL()
and CMsvEntry::MoveL()
functions on entries under the remote service. If these functions are used, then the entire message is fetched without size
limits.
CMsvEntry
functions can also be used to:
create a folder on a remote server
delete messages
copy or move messages from a local folder into a remote folder
copy or move messages between remote folders
Note that changing an existing entry through CMsvEntry
is not supported. An MTM- specific command KIMAP4MTMRenameFolder
is instead provided to rename a remote folder.
The page "CMsvEntry functions for IMAP4 message entries", linked to in the "See also" section below, provides more details
on using CMsvEntry
.
--------------------------------------
Offline operations
Some operations can only be performed while online, while other commands may be stored while offline for processing when next connected. An attempt to perform a command while offline that requires the MTM to be connected results in immediate completion with the error code KErrDisconnected.
Permitted offline operations include:
copy
move
delete
Queued offline operations are usually performed when a connection is made, prior to the relevant folder being synchronised.
Delete operations can alternatively be set to be done on disconnection using the service setting CImImap4Settings::SetDeleteEmailsWhenDisconnecting(TBool)
.
Note that:
Offline operations are only permitted if the service setting SetDisconnectedUserMode() is true.
It is possible to undo pending offline operations using the commands KIMAP4MTMCancelOffLineOperations
and KIMAP4MTMUndeleteAll
.
--------------------------------------
IMAP IDLE support
IMAP IDLE (RFC 2177) is an optional expansion of the IMAP email accessing protocol that allows the server to send updates
to the client that messages have been created or deleted in real time. The IDLE command is sent from the client to the server
when the client is ready to accept unsolicited mailbox update messages. Whether the client requests the server to provide
IDLE support is set in the CImImap4Settings::SetImapIdle(TBool)
service setting. When the IMAP MTM receives such a notification, it synchronises the changed folder. Email clients can be
notified of such changes by setting a MMsvEntryObserver
observer on a folder.
MImUndoOffLineOperation
- No description.
MMsvEntryObserver
- Provides the interface for notification of events associated with an entry.
CBase
-
Base class for all classes to be instantiated on the heap.
CBaseMtm
- Provides a high-level interface for accessing and manipulating a Message Server ...
CImap4ClientMtm
- IMAP4 client MTM interface, providing access to the email services using the IMA...
Defined in CImap4ClientMtm
:
AddAddresseeL(const TDesC &)
Message address function required by the base class, but not used for IMAP.AddAddresseeL(const TDesC &,const TDesC &)
Message address function required by the base class, but not used for IMAP.AddAttachmentL(RFile &,const TDesC8 &,TUint,TRequestStatus &)
Unsupported client MTM base class function.AddAttachmentL(const TDesC &,const TDesC8 &,TUint,TRequestStatus &)
Unsupported client MTM base class function.AddEntryAsAttachmentL(TMsvId,TRequestStatus &)
Unsupported client MTM base class function.AddLinkedAttachmentL(const TDesC &,const TDesC8 &,TUint,TRequestStatus &)
Unsupported client MTM base class function.ChangeDefaultServiceL(const TMsvId &)
Unsupported client MTM base class function.ContextEntrySwitched()
Called by the base class functions CBaseMtm::SwitchCurrentEntryL(TMsvId) and CBa...CreateAttachmentL(const TDesC &,RFile &,const TDesC8 &,TUint,TRequestStatus &)
Unsupported client MTM base class function.CreateMessageL(TMsvId)
Unsupported client MTM base class function.DefaultServiceL()const
Unsupported client MTM base class function.Find(const TDesC &,TMsvPartList)
Searches the specified message part(s) for the plain-text version of the text to...ForwardL(TMsvId,TMsvPartList,TRequestStatus &)
Creates an forwarded SMTP message from the current message context.Imap4Settings()const
Gets the IMAP4 email service settings currently being used by the client MTM, if...InvokeAsyncFunctionL(TInt,const CMsvEntrySelection &,TDes8 &,TRequestStatus &)
Invokes asynchronous IMAP-specific operations.InvokeSyncFunctionL(TInt,const CMsvEntrySelection &,TDes8 &)
Invokes synchronous IMAP-specific operations.LoadMessageL()
Loads the cache with the message data for the current message context.NewL(CRegisteredMtmDll &,CMsvSession &)
IMAP4 client MTM factory function.QueryCapability(TUid,TInt &)
Queries if the MTM supports a particular capability, specified by a UID.RemoveAddressee(TInt)
Message address function required by the base class, but not used for IMAP.RemoveDefaultServiceL()
Unsupported client MTM base class function.ReplyL(TMsvId,TMsvPartList,TRequestStatus &)
Creates an SMTP reply message to the current message context.RestoreSettingsL()
If the current context of the client MTM is on an IMAP4 service, restores settin...SaveMessageL()
Empty implementation of base class function.SetImap4SettingsL(const CImImap4Settings &)
Sets the IMAP4 email service settings.StoreSettingsL()
If the current context of the client MTM is an IMAP4 service, stores settings in...UndoOffLineChangesL(const CImOffLineOperation &,TMsvId)
This function is not supported.Inherited from CBase
:
Delete(CBase *)
Deletes the specified object.operator new(TUint)
Allocates the object from the heap and then initialises its contents to binary z...operator new(TUint,TAny *)
Initialises the object to binary zeroes.operator new(TUint,TLeave)
Allocates the object from the heap and then initialises its contents to binary z...operator new(TUint,TLeave,TUint)
Allocates the object from the heap and then initialises its contents to binary z...operator new(TUint,TUint)
Allocates the object from the heap and then initialises its contents to binary z...Inherited from CBaseMtm
:
AddAddresseeL(TMsvRecipientType,const TDesC &)
Adds addressee to list.AddAddresseeL(TMsvRecipientType,const TDesC &,const TDesC &)
Adds addressee to list.AddresseeList()const
Gets the list of intended recipients for the current context, which must be a me...BioTypeChangedL(TUid)
Informs client-side MTM that the context's BIO field is being changed as a resul...Body()
Gets the body text of the context, that must be a message. For non-message conte...Body()const
Gets the read-only body text of the context, that must be a message. For non-mes...CBaseMtm(CRegisteredMtmDll &,CMsvSession &)
Creates a CBaseMtm with member variables initialised from the passed arguments.CancelAttachmentOperation()
Cancels the current attachment operation. Entry()const
Gets a CMsvEntry for the current context. The message client application can the...Extension_(TUint,TAny *&,TAny *)
The default Extension service. The default implementation of this function assum...Filler1()
Filler2()
GetInterface(TUid)
Returns a pointer to the interface with the specified Uid.HandleEntryEventL(TMsvEntryEvent,TAny *,TAny *,TAny *)
Indicates that an event has occurred.HasContext()const
Tests if an MTM context has been set.RestoreBodyL(CMsvStore &)
Gets the current cached CRichText from the appropriate stream in the specified m...Session()
Gets a reference to the session object passed by the creator of the Client-side ...SetCurrentEntryL(CMsvEntry *)
Sets the entry on which later actions are performed to the specified CMsvEntry.SetMessageCharacterSet(TUint)
Sets the character encoding value. The character encoding value options are 7-bi...SetSubjectL(const TDesC &)
Sets the subject text of the context, which must be a message.StoreBodyL(CMsvStore &)
Stores and commits the current cached CRichText body text to the appropriate str...SubjectL()const
Gets the subject text of the context, which must be a message.SwitchCurrentEntryL(TMsvId)
Changes the entry on which later actions are performed to the entry with the spe...Type()const
Gets the Type UID of the message type associated with the Client-side MTM.ValidateMessage(TMsvPartList)
Validates the current message context.iAddresseeList
The address list for the current context. iCharFormatLayer
Character formatting applied to the CRichText object for the body text, as retur...iMsvEntry
The current context. iParaFormatLayer
Paragraph formatting applied to the CRichText object for the body text, as retur...Inherited from MMsvEntryObserver
:
EMsvChildrenChanged
One or more of the children have been changed. aArg1 points to a CMsvEntrySelect...EMsvChildrenInvalid
An error has occurred such that the status of the children is unknown and probab...EMsvChildrenMissing
Some new children have been created, but CMsvEntry was unable to retrieve the da...EMsvContextInvalid
The context has become invalid. The entry has been changed, but the CMsvEntry wa...EMsvDeletedChildren
Children have been deleted. aArg1 points to a CMsvEntrySelection contain the ID ...EMsvEntryChanged
The entry has been changed, either as a result of a CMsvEntry::ChangeL(const TMs...EMsvEntryDeleted
The entry has been deleted by another client. The context is now invalid. EMsvEntryMoved
The current entry has been moved by another client. The CMsvEntry has already be...EMsvNewChildren
New children have been created. aArg1 points to a CMsvEntrySelection contain the...TMsvEntryEvent
Defines entry event types. IMPORT_C static CImap4ClientMtm* NewL(CRegisteredMtmDll &aRegisteredMtmDll, CMsvSession &aSession);
IMAP4 client MTM factory function.
This function is not called directly by messaging clients. To create a client MTM object, use CClientMtmRegistry::NewMtmL(TUid)
.
|
|
CClientMtmRegistry::NewMtmL(TUid)
Creates a Client-side MTM object for the specified MTM UID.virtual CMsvOperation* ReplyL(TMsvId aDestination, TMsvPartList aPartList, TRequestStatus &aCompletionStatus);
Creates an SMTP reply message to the current message context.
|
|
virtual CMsvOperation* ForwardL(TMsvId aDestination, TMsvPartList aPartList, TRequestStatus &aCompletionStatus);
Creates an forwarded SMTP message from the current message context.
|
|
virtual TMsvPartList Find(const TDesC &aTextToFind, TMsvPartList aPartList);
Searches the specified message part(s) for the plain-text version of the text to be found.
|
|
virtual void SaveMessageL();
Empty implementation of base class function.
To edit an IMAP message, use CImEmailMessage
.
virtual void LoadMessageL();
Loads the cache with the message data for the current message context.
The current context should be an IMAP service or a message. If the current context is an IMAP service, then the function loads
the service settings from the Central Repository. This is the same behaviour as CImap4ClientMtm::RestoreSettingsL()
.
IMPORT_C void StoreSettingsL();
If the current context of the client MTM is an IMAP4 service, stores settings in the Central Repository.
|
IMPORT_C void RestoreSettingsL();
If the current context of the client MTM is on an IMAP4 service, restores settings from the Central Repository.
The restored settings can be accessed through the CImap4ClientMtm::Imap4Settings()const
function.
|
virtual TInt QueryCapability(TUid aCapability, TInt &aResponse);
Queries if the MTM supports a particular capability, specified by a UID.
|
|
virtual void InvokeSyncFunctionL(TInt aFunctionId, const CMsvEntrySelection &aSelection, TDes8 &aParameter);
Invokes synchronous IMAP-specific operations.
|
|
|
KIMAP4MTMIsConnected
Tests if a specified service is connected.KIMAP4MTMBusy
Tests if the server is busy.virtual CMsvOperation* InvokeAsyncFunctionL(TInt aFunctionId, const CMsvEntrySelection &aSelection, TDes8 &aParameter, TRequestStatus
&aCompletionStatus);
Invokes asynchronous IMAP-specific operations.
This provides support for a large number of IMAP-specific functions, including operations to:
Connect and logon to a remote server
Synchronise headers
Subscribe to mailboxes
Populate messages
Copy messages
Move messages
Create messages
Set offline behaviour
For details of operations, see TImap4Cmds
.
|
|
|
|
TImap4Cmds
IMAP4-specific commands that can be issued through either CImap4ClientMtm::Invok...virtual void AddAddresseeL(const TDesC &aRealAddress);
Message address function required by the base class, but not used for IMAP.
To modify message address information, use the address functions in CImHeader
.
|
virtual void AddAddresseeL(const TDesC &aRealAddress, const TDesC &aAlias);
Message address function required by the base class, but not used for IMAP.
To modify message address information, use the address functions in CImHeader
.
|
virtual void RemoveAddressee(TInt aIndex);
Message address function required by the base class, but not used for IMAP.
To modify message address information, use the address functions in CImHeader
.
|
IMPORT_C virtual void AddAttachmentL(const TDesC &aFilePath, const TDesC8 &aMimeType, TUint aCharset, TRequestStatus &aStatus);
Unsupported client MTM base class function.
To modify message attachments, use CImEmailMessage
.
|
|
IMPORT_C virtual void AddAttachmentL(RFile &aFile, const TDesC8 &aMimeType, TUint aCharset, TRequestStatus &aStatus);
Unsupported client MTM base class function.
To modify message attachments, use CImEmailMessage
.
|
|
IMPORT_C virtual void AddLinkedAttachmentL(const TDesC &aFilePath, const TDesC8 &aMimeType, TUint aCharset, TRequestStatus
&aStatus);
Unsupported client MTM base class function.
To modify message attachments, use CImEmailMessage
.
|
|
IMPORT_C virtual void AddEntryAsAttachmentL(TMsvId aAttachmentId, TRequestStatus &aStatus);
Unsupported client MTM base class function.
To modify message attachments, use CImEmailMessage
.
|
|
IMPORT_C virtual void CreateAttachmentL(const TDesC &aFileName, RFile &aAttachmentFile, const TDesC8 &aMimeType, TUint aCharset,
TRequestStatus &aStatus);
Unsupported client MTM base class function.
To modify message attachments, use CImEmailMessage
.
|
|
IMPORT_C virtual void CreateMessageL(TMsvId aServiceId);
Unsupported client MTM base class function.
To create a new message, use CImEmailOperation
.
|
|
IMPORT_C virtual TMsvId DefaultServiceL() const;
Unsupported client MTM base class function.
|
|
IMPORT_C virtual void RemoveDefaultServiceL();
Unsupported client MTM base class function.
|
IMPORT_C virtual void ChangeDefaultServiceL(const TMsvId &aService);
Unsupported client MTM base class function.
|
|
IMPORT_C const CImImap4Settings& Imap4Settings() const;
Gets the IMAP4 email service settings currently being used by the client MTM, if they exist.
If no settings exist, then an empty settings object will be returned by this function. Settings will only exist if a prior
call has been made to the CImap4ClientMtm::RestoreL()
function when the client MTM was positioned over an IMAP4 service in the message store.
|
IMPORT_C void SetImap4SettingsL(const CImImap4Settings &aSettings);
Sets the IMAP4 email service settings.
This can be called at any time to override any current email settings (if they exist). However, new settings are only used by the MTM if they have been stored and then a new IMAP4 email session has been started: i.e. settings cannot be changed in mid-session.
|
virtual void UndoOffLineChangesL(const CImOffLineOperation &aDeleted, TMsvId aFolderId);
This function is not supported.
|
protected: virtual void ContextEntrySwitched();
Called by the base class functions CBaseMtm::SwitchCurrentEntryL(TMsvId)
and CBaseMtm::SetCurrentEntryL(CMsvEntry *)
when the context is changed to another entry.
Client applications do not use this function. It is relevant only to implementers of derived classes.
Requirements:
An implementation should clear:
1. address data stored in iAddresseeList
2. any caches of MTM-specific entry data relating to a previous context. For example, if the implementation has a private buffer storing a message subject, for access through Subject(), this buffer should be cleared.