--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-BD8446C5-3ADE-59A6-A13A-A5482D6FC56F.dita	Wed Mar 31 11:11:55 2010 +0100
@@ -0,0 +1,124 @@
+<?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>
\ No newline at end of file