<?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-24860917-0FE2-5C8F-B436-96928350996E" xml:lang="en"><title>Bearer
Mobility Overview</title><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>Bearer mobility allows the email Message Type Modules (MTM) to non-seamlessly
switch between networking bearers, such as, GPRS, WiFi, CDMA, GSM, and so
on. Switching between network bearers enables destination networks to connect
without dropping the connection with the remote server. </p>
<p>The POP3, IMAP4 and SMTP email server MTMs support this functionality. </p>
<section id="GUID-973000BE-9CE1-526D-ACC4-EA0ECFF3D93E"><title>Description</title> <p>The
bearer mobility must be enabled in the Networking bearer mobility framework
to provide bearer mobility functionality in the Messaging Application module. </p> <p>After
the bearer mobility is set for the email server MTMs at the client-side using
the <xref href="GUID-7E4A95AA-1614-3058-B08C-B81878C37489.dita"><apiname>SetBearerMobility</apiname></xref> function, the bearer mobility manager
registers with the bearer mobility framework in the Networking subsystem.
This informs the bearer mobility manager about any change in the bearers. </p> <p>The
bearer mobility plug-in gets the notifications about the change in the bearer.
When the required bearer is available, the server MTMs uses this plug-in to
get notifications. The following illustration shows the architecture of the
bearer mobility implementation in the Messaging Application module. </p> <fig id="GUID-3C8EB55A-9740-5249-8E82-1E6CD0B47F01">
<title>              Architecture of Bearer Mobility            </title>
<image href="GUID-5223D1C1-CBBE-551A-AC57-CD94F9D1B9B6_d0e273833_href.png" placement="inline"/>
</fig> </section>
<section><title>Settings</title> <p>The email client MTM <xref href="GUID-A7EF08E6-82AF-3577-B942-ABD532EDB7FE.dita"><apiname>CEmailAccounts</apiname></xref> interfaces
are enhanced to configure the email account settings. These settings modify
the behaviour of the relevant server MTMs for the following functionality: </p> <p><b>Non-seamless
bearer mobility</b> </p> <p>The IMAP4, POP3, and SMTP server MTMs are extended
to allow messaging applications to use the non-seamless network bearer mobility
when connecting to a destination network using the respective protocols. The
following functions are added to the <xref href="GUID-3EDD3DFA-AE8A-3941-960A-8BD2733E74C3.dita"><apiname>CImBaseEmailSettings</apiname></xref> (<xref href="GUID-6A7DFCF7-7268-3013-A5B6-5B77B6233329.dita"><apiname>CImPop3Settings</apiname></xref>, <xref href="GUID-55F11633-988C-39D5-ADE7-23C4966FD995.dita"><apiname>CImImap4Settings</apiname></xref>, and <xref href="GUID-DFE18962-0022-3833-A8F0-6E4C969177C0.dita"><apiname>CImSmtpSettings</apiname></xref>) class: </p> <ul>
<li id="GUID-2ED9D4E8-83F0-5264-88A0-3FC26A2DE9ED"><p> <xref href="GUID-7E4A95AA-1614-3058-B08C-B81878C37489.dita"><apiname>SetBearerMobility</apiname></xref>  </p> </li>
<li id="GUID-5653C643-85E3-57BD-ABF8-259AC244E52A"><p> <xref href="GUID-D3E8B8A1-1E78-369E-B09A-E4C6CDACED8A.dita"><apiname>BearerMobility()</apiname></xref>  </p> </li>
</ul> <p id="GUID-CC4028E7-ECD9-5045-9057-5BC687C3DF3A"><b>Per bearer-type
configuration for IMAP email accounts</b> </p> <p>Specifically for IMAP email
accounts, the <xref href="GUID-A7EF08E6-82AF-3577-B942-ABD532EDB7FE.dita"><apiname>CEmailAccounts</apiname></xref> class enables the following
per bearer-type configuration that affect the behaviour of IMAP accounts: </p> <ul>
<li id="GUID-EA24F6E4-D656-5053-996E-F75D645F318D"><p> <b>Download rules</b>  </p> <p>Download
rules specify which parts of message to automatically download (according
to bearer type) when synchronising the contents of an IMAP email account.
You can configure an IMAP email account for IMAP download rules on each bearer
type and for each account using the <xref href="GUID-1838902F-9077-36D8-AD22-5E36E0AFD51D.dita"><apiname>CImapSyncDownloadRules</apiname></xref> class. </p> <p>When
synchronising an IMAP email account you can do the following: </p> <ul>
<li id="GUID-B69ADD91-E4FC-57F1-8713-E1FD3539C16D"><p>Indicate that a list
of email download rules for each type of bearer must be used during the email
account synchronisations. </p> </li>
<li id="GUID-D5518521-4D23-53A1-A3B0-2925CB6DEC7A"><p>Retrieve emails during
the synchronisation using the mail options specified in the list for the bearer
type that is currently in use by the connection to the server. </p> </li>
</ul> <p>The <xref href="GUID-1838902F-9077-36D8-AD22-5E36E0AFD51D.dita"><apiname>CImapSyncDownloadRules</apiname></xref> class is used to store
per IMAP account sync download rules. This class describes the download rules
that provide the ability to automatically get the email content. This is configurable
on a per account and per bearer-type basis. </p><ul>
<li id="GUID-65E160D0-F45C-5B98-A11A-3EB1919EBF1B"><p>Different download rules
can be specified for different bearers. For example, you can specify that
all text and attachments should be retrieved when connecting through a WiFi
connection; whereas, only text parts should be retrieved when connecting over
GPRS connection. </p> </li>
<li id="GUID-8A4F7179-3E5A-5833-A12D-5E95EE927CA0"><p>Synchronisation is performed
in two stages: the email header synchronisation is performed first followed
by the email content retrieval. If the email account settings indicate that
the per-bearer-type list should not be used, or no per-bearer-type list is
defined, or the current bearer type is not listed in the per-bearer-type list,
then during the synchronisation the email headers for inbox and personal folders
are downloaded. </p> <p> <b>Note:</b> The per-bearer-type list is a set of
IMAP download and transport buffer size rules defined for each type of bearer. </p> </li>
<li id="GUID-692023AF-B834-584F-BD2F-78CFEF6A1D98"><p>Messages that are not
previously populated are retrieved using this method. So a message that has
been populated according to GPRS settings will not be retrieved again according
to WiFi settings, if a subsequent connection is made. </p> </li>
<li id="GUID-DF7A0844-5A4E-5BB0-B5CF-329171E0E185"><p>Messages that arrive
on the server while IMAP is in the <codeph>IDLE</codeph> state are also automatically
downloaded according to the Inbox download rules for the connected bearer
type. </p> </li>
<li id="GUID-694C4DDD-1579-5142-909B-9AB76BD8BBA9"><p>A single instance of
a set of download rules is applicable to multiple bearer types. </p> </li>
</ul> </li>
<li id="GUID-41D6D5F0-D9AF-5AAB-B45B-F69D62DA8DBA"><p> <b>Transport buffer
size</b>  </p> <p>Transport buffer size specifies the size of the data transferred
from server to client to get email body and attachments from an IMAP server
using a per bearer-type list of transport buffer sizes. You can configure
an IMAP account for IMAP transport buffer size on each bearer type using the <xref href="GUID-1CB521CD-BD46-37BE-B2BB-4817DFF73D73.dita"><apiname>CImapTransportBufferSizes</apiname></xref> class. </p><note> The
per-bearer-type list is a set of IMAP download and transport buffer size rules
defined for each type of bearer. </note> <p>This class allows a client to
configure transport buffer sizes of IMAP accounts according to the bearer
type for retrieving large message parts. It is possible to specify in the
following: </p> <ul>
<li id="GUID-9A27E24F-53E9-5962-A89E-4913B0BBF1CB"><p>Maximum retrieve size.
Default is 20480 octets. </p> </li>
<li id="GUID-751BA805-0E64-5B8A-AEA2-D814CE5355D1"><p>Maximum outstanding
retrieve requests. Default is two outstanding requests. </p> </li>
</ul> <p> <b>Important considerations</b>  </p> <ul>
<li id="GUID-2EDE94E1-8AC0-5AAA-A46A-D0317FF8874F"><p>If there are is no bearer
type specific list defined, or the current bearer type is not listed in the
per-bearer-type list of transport buffer sizes, then the maximum retrieve
request size specified in the email account settings is used. The maximum
and default number of outstanding retrieve requests is two. </p> </li>
<li id="GUID-4BBAAD4D-CA00-5E42-922C-D2456DD21212"><p>The transport buffer
sizes that can be specified are the maximum retrieve request size sent in
IMAP retrieve requests. </p> </li>
<li id="GUID-574B5003-E293-5ED2-932E-0F78188F2348"><p>Download email body
and attachments from an IMAP server using the retrieve request buffer size
specific to the bearer type that the server connection is using. </p> </li>
<li id="GUID-DCA1350E-9C6B-56F0-AF70-2A5C91C9149B"><p>Download email body
and attachments from an IMAP server using the maximum number of outstanding
retrieve requests specific to the bearer type that the server connection is
using. </p> </li>
<li id="GUID-DC672952-3FE1-5D72-8C6B-716FBF000222"><p>A single instance of
a set of transport buffer sizes is applicable to multiple bearer types. </p> </li>
</ul> </li>
</ul> <p><b>Bearer mobility policy plug-in</b> </p> <p>The bearer mobility
policy plug-in enables you to customise the migration behaviour of email accounts,
the bearer mobility policy plug-in is provided. It consists of an ECOM interface
class (<xref href="GUID-D3ED20A6-A16E-368E-98AD-820A469613EE.dita"><apiname>CImMobilityPolicyPlugin</apiname></xref>) and a call-back class (<xref href="GUID-73ABAC20-D43E-31B3-A6CB-95572D3140D2.dita"><apiname>MImMobilityPolicyHandler</apiname></xref>),which
allows the plug-in to issue policy decisions on an individual mobility events. </p> </section>
<section id="GUID-24BF7108-9229-5F0D-A3B0-27A8E419ABFF"><title>Important considerations</title> <ul>
<li id="GUID-F200A31C-6293-586A-AA4B-A9E052520DEE"><p>To enable bearer mobility,
you must first enable it at the Networking bearer mobility framework. </p> </li>
<li id="GUID-AF2642E1-8B84-505B-BFCC-C093DDF17ACE"><p>Bearer mobility is possible
only on the connections that are established using a SNAP preference list. </p> </li>
<li id="GUID-B9D2EF4B-EA15-5574-8DC1-2892349636D4"><p>To use the bearer mobility,
you must configure the email account settings to specify the SNAP preference
when creating the <xref href="GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD.dita"><apiname>RConnection</apiname></xref> notification (events). </p> </li>
<li id="GUID-84593BD5-376E-5302-8C9D-FBBBCB04BECD"><p>Multiple SNAP preferences
for each service entry is not supported. </p> </li>
<li id="GUID-BD5A6C40-B77A-5BBF-BB29-758391652A4B"><p>It is not possible to
specify both IAPs and a SNAP for a single email account. The API for setting
a SNAP preference clears any provisioned IAPs. Likewise, the API for setting
IAPs are updated to clear any SNAP preference that is set. </p> </li>
</ul> </section>
</conbody><related-links>
<link href="GUID-EBFE8B29-86AD-5785-8041-BCED2E90472E.dita"><linktext>SNAP Preferences</linktext>
</link>
<link href="GUID-786984BD-ADE8-5EF1-A819-F402F5703A80.dita"><linktext>Configuring
Non-seamless Bearer Mobility</linktext></link>
<link href="GUID-43CE4DCB-F498-5878-A2EE-7831BBB4D288.dita"><linktext>Configuring
TLS or SSL Socket</linktext></link>
<link href="GUID-A602A5BA-6C1F-5D8A-A6E7-50DECA1C64CC.dita"><linktext>SMTP Account
Override Settings</linktext></link>
<link href="GUID-75B1B1DF-4EC2-59BC-8BE0-A8AD681798C5.dita"><linktext>IMAP Account
Settings</linktext></link>
</related-links></concept>