<?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-93221B70-EB36-5E8E-AE23-700988D5DACB" xml:lang="en"><title>Bearer

Mobility Policy Plug-in</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>The bearer mobility policy plug-in enables email server MTMs (POP3, IMAP4,

or SMTP) to do the following tasks, provided bearer mobility is set at the

client-side: </p>

<ul>

<li id="GUID-CE94C956-4CDD-5EA3-8F67-398554D88E85"><p>Check for the bearer

that is currently available. </p> </li>

<li id="GUID-FB732A0E-2188-5AAB-B1BA-A589C3F572D6"><p>Register for notifications

when a new bearer becomes available. </p> </li>

<li id="GUID-8A61EBCF-0F30-5C63-B254-4FBC5A50FBE8"><p>Handle notifications

of availability of new bearers, and respond with acceptance or rejection of

the new bearer. </p> </li>

<li id="GUID-6E7D8255-FA0B-509A-A3F8-8FE1E660ABAC"><p>Handle notifications

that a bearer change has occurred, and initiate socket re-establishment. </p> </li>

</ul>

<p>The bearer mobility policy plug-in interface allows customisation of the

migration behaviour of email accounts. 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 individual mobility events. </p>

<section><title>Description</title> <p>There are two components (APIs) in

the bearer mobility policy plug-in: <b>policy plug-in</b> and <b>policy handler</b>.

A default policy plug-in implementation is provided, which can be overridden. </p> <p>The

policy handler can set policies on for the preferred bearer to accept or reject,

when the bearer is available. Based on the policy that you set, the migration

to the preferred bearer is decided. If you have set the policy to accept the

preferred bearer, then the policy plug-in receives notification when a switch

to a new bearer occurs, or when the current connection is lost. For graphical

illustration of the architecture, see <xref href="GUID-24860917-0FE2-5C8F-B436-96928350996E.dita#GUID-24860917-0FE2-5C8F-B436-96928350996E/GUID-973000BE-9CE1-526D-ACC4-EA0ECFF3D93E">Architecture</xref>. </p> </section>

<section><title>API overview</title><p>The <xref href="GUID-D3ED20A6-A16E-368E-98AD-820A469613EE.dita"><apiname>CImMobilityPolicyPlugin</apiname></xref> class

allows the plug-in to be notified about mobility events. The mobility manager

and server MTMs do not attempt to perform a migration until the policy plug-in

has issued a response to a notification. </p> <p>The <xref href="GUID-73ABAC20-D43E-31B3-A6CB-95572D3140D2.dita"><apiname>MImMobilityPolicyHandler</apiname></xref> class

allows the bearer mobility policy plug-in to provide the decision on whether

to accept or reject a migration. </p> <p>The bearer mobility policy

plug-in (<xref href="GUID-D3ED20A6-A16E-368E-98AD-820A469613EE.dita"><apiname>CImMobilityPolicyPlugin</apiname></xref>) implements the following

functions: </p> <ul>

<li id="GUID-B58F81EA-9705-5162-8DFA-61A38D8E4DA6"><p> <xref href="GUID-4D26288F-A8F8-355E-B49C-B313EEC04584.dita"><apiname>PreferredCarrierAvailable()</apiname></xref>  </p> </li>

<li id="GUID-9C99FE75-61D2-5717-BE09-876CD42B3CFB"><p> <xref href="GUID-B61994E7-B88B-38FE-86AE-1B9834F1816D.dita"><apiname>Cancel()</apiname></xref>  </p> </li>

<li id="GUID-F5B3FA11-00CD-5B88-84D4-1CC5AB002E86"><p> <xref href="GUID-D83D8E23-824B-3211-8B97-7BBBF1253264.dita"><apiname>MigrationComplete()</apiname></xref>  </p> </li>

</ul> <p>Responses to the preferred carrier interface are made

through the <xref href="GUID-73ABAC20-D43E-31B3-A6CB-95572D3140D2.dita"><apiname>MImMobilityPolicyHandler</apiname></xref> class, which has the

following functions: </p> <ul>

<li id="GUID-2174067A-AED8-5C05-BDAB-DD19B19E2D37"><p> <xref href="GUID-6D6F91B5-2C0D-387D-870C-84E2681F5C5E.dita"><apiname>AcceptNewCarrier()</apiname></xref>  </p> <p>If

a migration is accepted, this function provides the following options for

managing client-requested operations that may be in progress. </p> <ul>

<li id="GUID-E5DB1009-1516-5661-A04D-622AFD1926C2"><p>The client-requested

operation is immediately stopped the current outstanding server command is

cancelled. The open sockets are closed, and migration is initiated. </p> </li>

<li id="GUID-8ADF1BEF-F340-58DD-9175-2BB9F82C8AD7"><p>The client-requested

operation continues until the data does not need to be re-sent or re-received

after migration. For example, if fetching several messages, the current message

will be allowed to complete. </p> </li>

<li id="GUID-43377D38-87E7-5CA3-A2BC-8129C49078D6"><p>The client-requested

operation is allowed complete before migration is accepted. </p> </li>

</ul> </li>

<li id="GUID-3E49A078-6147-5BFB-80DF-AF54719FA114"><p> <xref href="GUID-5140B381-D44F-365F-9ABF-80E7FCC89F70.dita"><apiname>IgnoreNewCarrier()</apiname></xref>  </p> </li>

</ul> <fig id="GUID-799574C2-A9EC-5CDB-8F8A-E972D8FD0F17">

<title>                 Bearer plug-in class diagram              </title>

<image href="GUID-66772A42-2326-5250-9411-4C65534FB5D2_d0e473678_href.png" placement="inline"/>

</fig> </section>

<section><title>See also</title> <ul>

<li id="GUID-C7A0B45B-FD6B-587D-AEF9-8286808611CE"><p>For tasks on notifications

using the <xref href="GUID-D3ED20A6-A16E-368E-98AD-820A469613EE.dita"><apiname>CImMobilityPolicyPlugin</apiname></xref> class, see the following: </p> <ul>

<li id="GUID-905985D1-095B-573F-83EF-BF226F152E61"><p><xref href="GUID-DD276E82-B190-56CD-9A4A-ADE586E5EE92.dita">Notifying

the Availability of a Preferred Bearer</xref>  </p> </li>

<li id="GUID-DF504B44-3132-50F3-8D65-A7D34E0B9F9A"><p><xref href="GUID-E76A69FF-0FF2-52DC-A5B4-FBB772677CB3.dita">Notifying

on Completion of a Bearer Migration</xref>  </p> </li>

</ul> </li>

<li id="GUID-0AE4A434-379B-5B62-93B9-BBC44F68E9C1"><p>For tasks on handling

bearer mobility using the <xref href="GUID-73ABAC20-D43E-31B3-A6CB-95572D3140D2.dita"><apiname>MImMobilityPolicyHandler</apiname></xref> class,

see the following: </p> <ul>

<li id="GUID-07071515-6C1B-5161-A433-C2865F771B2B"><p><xref href="GUID-CF6ED944-6BC6-51FA-9B05-6F799F06B44B.dita">Accepting

a Newly-Available Bearer</xref>  </p> </li>

<li id="GUID-68134333-38CB-5F93-A2B2-149701A124C8"><p><xref href="GUID-4F02CF5E-7AA6-55AD-B3C5-42892547C188.dita">Rejecting

the Newly-Available Bearer</xref>  </p> </li>

</ul> </li>

</ul> </section>

</conbody></concept>