|
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 reference |
|
11 PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd"> |
|
12 <reference id="GUID-D24D5F17-462E-5424-99A7-9B16E9FEDC93" xml:lang="en"><title>Rconnection: |
|
13 connection monitoring and management example</title><shortdesc>This example demonstrates the use of the <codeph>RConnection</codeph> API |
|
14 to do connection monitoring and management. </shortdesc><prolog><metadata><keywords/></metadata></prolog><refbody> |
|
15 <section><title>Purpose</title> <p>The example demonstrates the following |
|
16 features of the <xref href="GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD.dita"><apiname>RConnection</apiname></xref> API: </p> <ul> |
|
17 <li id="GUID-01B8C3CB-4C74-51B5-A9B1-6CE1D5DD0360"><p>Opening and closing |
|
18 a connection using <xref href="GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD.dita#GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD/GUID-CE8F3FE7-14F2-3FB6-B04C-8596B5F80DFC"><apiname>RConnection::Open(RSocketServ& aSocketServer, |
|
19 TUint aConnectionType = KConnectionTypeDefault)</apiname></xref> and <xref href="GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD.dita#GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD/GUID-20D71C1C-27EE-3305-8326-4CC1DFFB0E2F"><apiname>RConnection::Close()</apiname></xref>. </p> </li> |
|
20 <li id="GUID-A5CDAFC8-771C-56A1-86BF-E4731EB7D325"><p>Starting a connection |
|
21 that uses the default CommDb connection preferences, and another connection |
|
22 that overrides them, using (respectively) <xref href="GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD.dita#GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD/GUID-CB62E838-A380-309C-8B08-1F804EDB4387"><apiname>RConnection::Start()</apiname></xref> and <xref href="GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD.dita#GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD/GUID-16E04EA9-E7AD-31EE-A1CB-F40F726ED489"><apiname>RConnection::Start(TConnPref& |
|
23 aPref)</apiname></xref>. </p> </li> |
|
24 <li id="GUID-DF26CF2F-E012-5752-88B8-2E2FBE4DC0BC"><p>Getting the number of |
|
25 connections, and retrieving information about one of them, using <xref href="GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD.dita#GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD/GUID-45801E1B-A7F0-3E3D-BAC2-98FA542BD082"><apiname>RConnection::EnumerateConnections(TUint& |
|
26 aCount)</apiname></xref> and <xref href="GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD.dita#GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD/GUID-DEAFE4AC-B1B7-38DF-A0C2-9BA0201F11FD"><apiname>RConnection::GetConnectionInfo(TUint |
|
27 aIndex, TDes8& aConnectionInfo)</apiname></xref>. </p> </li> |
|
28 <li id="GUID-43861187-FF27-56BD-8B09-F5FC3456FB0D"><p>Attaching a connection |
|
29 to an existing interface, using <xref href="GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD.dita#GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD/GUID-1C5036E6-62E8-308F-AE72-CB886B2C9C0A"><apiname>RConnection::Attach(const TDesC8& |
|
30 aConnectionInfo, TConnAttachType aAttachType)</apiname></xref>. </p> </li> |
|
31 <li id="GUID-3C89B0C2-3378-5D8B-A519-F5689ACA65EC"><p>Registering for notifications |
|
32 when: </p> <ul> |
|
33 <li id="GUID-61A4C660-FA35-51DC-A4F1-715CC630052D"><p>a certain amount of |
|
34 data has been sent, using <xref href="GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD.dita#GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD/GUID-800269E0-8B6D-3C47-86BF-76862AA8CDC3"><apiname>RConnection::DataSentNotificationRequest(TUint |
|
35 aThreshold, TPckg<TUint>& aUplinkVolume, TRequestStatus& |
|
36 aStatus)</apiname></xref>. </p> </li> |
|
37 <li id="GUID-40B69177-D7DB-5920-98DF-A681E5EB21E8"><p>a certain amout of data |
|
38 has been received, using <xref href="GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD.dita#GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD/GUID-4DDC3337-FFE9-32E0-A98E-3823F8E833BF"><apiname>RConnection::DataReceivedNotificationRequest(TUint |
|
39 aThreshold, TPckg<TUint>& aDownlinkVolume, TRequestStatus& |
|
40 aStatus)</apiname></xref>. </p> </li> |
|
41 <li id="GUID-48F1D550-A56C-5F52-A870-C74C63BB8FFE"><p>interfaces go up and |
|
42 down, using <xref href="GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD.dita#GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD/GUID-22059E3E-37D7-3C48-940B-A93698E27E5D"><apiname>RConnection::AllInterfaceNotification(TDes8& aNotification, |
|
43 TRequestStatus& aStatus)</apiname></xref>. </p> </li> |
|
44 <li id="GUID-15E99A35-D6C3-5F28-98C5-72B80B594EBB"><p>the connection changes |
|
45 state, using <xref href="GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD.dita#GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD/GUID-84FF9C60-60B9-3D9D-9D82-3CE063FC9D72"><apiname>RConnection::ProgressNotification(TNifProgressBuf& |
|
46 aProgress, TRequestStatus& aStatus, TUint aSelectedProgress |
|
47 = KConnProgressDefault)</apiname></xref>. </p> </li> |
|
48 </ul> </li> |
|
49 <li id="GUID-57C9068C-1380-5397-A090-1D9FC1587FED"><p>Obtaining the amount |
|
50 of data transferred, using <xref href="GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD.dita#GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD/GUID-6C695DC3-978A-3F48-87AE-08E64F45831D"><apiname>RConnection::DataTransferredRequest()</apiname></xref>. </p> </li> |
|
51 <li id="GUID-FAA3F969-67AF-5716-92F9-B5BDBC038906"><p>Obtaining the connection's |
|
52 current state, using <xref href="GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD.dita#GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD/GUID-2A798FA2-371F-3BB8-8531-374D9C72AA90"><apiname>RConnection::Progress(TNifProgress& aProgress)</apiname></xref>. </p> </li> |
|
53 <li id="GUID-14CBAB9C-F93D-5A0D-A63E-B18D2209D38A"><p>Stopping the connection, |
|
54 using <xref href="GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD.dita#GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD/GUID-52878713-A4E8-327E-901B-449EF3D39E0A"><apiname>RConnection::Stop()</apiname></xref>. </p> </li> |
|
55 <li id="GUID-0525FECB-37A0-5373-93DD-92BCB1317078"><p>Closing the session |
|
56 with the socket server using <xref href="GUID-EF29C1D7-B1E5-370F-AE37-66231A6BE449.dita#GUID-EF29C1D7-B1E5-370F-AE37-66231A6BE449/GUID-B6D74895-B413-3759-966A-4A1D855267E1"><apiname>RSocketServ::Close()</apiname></xref>. </p> </li> |
|
57 </ul> </section> |
|
58 <section><title>Download</title><p>Click on the following link to download |
|
59 the example: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-3d0ac087-79ee-467f-b6ed-d71eafa40d9c.zip" scope="external">Rconnection.zip</xref></p><p>Click: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-3d0ac087-79ee-467f-b6ed-d71eafa40d9c.html" scope="peer">browse</xref> to view the example code. </p> </section> |
|
60 <section><title>Class Summary</title><p>The example demonstrates the following |
|
61 classes: </p><p><xref href="GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD.dita"><apiname>RConnection</apiname></xref></p><p><xref href="GUID-D4F08503-F1EF-3531-9C3C-4AF24A6255F0.dita"><apiname>RSocket</apiname></xref></p><p><xref href="GUID-EF29C1D7-B1E5-370F-AE37-66231A6BE449.dita"><apiname>RSocketServ</apiname></xref></p><p><xref href="GUID-739117F6-9559-3274-8E00-B2B653C0A8B6.dita"><apiname>TCommDbConnPref</apiname></xref></p><p><xref href="GUID-E104DE5D-FF3F-3E07-ACC3-E24A96DF3629.dita"><apiname>TConnectionInfoBuf</apiname></xref></p></section> |
|
62 <section><title>Design and implementation</title> <p>The project implements |
|
63 a single class called <codeph>CRConnection</codeph>, that has three principal |
|
64 functions: </p> <p><b>CRConnection::DemoApiWithoutDbOverrideL() </b> </p> <p>This |
|
65 shows how to use <xref href="GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD.dita"><apiname>RConnection</apiname></xref> to: </p> <ul> |
|
66 <li id="GUID-01D4595A-2723-53C8-9499-7215FFA219C3"><p>start a connection and |
|
67 associate it with an underlying interface, using default CommDb connection |
|
68 preferences, </p> </li> |
|
69 <li id="GUID-6377E5AB-71D3-50F1-B084-E8891BB73BB9"><p>get notification when |
|
70 the underlying interface goes up or down, </p> </li> |
|
71 <li id="GUID-37FF8270-7FD1-5B27-9E9A-BC6D49E02B4D"><p>get notification about |
|
72 the state of a connection as it becomes fully established, </p> </li> |
|
73 <li id="GUID-E396A06F-5156-5924-9B68-649575A1CA62"><p>transfer data over a |
|
74 socket, </p> </li> |
|
75 <li id="GUID-584D9C8C-A317-51D0-8AD2-397337F1A332"><p>get the amount of data |
|
76 transferred, </p> </li> |
|
77 <li id="GUID-23588938-CEE7-5AD9-8C9D-9FA253AE11D2"><p>close the connection. </p> </li> |
|
78 </ul> <p>It also shows how to set up a socket to carry out data transfer. </p> <p><b>CRConnection::DemoApiWithDbOverrideL() </b> </p> <p>This |
|
79 is the same as <codeph>DemoApiWithoutDbOverrideL()</codeph> except that it: </p> <ul> |
|
80 <li id="GUID-C61443A2-8576-59F3-A586-30DDF1D2AD56"><p>starts a connection |
|
81 using non-default CommDb connection preferences, </p> </li> |
|
82 <li id="GUID-9777305D-11BC-5BD4-AFE0-2ED3D010BE93"><p>requests notification |
|
83 when a threshold amount of data has been transferred (instead of getting the |
|
84 amount of data transferred). </p> </li> |
|
85 </ul> <p><b>CRConnection::AttachToExistingInterfaceL() </b> </p> <p>This shows |
|
86 how to use <xref href="GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD.dita"><apiname>RConnection</apiname></xref> to: </p> <ul> |
|
87 <li id="GUID-CB835CF4-BD2A-55E5-BEF7-248A0750B466"><p>open 2 connections and |
|
88 start one of them (the other is not yet associated with an underlying interface), </p> </li> |
|
89 <li id="GUID-DE013E1E-E3C3-513C-B0B6-5B16E6000C5C"><p>get connection information |
|
90 for the 1st connection and use this to attach the 2nd connection to the existing |
|
91 interface, </p> </li> |
|
92 <li id="GUID-BCA6E282-7C55-5416-884F-F88172672D8B"><p>get the state of the |
|
93 attached connection, </p> </li> |
|
94 <li id="GUID-8A107877-F6BD-5580-ADB5-230F86B36CD4"><p>close the connections. </p> </li> |
|
95 </ul> </section> |
|
96 <section><title>Building and configuring</title> <p>You can build the example |
|
97 from the IDE or the command line. </p> <p>If you use an IDE, import the <filepath>bld.inf</filepath> file |
|
98 into your IDE, and use the build command of the IDE. </p> <p>If you use the |
|
99 command line, open a command prompt, and set the current directory to the |
|
100 source code directory of the example. You can then build the example using |
|
101 the SBSv1 build tools with the following commands: </p> <p><userinput>bldmake |
|
102 bldfiles</userinput> </p> <p><userinput>abld build</userinput> </p> <p><xref href="GUID-793A5EF9-CC16-5EEB-9011-6431EA76EB15.dita">How to use bldmake</xref> and <xref href="GUID-B6B54E07-3B34-5D5C-8815-93383FA8FB4B.dita">How to use abld</xref> describe |
|
103 how to use the SBSv1 build tools. </p> <p><b>Emulator: </b> </p> <p>Before |
|
104 running the example, the emulator must be set up to use ethernet, as follows: </p> <ul> |
|
105 <li id="GUID-1C477C42-8F6B-57F1-A8CE-F1CBAA22F265"><p>Install <xref href="GUID-CDD1E761-6B28-5F69-BBEF-756DF45E59A2.dita">WinPCap |
|
106 4.0.2</xref> </p> </li> |
|
107 <li id="GUID-C79C333A-AF6E-5587-8BA0-B19C470C2D09"><p>Configure the emulator |
|
108 using <xref href="GUID-7B114A67-356A-5FCE-B57B-761F5477A2B2.dita">configchange.pl</xref> for |
|
109 instance: </p> <p><userinput>configchange.pl --config ethernetWithCommDB --kernel |
|
110 EKA2 --target winscw --variant udeb</userinput> </p> </li> |
|
111 <li id="GUID-FBAD862F-DFA3-5E7E-8F69-3C4B3CF9E56B"><p>Open <filepath>ethernetced.xml</filepath> in <filepath>epoc32\winscw\c\</filepath> and |
|
112 change the last 3 values in the <codeph>LANBearer operation</codeph> section |
|
113 for "EKA2 Emulator Ethernet" in the <codeph>LANBearerTable</codeph> to: </p> <codeblock id="GUID-1C6B07F1-521D-5E3A-A4EE-A96FA369D5CA" xml:space="preserve">LastSocketActivityTimeout = 10 |
|
114 LastSessionClosedTimeout = 10 |
|
115 LastSocketClosedTimeout = 10</codeblock> <p>i.e. change the three values from |
|
116 -1 to 10. </p> </li> |
|
117 <li id="GUID-82ECDF33-3782-5399-B192-F8DA06B7CE6D"><p>Save the file and then |
|
118 run <codeph>ced c:\ethernetced.xml</codeph> from the eshell command prompt |
|
119 in the emulator. </p> </li> |
|
120 <li id="GUID-5C6DC453-E01B-5F54-9FE1-3AB384357E7D"><p>Download a UDP Echoserver. |
|
121 An Echoserver is easily available on the internet. </p> </li> |
|
122 <li id="GUID-F5A2E8B3-D8ED-5A3B-AD16-1EC7928B6EEB"><p>Start the UDP Echoserver |
|
123 and edit the <codeph>rconnection.cpp</codeph> file in the example code so |
|
124 that the values for <codeph>KDestAddr</codeph> and <codeph>KSockPort</codeph> match |
|
125 the values being used by the UDP Echoserver. </p> </li> |
|
126 <li id="GUID-CE2E778F-3AB3-5E93-B004-7152AA931072"><p>Build the application |
|
127 using the commands described above and then run it. </p> </li> |
|
128 </ul> <p><b>Hardware: </b> </p> <ul> |
|
129 <li id="GUID-5A2860DF-FF03-585D-87CB-28611B80A0A8"><p>To run the example on |
|
130 an H4 board, connect the H4 to the PC/network by serial cable. Copy <filepath>ethernetced.xml</filepath> to |
|
131 a memory card and execute: </p> <p><userinput>ced e:\ethernetced.xml</userinput> </p> <p>before |
|
132 running the example. </p> </li> |
|
133 </ul> </section> |
|
134 <section><title>Running the example</title> <p>For the emulator, the example |
|
135 builds an executable called <filepath>rconnection.exe</filepath> in the <filepath>epoc32\release\winscw\<udeb |
|
136 or urel>\</filepath> folder. </p> <p> <filepath>rconnection.exe</filepath> is |
|
137 a console-based application. The example takes input from the user and prints |
|
138 to the console information about the various stages of the example. </p> </section> |
|
139 </refbody></reference> |