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