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