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-24860917-0FE2-5C8F-B436-96928350996E" xml:lang="en"><title>Bearer

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

    14 <p>Bearer mobility allows the email Message Type Modules (MTM) to non-seamlessly

    15 switch between networking bearers, such as, GPRS, WiFi, CDMA, GSM, and so

    16 on. Switching between network bearers enables destination networks to connect

    17 without dropping the connection with the remote server. </p>

    18 <p>The POP3, IMAP4 and SMTP email server MTMs support this functionality. </p>

    19 <section id="GUID-973000BE-9CE1-526D-ACC4-EA0ECFF3D93E"><title>Description</title> <p>The

    20 bearer mobility must be enabled in the Networking bearer mobility framework

    21 to provide bearer mobility functionality in the Messaging Application module. </p> <p>After

    22 the bearer mobility is set for the email server MTMs at the client-side using

    23 the <xref href="GUID-7E4A95AA-1614-3058-B08C-B81878C37489.dita"><apiname>SetBearerMobility</apiname></xref> function, the bearer mobility manager

    24 registers with the bearer mobility framework in the Networking subsystem.

    25 This informs the bearer mobility manager about any change in the bearers. </p> <p>The

    26 bearer mobility plug-in gets the notifications about the change in the bearer.

    27 When the required bearer is available, the server MTMs uses this plug-in to

    28 get notifications. The following illustration shows the architecture of the

    29 bearer mobility implementation in the Messaging Application module. </p> <fig id="GUID-3C8EB55A-9740-5249-8E82-1E6CD0B47F01">

    30 <title>              Architecture of Bearer Mobility            </title>

    31 <image href="GUID-5223D1C1-CBBE-551A-AC57-CD94F9D1B9B6_d0e462308_href.png" placement="inline"/>

    32 </fig> </section>

    33 <section><title>Settings</title> <p>The email client MTM <xref href="GUID-A7EF08E6-82AF-3577-B942-ABD532EDB7FE.dita"><apiname>CEmailAccounts</apiname></xref> interfaces

    34 are enhanced to configure the email account settings. These settings modify

    35 the behaviour of the relevant server MTMs for the following functionality: </p> <p><b>Non-seamless

    36 bearer mobility</b> </p> <p>The IMAP4, POP3, and SMTP server MTMs are extended

    37 to allow messaging applications to use the non-seamless network bearer mobility

    38 when connecting to a destination network using the respective protocols. The

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

    40 <li id="GUID-2ED9D4E8-83F0-5264-88A0-3FC26A2DE9ED"><p> <xref href="GUID-7E4A95AA-1614-3058-B08C-B81878C37489.dita"><apiname>SetBearerMobility</apiname></xref>  </p> </li>

    41 <li id="GUID-5653C643-85E3-57BD-ABF8-259AC244E52A"><p> <xref href="GUID-D3E8B8A1-1E78-369E-B09A-E4C6CDACED8A.dita"><apiname>BearerMobility()</apiname></xref>  </p> </li>

    42 </ul> <p id="GUID-CC4028E7-ECD9-5045-9057-5BC687C3DF3A"><b>Per bearer-type

    43 configuration for IMAP email accounts</b> </p> <p>Specifically for IMAP email

    44 accounts, the <xref href="GUID-A7EF08E6-82AF-3577-B942-ABD532EDB7FE.dita"><apiname>CEmailAccounts</apiname></xref> class enables the following

    45 per bearer-type configuration that affect the behaviour of IMAP accounts: </p> <ul>

    46 <li id="GUID-EA24F6E4-D656-5053-996E-F75D645F318D"><p> <b>Download rules</b>  </p> <p>Download

    47 rules specify which parts of message to automatically download (according

    48 to bearer type) when synchronising the contents of an IMAP email account.

    49 You can configure an IMAP email account for IMAP download rules on each bearer

    50 type and for each account using the <xref href="GUID-1838902F-9077-36D8-AD22-5E36E0AFD51D.dita"><apiname>CImapSyncDownloadRules</apiname></xref> class. </p> <p>When

    51 synchronising an IMAP email account you can do the following: </p> <ul>

    52 <li id="GUID-B69ADD91-E4FC-57F1-8713-E1FD3539C16D"><p>Indicate that a list

    53 of email download rules for each type of bearer must be used during the email

    54 account synchronisations. </p> </li>

    55 <li id="GUID-D5518521-4D23-53A1-A3B0-2925CB6DEC7A"><p>Retrieve emails during

    56 the synchronisation using the mail options specified in the list for the bearer

    57 type that is currently in use by the connection to the server. </p> </li>

    58 </ul> <p>The <xref href="GUID-1838902F-9077-36D8-AD22-5E36E0AFD51D.dita"><apiname>CImapSyncDownloadRules</apiname></xref> class is used to store

    59 per IMAP account sync download rules. This class describes the download rules

    60 that provide the ability to automatically get the email content. This is configurable

    61 on a per account and per bearer-type basis. </p><ul>

    62 <li id="GUID-65E160D0-F45C-5B98-A11A-3EB1919EBF1B"><p>Different download rules

    63 can be specified for different bearers. For example, you can specify that

    64 all text and attachments should be retrieved when connecting through a WiFi

    65 connection; whereas, only text parts should be retrieved when connecting over

    66 GPRS connection. </p> </li>

    67 <li id="GUID-8A4F7179-3E5A-5833-A12D-5E95EE927CA0"><p>Synchronisation is performed

    68 in two stages: the email header synchronisation is performed first followed

    69 by the email content retrieval. If the email account settings indicate that

    70 the per-bearer-type list should not be used, or no per-bearer-type list is

    71 defined, or the current bearer type is not listed in the per-bearer-type list,

    72 then during the synchronisation the email headers for inbox and personal folders

    73 are downloaded. </p> <p> <b>Note:</b> The per-bearer-type list is a set of

    74 IMAP download and transport buffer size rules defined for each type of bearer. </p> </li>

    75 <li id="GUID-692023AF-B834-584F-BD2F-78CFEF6A1D98"><p>Messages that are not

    76 previously populated are retrieved using this method. So a message that has

    77 been populated according to GPRS settings will not be retrieved again according

    78 to WiFi settings, if a subsequent connection is made. </p> </li>

    79 <li id="GUID-DF7A0844-5A4E-5BB0-B5CF-329171E0E185"><p>Messages that arrive

    80 on the server while IMAP is in the <codeph>IDLE</codeph> state are also automatically

    81 downloaded according to the Inbox download rules for the connected bearer

    82 type. </p> </li>

    83 <li id="GUID-694C4DDD-1579-5142-909B-9AB76BD8BBA9"><p>A single instance of

    84 a set of download rules is applicable to multiple bearer types. </p> </li>

    85 </ul> </li>

    86 <li id="GUID-41D6D5F0-D9AF-5AAB-B45B-F69D62DA8DBA"><p> <b>Transport buffer

    87 size</b>  </p> <p>Transport buffer size specifies the size of the data transferred

    88 from server to client to get email body and attachments from an IMAP server

    89 using a per bearer-type list of transport buffer sizes. You can configure

    90 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

    91 per-bearer-type list is a set of IMAP download and transport buffer size rules

    92 defined for each type of bearer. </note> <p>This class allows a client to

    93 configure transport buffer sizes of IMAP accounts according to the bearer

    94 type for retrieving large message parts. It is possible to specify in the

    95 following: </p> <ul>

    96 <li id="GUID-9A27E24F-53E9-5962-A89E-4913B0BBF1CB"><p>Maximum retrieve size.

    97 Default is 20480 octets. </p> </li>

    98 <li id="GUID-751BA805-0E64-5B8A-AEA2-D814CE5355D1"><p>Maximum outstanding

    99 retrieve requests. Default is two outstanding requests. </p> </li>

   100 </ul> <p> <b>Important considerations</b>  </p> <ul>

   101 <li id="GUID-2EDE94E1-8AC0-5AAA-A46A-D0317FF8874F"><p>If there are is no bearer

   102 type specific list defined, or the current bearer type is not listed in the

   103 per-bearer-type list of transport buffer sizes, then the maximum retrieve

   104 request size specified in the email account settings is used. The maximum

   105 and default number of outstanding retrieve requests is two. </p> </li>

   106 <li id="GUID-4BBAAD4D-CA00-5E42-922C-D2456DD21212"><p>The transport buffer

   107 sizes that can be specified are the maximum retrieve request size sent in

   108 IMAP retrieve requests. </p> </li>

   109 <li id="GUID-574B5003-E293-5ED2-932E-0F78188F2348"><p>Download email body

   110 and attachments from an IMAP server using the retrieve request buffer size

   111 specific to the bearer type that the server connection is using. </p> </li>

   112 <li id="GUID-DCA1350E-9C6B-56F0-AF70-2A5C91C9149B"><p>Download email body

   113 and attachments from an IMAP server using the maximum number of outstanding

   114 retrieve requests specific to the bearer type that the server connection is

   115 using. </p> </li>

   116 <li id="GUID-DC672952-3FE1-5D72-8C6B-716FBF000222"><p>A single instance of

   117 a set of transport buffer sizes is applicable to multiple bearer types. </p> </li>

   118 </ul> </li>

   119 </ul> <p><b>Bearer mobility policy plug-in</b> </p> <p>The bearer mobility

   120 policy plug-in enables you to customise the migration behaviour of email accounts,

   121 the bearer mobility policy plug-in is provided. It consists of an ECOM interface

   122 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

   123 allows the plug-in to issue policy decisions on an individual mobility events. </p> </section>

   124 <section id="GUID-24BF7108-9229-5F0D-A3B0-27A8E419ABFF"><title>Important considerations</title> <ul>

   125 <li id="GUID-F200A31C-6293-586A-AA4B-A9E052520DEE"><p>To enable bearer mobility,

   126 you must first enable it at the Networking bearer mobility framework. </p> </li>

   127 <li id="GUID-AF2642E1-8B84-505B-BFCC-C093DDF17ACE"><p>Bearer mobility is possible

   128 only on the connections that are established using a SNAP preference list. </p> </li>

   129 <li id="GUID-B9D2EF4B-EA15-5574-8DC1-2892349636D4"><p>To use the bearer mobility,

   130 you must configure the email account settings to specify the SNAP preference

   131 when creating the <xref href="GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD.dita"><apiname>RConnection</apiname></xref> notification (events). </p> </li>

   132 <li id="GUID-84593BD5-376E-5302-8C9D-FBBBCB04BECD"><p>Multiple SNAP preferences

   133 for each service entry is not supported. </p> </li>

   134 <li id="GUID-BD5A6C40-B77A-5BBF-BB29-758391652A4B"><p>It is not possible to

   135 specify both IAPs and a SNAP for a single email account. The API for setting

   136 a SNAP preference clears any provisioned IAPs. Likewise, the API for setting

   137 IAPs are updated to clear any SNAP preference that is set. </p> </li>

   138 </ul> </section>

   139 </conbody><related-links>

   140 <link href="GUID-EBFE8B29-86AD-5785-8041-BCED2E90472E.dita"><linktext>SNAP Preferences</linktext>

   141 </link>

   142 <link href="GUID-786984BD-ADE8-5EF1-A819-F402F5703A80.dita"><linktext>Configuring

   143 Non-seamless Bearer Mobility</linktext></link>

   144 <link href="GUID-43CE4DCB-F498-5878-A2EE-7831BBB4D288.dita"><linktext>Configuring

   145 TLS or SSL Socket</linktext></link>

   146 <link href="GUID-A602A5BA-6C1F-5D8A-A6E7-50DECA1C64CC.dita"><linktext>SMTP Account

   147 Override Settings</linktext></link>

   148 <link href="GUID-75B1B1DF-4EC2-59BC-8BE0-A8AD681798C5.dita"><linktext>IMAP Account

   149 Settings</linktext></link>

   150 </related-links></concept>