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-5B43ED43-21B4-54C6-8637-76554769E6FE" xml:lang="en"><title>POP3

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

    14 <p>This section provides an overview of the Post Office Protocol (POP3) MTM

    15 component. </p>

    16 <section><title>Purpose</title> <p>Allows Internet email to be retrieved using

    17 the POP3 protocol. </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 POP3 MTM API provides

    22 the client MTM API, plus supporting classes for POP3, 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 four key concepts: POP3

    25 Client MTM, get mail helper, POP3 email settings, and email message entry

    26 information. </p> <p><b>POP3 Client MTM</b> </p> <p>The POP3 Client MTM provides

    27 MTM-specific operations for connection and mail retrieval. Some generic messaging

    28 operations, such as creating and sending messages, are not appropriate for

    29 POP3, and are not supported by the MTM. </p> <p>The POP3 Client MTM class

    30 is <xref href="GUID-40CB617C-849B-3377-A877-A90B43606CBC.dita"><apiname>CPop3ClientMtm</apiname></xref>. Most of the functions in this class

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

    32 class. The POP3-specific operations are defined in <xref href="GUID-BD51FABB-CD40-3F5C-BDEF-DD467CF2878A.dita"><apiname>TPop3Cmds</apiname></xref>. </p> <ul>

    33 <li id="GUID-4C414AB7-5D01-5F04-B5B1-EF1FF9D4D466"><p> <b> Reply to and forward

    34 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

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

    36 <li id="GUID-873EDAA6-42E5-549E-89E4-9FEDCA3E0C12"><p> <b>Reply to, forward,

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

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

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

    40 <li id="GUID-6AC1C5A2-B898-5108-AB4F-3C245E6843CE"><p> <b>Connecting, disconnecting

    41 and copying email while connected </b>  </p> <p>These operations are accessible

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

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

    44 <li id="GUID-99321F1B-DB0E-581A-9E32-2C581B5341CA"><p> <b>Querying connection

    45 status</b>  </p> <p>These commands let clients know whether the POP3 Server

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

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

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

    49 MTM. </p> </li>

    50 <li id="GUID-101CBE69-5DE6-5549-8CEE-8675B41338C1"><p> <b>Compound operation</b>  </p> <p>The

    51 Client MTM provides functionality to wrap up connecting to email servers,

    52 copying or moving new messages or a selection of messages, and then optionally

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

    54 of the Client MTM. The Client MTM implements this by using the <xref href="GUID-EBD29494-1DFA-3C87-82B0-C68908B1970E.dita"><apiname>CImPOP3GetMail</apiname></xref> class

    55 which requests the correct sequence of operations from the Server MTM, waiting

    56 for each operation to complete before requesting the next one. </p> </li>

    57 <li id="GUID-D392744A-7566-58A2-9884-04AD2DCF7F2E"><p> <b>Send on next connection </b>  </p> <p>If

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

    59 the POP3 settings. If the send on next connection option is set, the Client

    60 MTM launches the <filepath>autosend.exe</filepath> executable, which handles

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

    62 <li id="GUID-6A283BFD-1708-5F2F-B071-07BF3A1D2466"><p> <b> Offline operations</b>  </p> <p>The

    63 POP3 Client MTM has a command to cancel offline operations. This is available

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

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

    66 </ul> <p><b>Get mail helper</b> </p> <p>This encapsulates all the operations

    67 required to connect and retrieve mail. Options are available for moving or

    68 copying mail, and for getting all mail or selected mail. The get mail helper

    69 is provided by <xref href="GUID-EBD29494-1DFA-3C87-82B0-C68908B1970E.dita"><apiname>CImPOP3GetMail</apiname></xref>. </p> <p><b>POP3 email settings </b> </p> <p>The

    70 settings define email server and user log-on details. The settings are provided

    71 by the <xref href="GUID-6A7DFCF7-7268-3013-A5B6-5B77B6233329.dita"><apiname>CImPop3Settings</apiname></xref> class. </p> <p><b>Email message

    72 entry information</b> </p> <p>Protocol-specific data for a message is stored

    73 in fields in its index entry. A class <xref href="GUID-96CB1F06-0642-3313-8E18-1F68CBE26CCB.dita"><apiname>TMsvEmailEntry</apiname></xref> is

    74 provided to read these fields for e-mail protocols (including POP3). </p> </section>

    75 </conbody><related-links>

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

    77 Module</linktext></link>

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

    79              Settings</linktext></link>

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

    81 </link>

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

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

    84 <link href="GUID-BB35DBCC-FE56-547F-BADA-9EF854691ADC.dita"><linktext>Example code</linktext>

    85 </link>

    86 </related-links></concept>