1 <?xml version="1.0" encoding="utf-8"?>

     2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

     3 <!-- This component and the accompanying materials are made available under the terms of the License 

     4 "Eclipse Public License v1.0" which accompanies this distribution, 

     5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE concept

    11   PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

    12 <concept id="GUID-1F755804-70D6-5635-B2F7-06F03C8D4B74" xml:lang="en"><title>IMAP4

    13 MTM Overview</title><prolog><metadata><keywords/></metadata></prolog><conbody>

    14 <p>This section provides an overview of the Internet Message Access Protocol

    15 (IMAP4) MTM. </p>

    16 <section><title>Purpose</title> <p>Provides retrieval and management of email

    17 on a remote Internet Message Access Protocol (IMAP4) server. </p> </section>

    18 <section><title>Architectural relationships</title> <p>The Messaging Middleware

    19 architecture defines a framework in which modules (MTMs) can be implemented

    20 that provide support for particular messaging protocols. A client MTM provides

    21 the API for application engines to use the protocol. The IMAP4 MTM API provides

    22 the Client MTM API, plus supporting classes for IMAP4, see <xref href="GUID-9BB849A2-8F69-580D-8A52-C7002D919521.dita">Email

    23 Overview</xref>. </p> </section>

    24 <section><title>Description</title> <p>The API has two key concepts: IMAP4

    25 Client MTM, and IMAP4 service settings. </p> <p><b>IMAP4 Client MTM</b> </p> <p>The

    26 IMAP4 Client MTM provides IMAP-specific operations, the most important of

    27 which are synchronising with a remote server, or folder on a remote server.

    28 Some generic messaging operations, such as sending messages (for which you

    29 should use SMTP), are not supported by the MTM. Extra functions are provided

    30 for obtaining and setting IMAP4 service settings. </p> <p>The IMAP4 Client

    31 MTM class is <xref href="GUID-2DEC2EBD-EC94-3BAF-AD9D-8900FCD1CABE.dita"><apiname>CImap4ClientMtm</apiname></xref> and it does not support many

    32 of the generic functions defined by the <xref href="GUID-177AF50B-14EF-3C45-AE22-1FEE5678261D.dita"><apiname>CBaseMtm</apiname></xref> base class.

    33 The IMAP4 Client MTM implements the standard Client MTM APIs and extensions

    34 for the following operations: </p> <ul>

    35 <li id="GUID-BD531DC9-0308-5A6E-A6BD-8A21E7F83DD7"><p> <b>Connecting, disconnecting,

    36 synchronising, subscribing and unsubscribing folders </b>  </p> <p>These operations

    37 are accessible as commands available through the <xref href="GUID-41E5C23D-CD5A-3DD3-BFCE-F8C576CE2149.dita"><apiname>InvokeAsyncFunction</apiname></xref> class

    38 of the Client MTM. They are implemented as calls to the IMAP4 Server MTM. </p> </li>

    39 <li id="GUID-15A978DB-B7D0-5DD6-BE57-2A79B020B8FA"><p> <b>Send on next connection</b>  </p> <p>If

    40 the Client MTM gets a request to connect to an email server, it checks for

    41 the IMAP4 settings. . If the send on next connection option is set, the Client

    42 MTM launches the <filepath>autosend.exe</filepath> executable that handles

    43 sending messages waiting in the outbox. </p> </li>

    44 <li id="GUID-FD1C41EF-2B1D-5850-B14A-DC50CE94A053"><p> <b> Reply to and forward

    45 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

    46 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>

    47 <li id="GUID-7F025996-0ABD-50DE-BC2F-908AE7D3AB7D"><p> <b>Reply to, forward,

    48 create new, create receipt and forward as attachment </b>  </p> <p>These are

    49 accessible as commands available through the <xref href="GUID-41E5C23D-CD5A-3DD3-BFCE-F8C576CE2149.dita"><apiname>InvokeAsyncFunction</apiname></xref> class

    50 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>

    51 <li id="GUID-78221799-2E57-5082-A66E-FF19BACD90AF"><p> <b>Querying connection

    52 status</b>  </p> <p>These commands let clients know whether the IMAP4 Server

    53 MTM is connected to an email server and whether it is currently processing

    54 a request. They are available through the <xref href="GUID-41E5C23D-CD5A-3DD3-BFCE-F8C576CE2149.dita"><apiname>InvokeAsyncFunction</apiname></xref> class

    55 of the Client MTM. The Client MTM requests the information from the Server

    56 MTM. </p> </li>

    57 <li id="GUID-850927D5-5A35-5468-904A-EA71FE11C5F8"><p> <b>Compound connection

    58 and synchronisation </b>  </p> <p>The IMAP4 Client MTM provides a compound

    59 operation that connects and synchronises with an IMAP4 server. This operation

    60 is implemented as a client-side object that combines requests to the IMAP4

    61 Server MTM. The client-side operation can complete the client request either:

    62 after the connection; after the connection and synchronisation; or after the

    63 connection, synchronisation, and disconnection. The client keeps requesting

    64 that the inbox be resynchronised at a configurable interval so new messages

    65 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

    66 handles these compound operations. </p> </li>

    67 <li id="GUID-F666A79F-9623-5E93-8CB0-133CAA07FE83"><p> <b>Compound connect

    68 and copy, move or populate messages </b>  </p> <p>The IMAP4 Client MTM provides

    69 a compound operation that connects to an IMAP4 server and copies, moves, or

    70 populates messages. The implementation is provided by the <xref href="GUID-B9209668-D191-35F0-A02A-DABD6B1A706C.dita"><apiname>CImImap4GetMail</apiname></xref> class

    71 which makes callbacks into the IMAP4 Client MTM. </p> </li>

    72 <li id="GUID-1C58BE15-59F9-5915-8F5F-01374C87D071"><p> <b> Offline operations</b>  </p> <p>The

    73 IMAP4 Client MTM has a command to cancel offline operations. This is available

    74 through the <xref href="GUID-41E5C23D-CD5A-3DD3-BFCE-F8C576CE2149.dita"><apiname>InvokeAsyncFunction</apiname></xref> API of the Client MTM.

    75 The Client MTM passes the request to the Server MTM. </p> </li>

    76 </ul> <p><b>IMAP4 service settings</b> </p> <p>Settings for a service are

    77 associated with a service-type entry in the Message Server's Message Store.

    78 IMAP service settings, such as the user name and password, synchronisation

    79 strategy, and the maximum number of messages to synchronise are specified

    80 in this object. This is used by many IMAP components. </p> <p>The settings

    81 are loaded when a connection is made to the server. However, the settings

    82 are not actually stored in the message store, but in the device's Central

    83 Repository data store. </p> <p>Encapsulation of service settings is provided

    84 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

    85 helper wraps up many individual IMAP operations into a single call. A large

    86 number of options are available, which fall into the following groups: </p> <ul>

    87 <li id="GUID-CFAEF51C-65F1-5AC4-BF2D-DFEACA5899A7"><p>get mail when already

    88 connected </p> </li>

    89 <li id="GUID-D9BBC7C4-24C8-5E99-A2A9-CFA1214734C4"><p>connect, get mail and

    90 then disconnect </p> </li>

    91 <li id="GUID-C3FB09F4-09F4-5E97-9269-91A0E4AD03E5"><p>connect, get mail and

    92 then stay online </p> </li>

    93 </ul> <p>The get mail helper class is <xref href="GUID-B9209668-D191-35F0-A02A-DABD6B1A706C.dita"><apiname>CImImap4GetMail</apiname></xref>. </p> </section>

    94 </conbody><related-links>

    95 <link href="GUID-8B843382-D27A-5E36-8F60-304903F3AA41.dita"><linktext>Message Type

    96 Module</linktext></link>

    97 <link href="GUID-24860917-0FE2-5C8F-B436-96928350996E.dita"><linktext>Bearer Mobility

    98 Overview</linktext></link>

    99 <link href="GUID-E56E21A9-B545-5217-A877-E64D30275157.dita"><linktext>Using the

   100 Policy Evaluator Plug-in</linktext></link>

   101 <link href="GUID-931F2B0C-0F7D-5819-83AF-8EC2C8988538.dita"><linktext>Email   

   102              Settings</linktext></link>

   103 <link href="GUID-8832AED4-6B9F-5B35-8211-0C6661CD6DCA.dita"><linktext>Email Tutorials</linktext>

   104 </link>

   105 <link href="GUID-D73AD200-BE4D-50BF-BCF9-14627DE530B7.dita"><linktext>Example code</linktext>

   106 </link>

   107 </related-links></concept>