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