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

  PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">

<task id="GUID-49205F79-C17B-4126-BDB2-D759B91B5894" xml:lang="en"><title>Enabling

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

<context id="GUID-9B1466E3-661E-4BAB-A7F7-7F587FF8EBF1">       <p>To use application-level

roaming: </p>     </context>

<steps id="GUID-4DD07DEC-6017-4237-BE46-1D69E5FBD744-GENID-1-12-1-16-1-1-6-1-3-2">

<step id="GUID-9A69E5AD-E938-4092-A8C2-CB65C37C8962-GENID-1-12-1-16-1-1-6-1-3-2-1"><cmd>Initiate an Internet

connection using the Connection Manager API and the Internet destination network.

In this example it is assumed that the best available access point for Internet

is GPRS. </cmd>

<stepresult>           <p> RConnection handle is returned to the application. </p> 

       </stepresult>

</step>

<step id="GUID-247DC723-B5D7-4E6B-B3E9-380DA63230B2"><cmd>Register for mobility

API sending <xref href="GUID-54ACF1D8-F501-37EB-A558-CEF005D84F14.dita"><apiname>NewL(RConnection handle, MMobilityProtocolResp&amp;)</apiname></xref> to

the Connection Manager API.</cmd>

</step>

<step id="GUID-65B2CBFA-9631-4172-8B1A-665F09729871"><cmd>Use Sockets Client

API to open <xref href="GUID-30FCE6D7-B7E2-317F-A72A-4AB908E92B34.dita"><apiname>RSockets</apiname></xref> with <xref href="GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD.dita"><apiname>RConnection</apiname></xref> handle. </cmd>

<stepresult><p> RSocket handle is returned to the application.</p></stepresult>

</step>

<step id="GUID-663CEB0D-A36D-46CB-8C2D-700D7DA76EF8"><cmd>Initiate normal

socket communication to the Sockets Client API. This data transfer uses GPRS.

  A WLAN access point becomes available. The Connection Manager API sends <xref href="GUID-EA7C9217-8989-3486-B50F-9EA5844A6F2F.dita"><apiname>PreferredCarrierAvailable(old

access point, new access point, is upgrade, not seamless</apiname></xref>) to the

application.  The application decides to switch to the better access point.

It closes the old socket using the Sockets Client API. </cmd>

</step>

<step id="GUID-417D1229-320F-4B07-A429-9274163C7E01"><cmd>Send <xref href="GUID-99D7A3EF-ACF5-3E11-B356-E77497884F1F.dita"><apiname>MigrateToPreferredCarrier()</apiname></xref> to

the Connection Manager API.  Note: The application can also<xref href="GUID-7B5530C5-A13F-3BC6-BC69-9B05993AFCB1.dita"><apiname> IgnorePreferredCarrier()</apiname></xref>.

In that case it would just keep using the existing socket.  The connection

is moved in the Connection Manager API. The WLAN access point is activated

and RConnection handle is moved from the GPRS interface to WLAN. <xref href="GUID-EB635CFD-84A5-334B-8F48-85265E40A5A2.dita"><apiname> NewCarrierActive(new

IAP)</apiname></xref> is returned to the application.  The WLAN access point is now

ready to be used. </cmd>

</step>

<step id="GUID-284D53C0-516A-4F05-8422-918A6FCA036C"><cmd>Use Sockets Client

API to open RSockets with RConnection handle. This data transfer uses WLAN.</cmd>

</step>

<step id="GUID-27CF0583-4A43-4386-AFF6-E37E6DA15A64"><cmd>Transfer data using

the Sockets Client API to confirm that the connection works.</cmd>

</step>

<step id="GUID-B7B7D14A-D241-49C2-84D0-147B780A70FF"><cmd>Send <xref href="GUID-91FB265C-9924-3F59-8C7B-C68D65D72ABC.dita"><apiname>NewCarrierAccepted()</apiname></xref> to

the Connection Manager API. This is the point of no return.</cmd>

</step>

<step id="GUID-239B2867-A34A-45EE-A843-8C913709CD47"><cmd>Continue transferring

data using the Sockets Client API. This data transfer uses WLAN.</cmd>

</step>

</steps>

<result id="GUID-B55F3ECE-2C77-446C-8313-ED3B72BBF4DF">       <p>ALR is enabled.</p> 

   </result>

<example><codeblock xml:space="preserve">class CALRApplication : public CActive, public MMobilityProtocolResp

    {

...

    public: // From MMobilityProtocolResp

    void PreferredCarrierAvailable( TAccessPointInfo aOldAPInfo,

                                        TAccessPointInfo aNewAPInfo,

                                        TBool aIsUpgrade,

                                        TBool aIsSeamless );

  void NewCarrierActive( TAccessPointInfo aNewAPInfo, TBool aIsSeamless );

  void Error( TInt aError );

  private:    // Data

  RConnection  iConnection;

  CActiveCommsMobilityApiExt*   iMobility;

    };

// When the connection starts, iMobility is created and it registers the connection to receive mobility messages.

iMobility = CActiveCommsMobilityApiExt::NewL( iConnection, *this );When apreferred access point becomes available, the implementation of CALRApplication::PreferredCarrierAvailable is called. MigrateToPreferredCarrier Mobility message is sent to the middleware in order to roam to this preferred access point.

void CALRApplication::PreferredCarrierAvailable( TAccessPointInfo aOldAPInfo,TAccessPointInfo aNewAPInfo,TBool aIsUpgrade,TBool aIsSeamless ){

    // aOldAPInfo contains the current IAP used by the connection.

    // aNewAPInfo contains the newly available IAP that can be used by the connection.

 if ( aIsSeamless )

        {

        // It is Seamless. E.g. Mobile IP enabled.

        }

    else

        {

        // sockets used by the connection should be closed here.

        // We ask to migrate to the Preferred Carrier.

        iMobility->MigrateToPreferredCarrier();

        }

    }

Once the connection roamed to the new access point, the implementation ofCALRApplication::NewCarrierActive is called. The application reopens its sockets on the connection. If the socket connection is fine, the application sends the NewCarrierAccepted Mobility message to the middleware.

void CALRApplication::NewCarrierActive( TAccessPointInfo aNewAPInfo, TBool aIsSeamless )

    {

    // aNewAPInfo contains the newly started IAP used now by the connection.

    if ( aIsSeamless )

        {

        // It is Seamless. E.g. Mobile IP enabled.

        }

    else

        {

        // sockets used by the connection should be reopened here.

        // We accept the new IAP.

        iMobility->NewCarrierAccepted();

        }

    }</codeblock></example>

</taskbody></task>