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

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-BD8446C5-3ADE-59A6-A13A-A5482D6FC56F" xml:lang="en"><title>Connection

Management</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>This topic introduces the concept of Connection Management and the APIs

needed to perform Connection Management operations. The APIs discussed include <xref href="GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD.dita"><apiname>RConnection</apiname></xref> and <xref href="GUID-B16CAD6D-85B1-3482-AAC0-9BADEDB6ABDD.dita"><apiname>RHostResolver</apiname></xref>. </p>

<p>The RConnection API provides: </p>

<ul>

<li id="GUID-395ABFCE-2A51-5205-B3FF-F85C882AF761"><p>an interface for actively

creating and managing connections </p> </li>

<li id="GUID-C3A61C1A-72DF-5304-9758-F6C298DF93AD"><p>facilities that are

not available when creating connections by other methods. Such facilities

include support for multihoming. </p> </li>

</ul>

<p>Introduced with the <keyword>multihoming</keyword> functionality, which

allows multiple Circuit/Packet Switched Data connections to be active. </p>

<p><b>Implementation </b> </p>

<p>The connection management API is implemented by <xref href="GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD.dita"><apiname>RConnection</apiname></xref>. </p>

<p> <xref href="GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD.dita"><apiname>RConnection</apiname></xref> objects are implemented as sub-sessions

to the <xref href="GUID-EF29C1D7-B1E5-370F-AE37-66231A6BE449.dita"><apiname>RSocketServ</apiname></xref>. </p>

<p><b>Connections and subconnections </b> </p>

<p>An RConnection is the handle for an application onto an underlying interface.

(But there may be a number of RConnections per interface). </p>

<p>Technologies such as W-CDMA and later releases of GPRS are capable of establishing

multiple subconnections within a connection. This is supported by the management

interface. </p>

<p>Note that all subconnections within a connection will have certain parameters

in common, such as the Access Point Name in the case of GPRS and WCDMA. However,

each subconnection may have a different Quality-of-Service. </p>

<p><b>Guidelines for use </b> </p>

<p> <codeph>RConnection</codeph> s need to be opened on an existing socket

server session, <xref href="GUID-EF29C1D7-B1E5-370F-AE37-66231A6BE449.dita"><apiname>RSocketServ</apiname></xref>. </p>

<p>In the API as a whole, there is an important distinction made between an <codeph>RConnection</codeph> object

which has been newly opened on an socket server session but not yet associated

with an underlying interface on the server, and one which is opened and associated.

There are certain operations that require a <codeph>RConnection</codeph> object

to be in the associated state to work successfully. The <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-EAB8B0B1-0F5B-31E5-BFD6-B3AE1181868E"><apiname>RConnection::Attach()</apiname></xref> methods

are used to associate an <codeph>RConnection</codeph> object with an interface. </p>

<p>There is no restriction on the number of <codeph>RConnection</codeph> objects

per socket server session. It is also possible for several <codeph>RConnection</codeph> objects

to refer to the same underlying interface. For example, several applications,

each with its own socket server session and <codeph>RConnection</codeph> object,

could refer to the same underlying interface. It is also technically possible

for the said <codeph>RConnection</codeph> objects to be on the same socket

server session, though this may be somewhat redundant. </p>

<p>Rather like <xref href="GUID-D4F08503-F1EF-3531-9C3C-4AF24A6255F0.dita"><apiname>RSocket</apiname></xref> /<xref href="GUID-B16CAD6D-85B1-3482-AAC0-9BADEDB6ABDD.dita"><apiname>RHostResolver</apiname></xref> objects,

an individual <codeph>RConnection</codeph> object is not designed to be used

by multiple clients simultaneously (i.e. have multiple requests outstanding

on it from different clients). </p>

<p>Although <codeph>RConnection</codeph> objects are automatically closed

when the corresponding socket server session is closed, appropriate use of <codeph>CleanupClosePushL(RConnection&amp;)</codeph> is

more likely to ensure proper operation. </p>

<p> <xref href="GUID-D4F08503-F1EF-3531-9C3C-4AF24A6255F0.dita"><apiname>RSocket</apiname></xref> and <xref href="GUID-B16CAD6D-85B1-3482-AAC0-9BADEDB6ABDD.dita"><apiname>RHostResolver</apiname></xref> objects

