<?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-5B43ED43-21B4-54C6-8637-76554769E6FE" xml:lang="en"><title>POP3
MTM Overview</title><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>This section provides an overview of the Post Office Protocol (POP3) MTM
component. </p>
<section><title>Purpose</title> <p>Allows Internet email to be retrieved using
the POP3 protocol. </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 POP3 MTM API provides
the client MTM API, plus supporting classes for POP3, see <xref href="GUID-9BB849A2-8F69-580D-8A52-C7002D919521.dita">Email
Overview</xref>. </p> </section>
<section><title>Description</title> <p>The API has four key concepts: POP3
Client MTM, get mail helper, POP3 email settings, and email message entry
information. </p> <p><b>POP3 Client MTM</b> </p> <p>The POP3 Client MTM provides
MTM-specific operations for connection and mail retrieval. Some generic messaging
operations, such as creating and sending messages, are not appropriate for
POP3, and are not supported by the MTM. </p> <p>The POP3 Client MTM class
is <xref href="GUID-40CB617C-849B-3377-A877-A90B43606CBC.dita"><apiname>CPop3ClientMtm</apiname></xref>. Most of the functions in this class
are implementations of the virtual functions defined by the <xref href="GUID-177AF50B-14EF-3C45-AE22-1FEE5678261D.dita"><apiname>CBaseMtm</apiname></xref> base
class. The POP3-specific operations are defined in <xref href="GUID-BD51FABB-CD40-3F5C-BDEF-DD467CF2878A.dita"><apiname>TPop3Cmds</apiname></xref>. </p> <ul>
<li id="GUID-4C414AB7-5D01-5F04-B5B1-EF1FF9D4D466"><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-873EDAA6-42E5-549E-89E4-9FEDCA3E0C12"><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-6AC1C5A2-B898-5108-AB4F-3C245E6843CE"><p> <b>Connecting, disconnecting
and copying email while connected </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 POP3 Server MTM. </p> </li>
<li id="GUID-99321F1B-DB0E-581A-9E32-2C581B5341CA"><p> <b>Querying connection
status</b>  </p> <p>These commands let clients know whether the POP3 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-101CBE69-5DE6-5549-8CEE-8675B41338C1"><p> <b>Compound operation</b>  </p> <p>The
Client MTM provides functionality to wrap up connecting to email servers,
copying or moving new messages or a selection of messages, and then optionally
disconnecting. These commands 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 implements this by using the <xref href="GUID-EBD29494-1DFA-3C87-82B0-C68908B1970E.dita"><apiname>CImPOP3GetMail</apiname></xref> class
which requests the correct sequence of operations from the Server MTM, waiting
for each operation to complete before requesting the next one. </p> </li>
<li id="GUID-D392744A-7566-58A2-9884-04AD2DCF7F2E"><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 POP3 settings. If the send on next connection option is set, the Client
MTM launches the <filepath>autosend.exe</filepath> executable, which handles
sending messages waiting in the outbox. </p> </li>
<li id="GUID-6A283BFD-1708-5F2F-B071-07BF3A1D2466"><p> <b> Offline operations</b>  </p> <p>The
POP3 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>Get mail helper</b> </p> <p>This encapsulates all the operations
required to connect and retrieve mail. Options are available for moving or
copying mail, and for getting all mail or selected mail. The get mail helper
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
settings define email server and user log-on details. The settings are provided
by the <xref href="GUID-6A7DFCF7-7268-3013-A5B6-5B77B6233329.dita"><apiname>CImPop3Settings</apiname></xref> class. </p> <p><b>Email message
entry information</b> </p> <p>Protocol-specific data for a message is stored
in fields in its index entry. A class <xref href="GUID-96CB1F06-0642-3313-8E18-1F68CBE26CCB.dita"><apiname>TMsvEmailEntry</apiname></xref> is
provided to read these fields for e-mail protocols (including POP3). </p> </section>
</conbody><related-links>
<link href="GUID-8B843382-D27A-5E36-8F60-304903F3AA41.dita"><linktext>Message Type
Module</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-E56E21A9-B545-5217-A877-E64D30275157.dita"><linktext>Using the
Policy Evaluator Plug-in</linktext></link>
<link href="GUID-BB35DBCC-FE56-547F-BADA-9EF854691ADC.dita"><linktext>Example code</linktext>
</link>
</related-links></concept>