<?xml version="1.0" encoding="utf-8"?>
<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
<!-- This component and the accompanying materials are made available under the terms of the License 
"Eclipse Public License v1.0" which accompanies this distribution, 
and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
<!-- Initial Contributors:
    Nokia Corporation - initial contribution.
Contributors: 
-->
<!DOCTYPE concept
  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="GUID-1F755804-70D6-5635-B2F7-06F03C8D4B74" xml:lang="en"><title>IMAP4
MTM Overview</title><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>This section provides an overview of the Internet Message Access Protocol
(IMAP4) MTM. </p>
<section><title>Purpose</title> <p>Provides retrieval and management of email
on a remote Internet Message Access Protocol (IMAP4) server. </p> </section>
<section><title>Architectural relationships</title> <p>The Messaging Middleware
architecture defines a framework in which modules (MTMs) can be implemented
that provide support for particular messaging protocols. A client MTM provides
the API for application engines to use the protocol. The IMAP4 MTM API provides
the Client MTM API, plus supporting classes for IMAP4, see <xref href="GUID-9BB849A2-8F69-580D-8A52-C7002D919521.dita">Email
Overview</xref>. </p> </section>
<section><title>Description</title> <p>The API has two key concepts: IMAP4
Client MTM, and IMAP4 service settings. </p> <p><b>IMAP4 Client MTM</b> </p> <p>The
IMAP4 Client MTM provides IMAP-specific operations, the most important of
which are synchronising with a remote server, or folder on a remote server.
Some generic messaging operations, such as sending messages (for which you
should use SMTP), are not supported by the MTM. Extra functions are provided
for obtaining and setting IMAP4 service settings. </p> <p>The IMAP4 Client
MTM class is <xref href="GUID-2DEC2EBD-EC94-3BAF-AD9D-8900FCD1CABE.dita"><apiname>CImap4ClientMtm</apiname></xref> and it does not support many
of the generic functions defined by the <xref href="GUID-177AF50B-14EF-3C45-AE22-1FEE5678261D.dita"><apiname>CBaseMtm</apiname></xref> base class.
The IMAP4 Client MTM implements the standard Client MTM APIs and extensions
for the following operations: </p> <ul>
<li id="GUID-BD531DC9-0308-5A6E-A6BD-8A21E7F83DD7"><p> <b>Connecting, disconnecting,
synchronising, subscribing and unsubscribing folders </b>  </p> <p>These operations
are accessible as commands available through the <xref href="GUID-41E5C23D-CD5A-3DD3-BFCE-F8C576CE2149.dita"><apiname>InvokeAsyncFunction</apiname></xref> class
of the Client MTM. They are implemented as calls to the IMAP4 Server MTM. </p> </li>
<li id="GUID-15A978DB-B7D0-5DD6-BE57-2A79B020B8FA"><p> <b>Send on next connection</b>  </p> <p>If
the Client MTM gets a request to connect to an email server, it checks for
the IMAP4 settings. . If the send on next connection option is set, the Client
MTM launches the <filepath>autosend.exe</filepath> executable that handles
sending messages waiting in the outbox. </p> </li>
<li id="GUID-FD1C41EF-2B1D-5850-B14A-DC50CE94A053"><p> <b> Reply to and forward
messages</b>  </p> <p>These are accessible through the <xref href="GUID-4E0F9B6F-C46B-34BA-BB8C-0A75014D31FD.dita"><apiname>ReplyL()</apiname></xref> and <xref href="GUID-3BBE6922-4F08-36AB-BAA9-2F37D6819794.dita"><apiname>ForwardL()</apiname></xref> classes
of a Client MTM and are implemented as calls to the email utilities <xref href="GUID-3F7DC1AB-D13C-31E9-967B-526AD72CD498.dita"><apiname>CImEmailOperation</apiname></xref> class. </p> </li>
<li id="GUID-7F025996-0ABD-50DE-BC2F-908AE7D3AB7D"><p> <b>Reply to, forward,
create new, create receipt and forward as attachment </b>  </p> <p>These are
accessible as commands available through the <xref href="GUID-41E5C23D-CD5A-3DD3-BFCE-F8C576CE2149.dita"><apiname>InvokeAsyncFunction</apiname></xref> class
of the Client MTM. They are implemented as calls to <xref href="GUID-3F7DC1AB-D13C-31E9-967B-526AD72CD498.dita"><apiname>CImEmailOperation</apiname></xref>. </p> </li>
<li id="GUID-78221799-2E57-5082-A66E-FF19BACD90AF"><p> <b>Querying connection
status</b>  </p> <p>These commands let clients know whether the IMAP4 Server
MTM is connected to an email server and whether it is currently processing
a request. They are available through the <xref href="GUID-41E5C23D-CD5A-3DD3-BFCE-F8C576CE2149.dita"><apiname>InvokeAsyncFunction</apiname></xref> class
of the Client MTM. The Client MTM requests the information from the Server
MTM. </p> </li>
<li id="GUID-850927D5-5A35-5468-904A-EA71FE11C5F8"><p> <b>Compound connection
and synchronisation </b>  </p> <p>The IMAP4 Client MTM provides a compound
operation that connects and synchronises with an IMAP4 server. This operation
is implemented as a client-side object that combines requests to the IMAP4
Server MTM. The client-side operation can complete the client request either:
after the connection; after the connection and synchronisation; or after the
connection, synchronisation, and disconnection. The client keeps requesting
that the inbox be resynchronised at a configurable interval so new messages
received in the inbox on the server appears under the IMAP4 inbox. The <xref href="GUID-1D7F2733-BC6F-30EA-A40D-C8573545CCB0.dita"><apiname>CImapConnectAndSyncOp</apiname></xref> class
handles these compound operations. </p> </li>
<li id="GUID-F666A79F-9623-5E93-8CB0-133CAA07FE83"><p> <b>Compound connect
and copy, move or populate messages </b>  </p> <p>The IMAP4 Client MTM provides
a compound operation that connects to an IMAP4 server and copies, moves, or
populates messages. The implementation is provided by the <xref href="GUID-B9209668-D191-35F0-A02A-DABD6B1A706C.dita"><apiname>CImImap4GetMail</apiname></xref> class
which makes callbacks into the IMAP4 Client MTM. </p> </li>
<li id="GUID-1C58BE15-59F9-5915-8F5F-01374C87D071"><p> <b> Offline operations</b>  </p> <p>The
IMAP4 Client MTM has a command to cancel offline operations. This is available
through the <xref href="GUID-41E5C23D-CD5A-3DD3-BFCE-F8C576CE2149.dita"><apiname>InvokeAsyncFunction</apiname></xref> API of the Client MTM.
The Client MTM passes the request to the Server MTM. </p> </li>
</ul> <p><b>IMAP4 service settings</b> </p> <p>Settings for a service are
associated with a service-type entry in the Message Server's Message Store.
IMAP service settings, such as the user name and password, synchronisation
strategy, and the maximum number of messages to synchronise are specified
in this object. This is used by many IMAP components. </p> <p>The settings
are loaded when a connection is made to the server. However, the settings
are not actually stored in the message store, but in the device's Central
Repository data store. </p> <p>Encapsulation of service settings is provided
by the <xref href="GUID-55F11633-988C-39D5-ADE7-23C4966FD995.dita"><apiname>CImImap4Settings</apiname></xref> class. </p> <p><b>Get mail helper</b> </p> <p>The
helper wraps up many individual IMAP operations into a single call. A large
number of options are available, which fall into the following groups: </p> <ul>
<li id="GUID-CFAEF51C-65F1-5AC4-BF2D-DFEACA5899A7"><p>get mail when already
connected </p> </li>
<li id="GUID-D9BBC7C4-24C8-5E99-A2A9-CFA1214734C4"><p>connect, get mail and
then disconnect </p> </li>
<li id="GUID-C3FB09F4-09F4-5E97-9269-91A0E4AD03E5"><p>connect, get mail and
then stay online </p> </li>
</ul> <p>The get mail helper class is <xref href="GUID-B9209668-D191-35F0-A02A-DABD6B1A706C.dita"><apiname>CImImap4GetMail</apiname></xref>. </p> </section>
</conbody><related-links>
<link href="GUID-8B843382-D27A-5E36-8F60-304903F3AA41.dita"><linktext>Message Type
Module</linktext></link>
<link href="GUID-24860917-0FE2-5C8F-B436-96928350996E.dita"><linktext>Bearer Mobility
Overview</linktext></link>
<link href="GUID-E56E21A9-B545-5217-A877-E64D30275157.dita"><linktext>Using the
Policy Evaluator Plug-in</linktext></link>
<link href="GUID-931F2B0C-0F7D-5819-83AF-8EC2C8988538.dita"><linktext>Email   
             Settings</linktext></link>
<link href="GUID-8832AED4-6B9F-5B35-8211-0C6661CD6DCA.dita"><linktext>Email Tutorials</linktext>
</link>
<link href="GUID-D73AD200-BE4D-50BF-BCF9-14627DE530B7.dita"><linktext>Example code</linktext>
</link>
</related-links></concept>