|
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 task |
|
11 PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd"> |
|
12 <task id="GUID-49205F79-C17B-4126-BDB2-D759B91B5894" xml:lang="en"><title>Enabling |
|
13 Application Level Roaming</title><shortdesc>Application-level roaming (ALR) enables your application to roam |
|
14 to use the best available data connection while operational.</shortdesc><prolog><metadata><keywords/></metadata></prolog><taskbody> |
|
15 <context id="GUID-9B1466E3-661E-4BAB-A7F7-7F587FF8EBF1"> <p>To use application-level |
|
16 roaming: </p> </context> |
|
17 <steps id="GUID-4DD07DEC-6017-4237-BE46-1D69E5FBD744-GENID-1-10-1-14-1-1-6-1-3-2"> |
|
18 <step id="GUID-9A69E5AD-E938-4092-A8C2-CB65C37C8962-GENID-1-10-1-14-1-1-6-1-3-2-1"><cmd>Initiate an Internet |
|
19 connection using the Connection Manager API and the Internet destination network. |
|
20 In this example it is assumed that the best available access point for Internet |
|
21 is GPRS. </cmd> |
|
22 <stepresult> <p> RConnection handle is returned to the application. </p> |
|
23 </stepresult> |
|
24 </step> |
|
25 <step id="GUID-247DC723-B5D7-4E6B-B3E9-380DA63230B2"><cmd>Register for mobility |
|
26 API sending <xref href="GUID-54ACF1D8-F501-37EB-A558-CEF005D84F14.dita"><apiname>NewL(RConnection handle, MMobilityProtocolResp&)</apiname></xref> to |
|
27 the Connection Manager API.</cmd> |
|
28 </step> |
|
29 <step id="GUID-65B2CBFA-9631-4172-8B1A-665F09729871"><cmd>Use Sockets Client |
|
30 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> |
|
31 <stepresult><p> RSocket handle is returned to the application.</p></stepresult> |
|
32 </step> |
|
33 <step id="GUID-663CEB0D-A36D-46CB-8C2D-700D7DA76EF8"><cmd>Initiate normal |
|
34 socket communication to the Sockets Client API. This data transfer uses GPRS. |
|
35 A WLAN access point becomes available. The Connection Manager API sends <xref href="GUID-EA7C9217-8989-3486-B50F-9EA5844A6F2F.dita"><apiname>PreferredCarrierAvailable(old |
|
36 access point, new access point, is upgrade, not seamless</apiname></xref>) to the |
|
37 application. The application decides to switch to the better access point. |
|
38 It closes the old socket using the Sockets Client API. </cmd> |
|
39 </step> |
|
40 <step id="GUID-417D1229-320F-4B07-A429-9274163C7E01"><cmd>Send <xref href="GUID-99D7A3EF-ACF5-3E11-B356-E77497884F1F.dita"><apiname>MigrateToPreferredCarrier()</apiname></xref> to |
|
41 the Connection Manager API. Note: The application can also<xref href="GUID-7B5530C5-A13F-3BC6-BC69-9B05993AFCB1.dita"><apiname> IgnorePreferredCarrier()</apiname></xref>. |
|
42 In that case it would just keep using the existing socket. The connection |
|
43 is moved in the Connection Manager API. The WLAN access point is activated |
|
44 and RConnection handle is moved from the GPRS interface to WLAN. <xref href="GUID-EB635CFD-84A5-334B-8F48-85265E40A5A2.dita"><apiname> NewCarrierActive(new |
|
45 IAP)</apiname></xref> is returned to the application. The WLAN access point is now |
|
46 ready to be used. </cmd> |
|
47 </step> |
|
48 <step id="GUID-284D53C0-516A-4F05-8422-918A6FCA036C"><cmd>Use Sockets Client |
|
49 API to open RSockets with RConnection handle. This data transfer uses WLAN.</cmd> |
|
50 </step> |
|
51 <step id="GUID-27CF0583-4A43-4386-AFF6-E37E6DA15A64"><cmd>Transfer data using |
|
52 the Sockets Client API to confirm that the connection works.</cmd> |
|
53 </step> |
|
54 <step id="GUID-B7B7D14A-D241-49C2-84D0-147B780A70FF"><cmd>Send <xref href="GUID-91FB265C-9924-3F59-8C7B-C68D65D72ABC.dita"><apiname>NewCarrierAccepted()</apiname></xref> to |
|
55 the Connection Manager API. This is the point of no return.</cmd> |
|
56 </step> |
|
57 <step id="GUID-239B2867-A34A-45EE-A843-8C913709CD47"><cmd>Continue transferring |
|
58 data using the Sockets Client API. This data transfer uses WLAN.</cmd> |
|
59 </step> |
|
60 </steps> |
|
61 <result id="GUID-B55F3ECE-2C77-446C-8313-ED3B72BBF4DF"> <p>ALR is enabled.</p> |
|
62 </result> |
|
63 <example><codeblock xml:space="preserve">class CALRApplication : public CActive, public MMobilityProtocolResp |
|
64 { |
|
65 ... |
|
66 public: // From MMobilityProtocolResp |
|
67 void PreferredCarrierAvailable( TAccessPointInfo aOldAPInfo, |
|
68 TAccessPointInfo aNewAPInfo, |
|
69 TBool aIsUpgrade, |
|
70 TBool aIsSeamless ); |
|
71 void NewCarrierActive( TAccessPointInfo aNewAPInfo, TBool aIsSeamless ); |
|
72 void Error( TInt aError ); |
|
73 private: // Data |
|
74 RConnection iConnection; |
|
75 CActiveCommsMobilityApiExt* iMobility; |
|
76 }; |
|
77 // When the connection starts, iMobility is created and it registers the connection to receive mobility messages. |
|
78 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. |
|
79 void CALRApplication::PreferredCarrierAvailable( TAccessPointInfo aOldAPInfo,TAccessPointInfo aNewAPInfo,TBool aIsUpgrade,TBool aIsSeamless ){ |
|
80 // aOldAPInfo contains the current IAP used by the connection. |
|
81 // aNewAPInfo contains the newly available IAP that can be used by the connection. |
|
82 if ( aIsSeamless ) |
|
83 { |
|
84 // It is Seamless. E.g. Mobile IP enabled. |
|
85 } |
|
86 else |
|
87 { |
|
88 // sockets used by the connection should be closed here. |
|
89 // We ask to migrate to the Preferred Carrier. |
|
90 iMobility->MigrateToPreferredCarrier(); |
|
91 } |
|
92 } |
|
93 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. |
|
94 |
|
95 void CALRApplication::NewCarrierActive( TAccessPointInfo aNewAPInfo, TBool aIsSeamless ) |
|
96 { |
|
97 // aNewAPInfo contains the newly started IAP used now by the connection. |
|
98 if ( aIsSeamless ) |
|
99 { |
|
100 // It is Seamless. E.g. Mobile IP enabled. |
|
101 } |
|
102 else |
|
103 { |
|
104 // sockets used by the connection should be reopened here. |
|
105 // We accept the new IAP. |
|
106 iMobility->NewCarrierAccepted(); |
|
107 } |
|
108 }</codeblock></example> |
|
109 </taskbody></task> |