<?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 xml:lang="en" id="GUID-9BB849A2-8F69-580D-8A52-C7002D919521"><title>Email Overview</title><prolog><metadata><keywords/></metadata></prolog><conbody><p>The Email collection provides support for sending and receiving emails using the individual email protocols, such as IMAP4, POP3 and SMTP, and also has support for parsing and generating plain and rich text, MIME and M-HTML format emails. </p> <section><title>Architecture</title> <p>The Email collection consists of a set of utilities and <xref href="GUID-8B843382-D27A-5E36-8F60-304903F3AA41.dita">MTMs</xref> for the POP3, IMAP4 and SMTP messaging protocols. </p> <fig id="GUID-3CF863C6-7627-55E4-951B-36BE4B4C43B9"><title>

             Email architecture 

          </title> <image href="GUID-51B0D0A9-C9FA-59DA-82B1-5834980CB35D_d0e271836_href.jpg" placement="inline"/></fig> <dl><dlentry><dt>Autosend</dt> <dd><p>Autosend is an executable file that is executed by the POP3 and IMAP4 client MTMs if the send on next connection setting is set. This executable makes a request to the SMTP server MTM to send messages associated with the SMTP service related to the POP3 or IMAP4 service, wait for the operation to finish and then exit. </p> </dd> </dlentry> <dlentry><dt>Server MTM</dt> <dd><p>A Server MTM provides specific message type storage and transport. It interacts with the Message Server to store and manage entries and provide a transport mechanism. </p> </dd> </dlentry> <dlentry><dt>Email client MTMs</dt> <dd><p>Email client MTMs provide client-side APIs (<filepath>IMCM DLL</filepath>) for IMAP4, POP3 and SMTP. </p> <p>The email client MTMs are used directly by clients to access parts of email messages for display. The <xref href="GUID-323E701E-EA22-3CC8-AE84-C16880608D44.dita"><apiname>CImEmailMessage</apiname></xref> class provides the functionality used by clients to display email messages, including listing attachments, getting body text and resolving URIs in M-HTML messages. </p> </dd> </dlentry> <dlentry><dt>Email client utilities </dt> <dd><p>The email client MTM uses the email client utilities when they are requested to create, reply to and forward messages. The <xref href="GUID-3F7DC1AB-D13C-31E9-967B-526AD72CD498.dita"><apiname>CImEmailOperation</apiname></xref> class provides the functionality to perform these operations. Each email is represented by a parent message entry with child entries that represent MIME folders and MIME parts. Adding or deleting MIME parts involves navigating the tree of entries and inserting or removing entries as appropriate. </p> </dd> </dlentry> <dlentry><dt>Email server utilities</dt> <dd><p>Email server utilities are responsible for generating and parsing of RFC2822 format email messages and providing an API to wrap up a TCP/IP connection to a remote email server. </p> </dd> </dlentry> </dl> </section> <section id="GUID-0E61C259-29CC-5FE3-AD4D-B2755F62A015"><title>Description</title> <p>Email messages are represented in a common format whether they are being sent by SMTP and downloaded by POP3 or IMAP4. Messaging clients can use the email client MTMs to create and compose email messages with attachments and a <xref href="GUID-17DE7D55-00C9-5D40-8AE4-39BDB20FCC5B.dita#GUID-17DE7D55-00C9-5D40-8AE4-39BDB20FCC5B/GUID-6E7D52CF-F18C-5C92-9DB2-611EDD018048">vCard</xref> signature. They can reply to or forward email messages. When connecting to a POP3 mailbox, just the header can be downloaded, or the entire message including attachments. However, when connecting to an IMAP4 mailbox, any or all of the following can be downloaded: </p> <ul><li id="GUID-4DBC9D2A-06F3-5282-A434-05AE87D82ABE"><p>the header </p> </li> <li id="GUID-BD0B15B3-713C-557B-9C01-2E73BB95DC7E"><p>the header and body text </p> </li> <li id="GUID-309E9C9C-EBB0-5363-847F-31986B64A10A"><p>the entire message including attachments </p> </li> <li id="GUID-98BFABA1-3706-5DE4-8990-AC29E249FAB7"><p>partial body text where the body text size limit is specified </p> </li> <li id="GUID-887FD8E3-BDEC-50E9-AA4B-3619DFF9CFA4"><p>download attachments if the attachment size is less then or equal to attachment size limit </p> </li> </ul> <p>Messaging clients can access any part of the message for display to the user. Messages can be moved or copied within folders on the local device and, for IMAP4 only, within the mailbox as well. </p> <p>Email client MTMs provide APIs that allow configuration information, such as secure or non-secure TCP/IP connection, username, password and message limits to be stored on the local device. Email client MTMs can be commanded to stay online during a client session, or connect and disconnect only when necessary. Operations such as moving, deleting, or sending a message while not connected can be queued for execution when the next connection to the subscriber's mailbox is established. </p> <p> <b>Note:</b> Email client MTMs are not responsible for any graphical or user interface associated functionality, such as rendering HTML or images, although they do provide access to images and HTML downloaded to the local device. </p> <p>For each email account a pair of services entries is created in the Message Store. For a POP3 account there will be an SMTP service and a POP3 service. For an IMAP4 account there will be an SMTP service and an IMAP4 service. These entries are used to store the settings for the email transport. Each of the service entry has its related ID that is set to the other member of the pair. The SMTP service is invisible, so that the user only sees the POP3 or IMAP4 service entry. Copying a message to the SMTP service causes the SMTP server MTM to attempt to send the message. The POP3 and IMAP4 MTMs provide functionality to synchronise with a remote email server by using the client MTM interface through the <xref href="GUID-0BD3DB31-2F8B-36B1-AF55-22E649D56164.dita"><apiname>InvokeAsync</apiname></xref> API. </p> <fig id="GUID-6BA2DAFE-B804-5D65-B350-5638DB31A366"><title>

             Email operation sequence diagram 

          </title> <image href="GUID-6E2F23B0-4765-5E4E-9B15-9F1D0EC5C28B_d0e271965_href.jpg" placement="inline"/></fig> </section> <section><title>Components</title> <p>The Email collection constitutes the following components: </p> <ul><li id="GUID-EA99CD44-E4C6-5067-954C-363FD6841440"><p><xref href="GUID-AFF7DA70-E993-5943-A27A-266541922E2F.dita">IMAP4 MTM</xref>  </p> </li> <li id="GUID-DE41A457-509E-505A-8229-506AEA78F9B1"><p><xref href="GUID-EADCDE6F-127E-528C-B2E0-F13E5C7FD4EF.dita">POP3 MTM</xref> </p> </li> <li id="GUID-CC0575AC-F1BC-5983-B589-83C2D048B2AC"><p><xref href="GUID-3988C2DE-3FC5-5AF8-BB9F-499E7082F7D5.dita">SMTP MTM</xref>  </p> </li> </ul> </section> <section><title>Using Email</title> <p>Email client applications can use the following functionality provided by the Email collection to: </p> <ul><li id="GUID-9C57E57B-F5E7-5087-ABEA-16431C8E6919"><p>Store emails including MIME headers, RFC2822 headers, attachments, body text and encoding information in the Message Store. </p> </li> <li id="GUID-54CDD32C-FEFB-57D1-BEFD-50B30FD6A03E"><p>Manipulate email messages, for example, adding attachments and replying. </p> </li> <li id="GUID-9C3725B3-738F-540A-8E36-6482FDE15AEA"><p>Encapsulate the character converters, which are used to convert between standard character sets and Unicode. </p> </li> <li id="GUID-4D56BD8D-9B80-55B6-9EF7-DB9847E69459"><p>Store email settings in the central repository. </p> </li> <li id="GUID-68F54B38-09EF-5D9D-B844-930E33B38BE4"><p>Get progress information for email operations. </p> </li> </ul> </section> </conbody><related-links><link href="GUID-8B843382-D27A-5E36-8F60-304903F3AA41.dita"><linktext>Message Type Module</linktext> </link> <link href="GUID-8832AED4-6B9F-5B35-8211-0C6661CD6DCA.dita"><linktext>Email Tutorials</linktext> </link> </related-links></concept>