IMAP4 client MTM interface, providing access to the email services using the IMAP4 protocol.

The class provides support for:

Note that CImap4ClientMtm does not support many of the generic functions defined by the CBaseMtm base class. In particular:

IMAP specific commands are issued through the InvokeAsyncFunctionL() 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(). (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:

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(). 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 InvokeAsyncFunctionL(). Synchronisation progress information is encapsulated in a TImap4SyncProgress object.

Settings that affect how a synchronisation is performed include:

--------------------------------------

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(). There are a large number of commands, for different combinations of these options:

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 InvokeAsyncFunctionL(). 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:

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:

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().

--------------------------------------

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() 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.