<?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><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<TUint>& aUplinkVolume, TRequestStatus&

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<TUint>& aDownlinkVolume, TRequestStatus&

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

how to use the SBSv1 build tools. </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><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>