can be associated with an <codeph>RConnection</codeph> object. In this case,

data will flow over the same underlying interface as the <codeph>RConnection</codeph> to

which they have been associated. For this to work, the <codeph>RSocket/RHostResolver/RConnection</codeph> objects

must all be on the same socket server session, and the <codeph>RConnection</codeph> object

must have been previously opened and active (i.e. associated with an underlying

interface). </p>

<section id="GUID-83D1E933-6A85-40C0-A9D0-7F465953DAFB"><title>Connection Management functionality</title> <p> <codeph>RConnection</codeph> provides

clients with the following functionality: </p> <ul>

<li id="GUID-882DB251-213D-58BF-9398-9ADC68341298"><p>Opening and closing

the connection </p> </li>

<li id="GUID-E20078EE-FE93-5452-877B-C3F7985142FD"><p>Starting a connection,

which means associating it with a new underlying interface </p> </li>

<li id="GUID-FBBB3514-280E-5989-AC76-B81DD8CAC8B8"><p>Attaching the <codeph>RConnection</codeph> instance

to an existing interface </p> </li>

<li id="GUID-BB58A700-B58C-5C26-BD67-688EE0CF55C2"><p>Stopping the connection,

which means disassociating it from the underlying interface </p> </li>

<li id="GUID-A74BD98D-F3A7-5FE4-9F74-60AC2E1FBB78"><p>Obtaining progress information

and notification during connection start-up </p> <p>This is useful because

the process of dialling an ISP, logging in and starting network protocols

can be quite lengthy, taking up to a minute in some cases. In addition, the

application can get the last error which occurred in setting up the connection. </p> <p> </p> </li>

<li id="GUID-9AAABE2A-3FB0-5B63-948F-2B3112683B0C"><p>Notifying when subconnections

come up and go down </p> </li>

<li id="GUID-418DFF66-415A-510D-AB86-1090EE0DC6B8"><p>Notifying when there

is a service change for the connection </p> </li>

<li id="GUID-CF7D3A21-0A1F-537B-AF50-4EDDBB931557"><p>Notifying when a given

amount of data has been sent or received on a connection or subconnection </p> </li>

<li id="GUID-E192532A-F857-5869-B5E0-D657AAFC8290"><p>Reading CommDB fields

specific to an active connection </p> </li>

<li id="GUID-1A83A7BD-FA23-5F4F-8D28-A0A24481DB9F"><p>Collecting statistical

information on the network connection and subconnections. A UI component can

display the collected statistical information in order to allow the user to

examine the status of connections. The information that can be gathered is

the following: </p> <ul>

<li id="GUID-AF90F93C-DA10-539F-842A-34337C51427F"><p>All available internet

access point names and internet access point 'friendly' names as appropriate

for each network (GPRS/UMTS) connection </p> </li>

<li id="GUID-66B29945-C319-5E56-ABCA-301188643CDB"><p>Enumerating the currently

active connections and subconnections </p> </li>

<li id="GUID-8E888149-A79D-5608-9875-9753CEE59EE9"><p>The current status of

all network connections e.g. active/suspended </p> </li>

<li id="GUID-B1125663-747F-5F8C-927F-94AB17482FE5"><p>The amount of data (in

bytes) transferred uplink and downlink by the network connection and subconnections </p> </li>

<li id="GUID-E00B23A4-E91B-54E7-9AE1-429E19C520AB"><p>The amount of time each

network connection has been active (in seconds) </p> </li>

<li id="GUID-7AC5AC0D-9147-52A5-A427-B5D798D9A119"><p>The current status of

the connection and subconnections with respect to data transfer, i.e. active/inactive </p> </li>

<li id="GUID-AD4C0A7A-E48E-513F-806A-40934415D42B"><p>The Quality of Service

profile associated with each Packet Data Protocol (GPRS/UMTS) context, e.g.

low/medium/high </p> </li>

</ul> </li>

</ul> </section>

</conbody><related-links>

<link href="GUID-5CFC075C-8F53-5E1B-A111-C6F4567DFD1E.dita"><linktext>RConnection

API Summary                 Reference</linktext></link>

</related-links></concept>