<?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 reference
  PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
<reference id="GUID-D24D5F17-462E-5424-99A7-9B16E9FEDC93" xml:lang="en"><title>Rconnection: connection monitoring and management example</title><shortdesc>This example demonstrates the use of the <codeph>RConnection</codeph> API to do connection monitoring and management. </shortdesc><prolog><metadata><keywords/></metadata></prolog><refbody>
<section id="GUID-E0BC58A2-4011-4836-91F6-A7FD2EEAC983"><title>Purpose</title> <p>The example demonstrates the following
features of the <xref href="GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD.dita"><apiname>RConnection</apiname></xref> API: </p> <ul>
<li id="GUID-01B8C3CB-4C74-51B5-A9B1-6CE1D5DD0360"><p>Opening and
closing 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&amp;
aSocketServer, 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>
<li id="GUID-A5CDAFC8-771C-56A1-86BF-E4731EB7D325"><p>Starting a connection
that uses the default CommDb connection preferences, and another connection
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&amp; aPref)</apiname></xref>. </p> </li>
<li id="GUID-DF26CF2F-E012-5752-88B8-2E2FBE4DC0BC"><p>Getting the
number of 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&amp;      
          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
aIndex,                 TDes8&amp; aConnectionInfo)</apiname></xref>. </p> </li>
<li id="GUID-43861187-FF27-56BD-8B09-F5FC3456FB0D"><p>Attaching a
connection 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&amp; aConnectionInfo,                 TConnAttachType aAttachType)</apiname></xref>. </p> </li>
<li id="GUID-3C89B0C2-3378-5D8B-A519-F5689ACA65EC"><p>Registering
for notifications when: </p> <ul>
<li id="GUID-61A4C660-FA35-51DC-A4F1-715CC630052D"><p>a certain amount
of 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
aThreshold,                      TPckg&lt;TUint&gt;&amp; aUplinkVolume,
TRequestStatus&amp; aStatus)</apiname></xref>. </p> </li>
<li id="GUID-40B69177-D7DB-5920-98DF-A681E5EB21E8"><p>a certain amout
of data 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
aThreshold,                      TPckg&lt;TUint&gt;&amp; aDownlinkVolume,
TRequestStatus&amp;                      aStatus)</apiname></xref>. </p> </li>
<li id="GUID-48F1D550-A56C-5F52-A870-C74C63BB8FFE"><p>interfaces go
up and 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&amp;
aNotification,                      TRequestStatus&amp; aStatus)</apiname></xref>. </p> </li>
<li id="GUID-15E99A35-D6C3-5F28-98C5-72B80B594EBB"><p>the connection
changes 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&amp;
aProgress,                      TRequestStatus&amp; aStatus, TUint
aSelectedProgress =                      KConnProgressDefault)</apiname></xref>. </p> </li>
</ul> </li>
<li id="GUID-57C9068C-1380-5397-A090-1D9FC1587FED"><p>Obtaining the
amount 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>
<li id="GUID-FAA3F969-67AF-5716-92F9-B5BDBC038906"><p>Obtaining the
connection's 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&amp;
aProgress)</apiname></xref>. </p> </li>
<li id="GUID-14CBAB9C-F93D-5A0D-A63E-B18D2209D38A"><p>Stopping the
connection, 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>
<li id="GUID-0525FECB-37A0-5373-93DD-92BCB1317078"><p>Closing the
session 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>
</ul> </section>
<section id="GUID-823CFB5C-C788-4B90-83A2-41DDA2626519"><title>Download</title><p>Click on the following link to
download 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>
<section id="GUID-C975476C-C2B7-4D9D-AF13-CB2AE995D5E3"><title>Class Summary</title><p>The example demonstrates the
following 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>
<section id="GUID-1AC878AD-5D60-4DE9-A47F-43C76816D43F"><title>Design and implementation</title> <p>The project implements
a single class called <codeph>CRConnection</codeph>, that has three
principal functions: </p> <p><b>CRConnection::DemoApiWithoutDbOverrideL() </b> </p> <p>This shows how to use <xref href="GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD.dita"><apiname>RConnection</apiname></xref> to: </p> <ul>
<li id="GUID-01D4595A-2723-53C8-9499-7215FFA219C3"><p>start a connection
and associate it with an underlying interface, using default CommDb
connection preferences, </p> </li>
<li id="GUID-6377E5AB-71D3-50F1-B084-E8891BB73BB9"><p>get notification
when the underlying interface goes up or down, </p> </li>
<li id="GUID-37FF8270-7FD1-5B27-9E9A-BC6D49E02B4D"><p>get notification
about the state of a connection as it becomes fully established, </p> </li>
<li id="GUID-E396A06F-5156-5924-9B68-649575A1CA62"><p>transfer data
over a socket, </p> </li>
<li id="GUID-584D9C8C-A317-51D0-8AD2-397337F1A332"><p>get the amount
of data transferred, </p> </li>
<li id="GUID-23588938-CEE7-5AD9-8C9D-9FA253AE11D2"><p>close the connection. </p> </li>
</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 is
the same as <codeph>DemoApiWithoutDbOverrideL()</codeph> except that
it: </p> <ul>
<li id="GUID-C61443A2-8576-59F3-A586-30DDF1D2AD56"><p>starts a connection
using non-default CommDb connection preferences, </p> </li>
<li id="GUID-9777305D-11BC-5BD4-AFE0-2ED3D010BE93"><p>requests notification
when a threshold amount of data has been transferred (instead of getting
the amount of data transferred). </p> </li>
</ul> <p><b>CRConnection::AttachToExistingInterfaceL() </b> </p> <p>This shows how to use <xref href="GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD.dita"><apiname>RConnection</apiname></xref> to: </p> <ul>
<li id="GUID-CB835CF4-BD2A-55E5-BEF7-248A0750B466"><p>open 2 connections
and start one of them (the other is not yet associated with an underlying
interface), </p> </li>
<li id="GUID-DE013E1E-E3C3-513C-B0B6-5B16E6000C5C"><p>get connection
information for the 1st connection and use this to attach the 2nd
connection to the existing interface, </p> </li>
<li id="GUID-BCA6E282-7C55-5416-884F-F88172672D8B"><p>get the state
of the attached connection, </p> </li>
<li id="GUID-8A107877-F6BD-5580-ADB5-230F86B36CD4"><p>close the connections. </p> </li>
</ul> </section>
<section id="GUID-2292DC4F-A2DF-4EFA-8EBC-DE278D375037"><title>Building and configuring</title> <p>You can build
the example from the IDE or the command line. </p> <p>If you use an
IDE, import the <filepath>bld.inf</filepath> file into your IDE, and
use the build command of the IDE. </p> <p>If you use the command line,
open a command prompt, and set the current directory to the source
code directory of the example. You can then build the example using
the SBSv1 build tools with the following commands: </p> <p><userinput>bldmake bldfiles</userinput> </p> <p><userinput>abld build</userinput> </p> <p><b>Emulator: </b> </p> <p>Before running
the example, the emulator must be set up to use ethernet, as follows: </p> <ul>
<li id="GUID-1C477C42-8F6B-57F1-A8CE-F1CBAA22F265"><p>Install <xref href="GUID-CDD1E761-6B28-5F69-BBEF-756DF45E59A2.dita">WinPCap 4.0.2</xref> </p> </li>
<li id="GUID-C79C333A-AF6E-5587-8BA0-B19C470C2D09"><p>Configure the
emulator using <xref href="GUID-7B114A67-356A-5FCE-B57B-761F5477A2B2.dita">configchange.pl</xref> for instance: </p> <p><userinput>configchange.pl
--config ethernetWithCommDB --kernel EKA2 --target winscw --variant
udeb</userinput> </p> </li>
<li id="GUID-FBAD862F-DFA3-5E7E-8F69-3C4B3CF9E56B"><p>Open <filepath>ethernetced.xml</filepath> in <filepath>epoc32\winscw\c\</filepath> and change the last 3 values in the <codeph>LANBearer operation</codeph> section for "EKA2 Emulator Ethernet" in the <codeph>LANBearerTable</codeph> to: </p> <codeblock id="GUID-1C6B07F1-521D-5E3A-A4EE-A96FA369D5CA" xml:space="preserve">LastSocketActivityTimeout = 10
LastSessionClosedTimeout = 10
LastSocketClosedTimeout = 10</codeblock> <p>i.e. change the three
values from -1 to 10. </p> </li>
<li id="GUID-82ECDF33-3782-5399-B192-F8DA06B7CE6D"><p>Save the file
and then run <codeph>ced c:\ethernetced.xml</codeph> from the eshell
command prompt in the emulator. </p> </li>
<li id="GUID-5C6DC453-E01B-5F54-9FE1-3AB384357E7D"><p>Download a UDP
Echoserver. An Echoserver is easily available on the internet. </p> </li>
<li id="GUID-F5A2E8B3-D8ED-5A3B-AD16-1EC7928B6EEB"><p>Start the UDP
Echoserver and edit the <codeph>rconnection.cpp</codeph> file in the
example code so that the values for <codeph>KDestAddr</codeph> and <codeph>KSockPort</codeph> match the values being used by the UDP Echoserver. </p> </li>
<li id="GUID-CE2E778F-3AB3-5E93-B004-7152AA931072"><p>Build the application
using the commands described above and then run it. </p> </li>
</ul> <p><b>Hardware: </b> </p> <ul>
<li id="GUID-5A2860DF-FF03-585D-87CB-28611B80A0A8"><p>To run the example
on an H4 board, connect the H4 to the PC/network by serial cable.
Copy <filepath>ethernetced.xml</filepath> to a memory card and execute: </p> <p><userinput>ced e:\ethernetced.xml</userinput> </p> <p>before
running the example. </p> </li>
</ul> </section>
<section id="GUID-A5BDDE5F-DA10-4594-A446-C079079D8050"><title>Running the example</title> <p>For the emulator, the
example builds an executable called <filepath>rconnection.exe</filepath> in the <filepath>epoc32\release\winscw\&lt;udeb or urel&gt;\</filepath> folder. </p> <p> <filepath>rconnection.exe</filepath> is a console-based
application. The example takes input from the user and prints to the
console information about the various stages of the example. </p> </section>
</refbody></reference>