Symbian3/SDK/Source/GUID-24860917-0FE2-5C8F-B436-96928350996E.dita
changeset 0 89d6a7a84779
equal deleted inserted replaced
-1:000000000000 0:89d6a7a84779
       
     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_d0e248943_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>