<?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-BE2D9AAB-203B-471A-984D-91E917611641" xml:lang="en"><title>Application

Level Roaming</title><shortdesc>Application-level roaming (ALR) enables your application to roam

to use the best available data connection while operational.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<section id="GUID-F6E3E184-0235-47B1-950F-AECA2F64D985"><title>Implementation

Considerations</title>      <p>There is no SDK method for WLAN scanning. Your

application should use Connection Monitor Server API to request the list of

available access points or network names (in the case of a WLAN these are

SSIDs). Connection Monitor Server API also provides notifications about changes

in the access point availability list. </p><p>Handovers between GPRS and WCDMA

radio networks take a long time (from 15 seconds to 2 minutes) and sometimes

fail completely. You should use long application level timers (if any) and

maintain a responsive UI. Note that handovers between GPRS and WCDMA cannot

be controlled by the symbian platform (except with fixed settings). The control

logic is in the cellular modem. </p><p> In ALR, the transfer from one connection

to another always introduces an IP address change and a break in data connection

(even with make-before-break when the break is really short). This is because

the sockets need to be closed and re-opened. This may be problematic for the

applications that maintain a stateful connection with a server in the network.

The workaround for a break is to open a new RConnection handle when receiving <xref href="GUID-4D26288F-A8F8-355E-B49C-B313EEC04584.dita"><apiname>PreferredCarrierAvailable()</apiname></xref> and

establishing the server connection using that (if the application protocol

allows such operation). When that is done and new sockets are created for

the new RConnection, the original RConnection can be closed. There is no workaround

for the IP address change.</p>     </section>

<section id="GUID-011DBF55-366F-4AC7-824A-2B485658E1C8"><title>Process Flow</title><fig id="GUID-79B01634-BBA5-40DD-BBB5-DE4D53139BC6">

<title>Application-level roaming</title>

<image href="GUID-8305F179-8F26-4B38-8523-066D1B0B7A62_d0e217254_href.png" placement="inline"/>

</fig></section>

<section id="GUID-A2C485F5-0BD5-4D0E-8F95-D9963C4C819F"><title>Additional

information</title><p>The following APIs are used to implement application-level

roaming: </p><ol>

<li id="GUID-B1B6B16A-A790-4B04-BC6E-91D64E5C4E06"><p> Sockets Server Client

API (ESOCK) is the API for all IP-based socket communication. It remains unchanged,

but applications need to be ready to close and open sockets at certain times

to roam for a better connection.</p></li>

<li id="GUID-F4D709CC-9F14-42B4-BF32-8EB0C787EBF3"><p>Connection Management

API (RConnection) is a collection of Symbian's connection management-related

functionalities provided by ESOCK. It contains several extensions and one

of them is the mobility extension. The term "mobility API" actually refers

to the mobility extensions that are part of Connection Manager API and defined

in header <filepath>cs_mobility_apiext.h</filepath>. With the so-called mobility

API the client application can register for mobility events, receive information

about preferred connections, indicate whether to switch to a new connection

or ignore it. In short, it enables ALR for the applications.</p></li>

</ol><p> The mobility extension functionality of the Connection

Manager API is provided by classes<xref href="GUID-9A3979A9-F882-3053-B5B1-E0E125774271.dita"><apiname> MMobilityProtocolResp </apiname></xref>and <xref href="GUID-6CA83252-4D0C-3B72-83ED-B5152B666C83.dita"><apiname>CActiveCommsMobilityApiExt</apiname></xref>. </p><p>Methods

that must be implemented by client (class MMobilityProtocolResp): <ol>

<li id="GUID-F6747252-65DF-4424-BA7E-DA5D11D2E9BE"><p><b>virtual void PreferredCarrierAvailable(TAccessPointInfo

aOldAP, TAccessPointInfo aNewAP, TBool aIsUpgrade, TBool aIsSeamless )</b>;

This method is called by the middleware to notify a client about a new preferred

connection.</p></li>

<li id="GUID-9C0DD06E-9949-4A7B-ABF9-CEF10F541274"><p><b>virtual void NewCarrierActive(TAccessPointInfo

aNewAP, TBool aIsSeamless );</b> This method is called by the middleware to

notify a client that a preferred connection has been activated.</p></li>

<li id="GUID-54247E78-0A68-4A2A-B94A-064BE9D61270"><p><b>virtual void Error(TInt

aError);</b> This method is called by middleware to notify that there are

no suitable connections available.</p></li>

</ol></p><p>Methods provided by ESock (class CActiveCommsMobilityApiExt): <ol>

<li id="GUID-CFEC6776-0206-4205-9269-7AD2A47CDF23"><p><b>void MigrateToPreferredCarrier();</b> Client

can indicate that it wants to start using a new preferred connection as a

response to PreferredCarrierAvailable().</p></li>

<li id="GUID-D5181565-96D3-4025-8A7E-B92EE4C699ED"><p><b>void IgnorePreferredCarrier();</b> Client

can indicate that it doesn’t want to use a new preferred connection as a response

to PreferredCarrierAvailable().</p></li>

<li id="GUID-4C9658D0-D0F3-40A6-9466-D2CBB15D2663"><p><b>void NewCarrierAccepted();</b> Client

indicates that a new connection is working for it.</p></li>

<li id="GUID-33856021-74DA-4501-9DCB-8B28BD281282"><p><b>void NewCarrierRejected();</b> Client

indicates that a new connection is not working and it wants to use another

connection. In this case it receives <xref href="GUID-4D26288F-A8F8-355E-B49C-B313EEC04584.dita"><apiname>PreferredCarrierAvailable()</apiname></xref> again

with probably the original connection as a preferred one. The non-working

access point is blacklisted for that client and not suggested again.</p></li>

</ol></p></section>

</conbody></concept>