<?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-06CE943B-3D6A-50D1-97C3-CCFE4D4F5864" xml:lang="en"><title>SubConnection

Client API</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>This document gives an introduction to using the <xref href="GUID-0AFDA357-EE44-3788-9CAB-162B874134BF.dita"><apiname>RSubConnection</apiname></xref> API. </p>

<p>The <xref href="GUID-0AFDA357-EE44-3788-9CAB-162B874134BF.dita"><apiname>RSubConnection</apiname></xref> API creates a channel ("subconnection")

within a connection (<xref href="GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD.dita"><apiname>RConnection</apiname></xref>). Sockets can be attached

to this channel and will then be bound by the properties of that channel,

such as Quality of Service (values such as minimum bandwith, latency limits

etc.). Depending on the state of the channel, it may not be possible to bind

arbitary sockets into it. Attempting to bind sockets from different protocol

families to a single channel is an error, as each channel can only be used

by one protocol family. </p>

<p>Note: The sub-connection can represent an end-to-end channel and/or a channel

from this device to an intermediate device (e.g an access server such as a

GGSN using UMTS and PDP contexts.) Properties can be specified simultaneously

on protocol and link level. In the case of GPRS/UMTS network interfaces, sub-connections

correspond to Primary and Secondary PDP Contexts. Before using any of these

services, a connection to a socket server session must have been made and

the connection must be open. </p>

<p>An <xref href="GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD.dita"><apiname>RConnection</apiname></xref> contains one or more sub-connections

(a default sub-connection, which is created automatically with the <xref href="GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD.dita"><apiname>RConnection</apiname></xref> plus

any added <xref href="GUID-0AFDA357-EE44-3788-9CAB-162B874134BF.dita"><apiname>RSubConnection</apiname></xref> s). Each sub-connection has properties.

To set those properties you apply an <xref href="GUID-27AA9BD2-9754-3BAE-8C2D-59937E1924CF.dita"><apiname>RSubConParameterBundle</apiname></xref> to

the <xref href="GUID-0AFDA357-EE44-3788-9CAB-162B874134BF.dita"><apiname>RSubConnection</apiname></xref>. The parameter bundle consists of families

of parameters. A "family" is a connected set of parameters, such as QoS. At

present only two families are defined, Quality of Service (<xref href="GUID-022ECBFB-911A-330B-B197-3BDAE6493981.dita"><apiname>KSubConQoSFamily</apiname></xref>)

and Authorisation (<xref href="GUID-B2567E44-BD9B-39B3-BB97-385124CFD973.dita"><apiname>KSubConAuthorisationFamily</apiname></xref>). </p>

<p>Quality of Service (QoS) in Symbian platform is implemented by setting

parameters on the sub-connection. </p>

<p>The <xref href="GUID-0AFDA357-EE44-3788-9CAB-162B874134BF.dita"><apiname>RSubConnection</apiname></xref> API provides the functionality to

divide a Connection (provided by the <xref href="GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD.dita"><apiname>RConnection</apiname></xref> API) into

channels that have properties such as bandwidth and latency. </p>

<p>Each family of parameters can consist of the values you would like to have

(<xref href="GUID-ADF08336-B43B-31CB-9548-E265E1001F27.dita"><apiname>ERequested</apiname></xref>) and the minimum you're willing to accept (<xref href="GUID-754AF65B-376E-3A75-97F0-8ECF4560BCEF.dita"><apiname>EAcceptable</apiname></xref>).

If you don't specify the <xref href="GUID-754AF65B-376E-3A75-97F0-8ECF4560BCEF.dita"><apiname>EAcceptable</apiname></xref> then the <xref href="GUID-ADF08336-B43B-31CB-9548-E265E1001F27.dita"><apiname>ERequested</apiname></xref> will

be used as the minimum acceptable. When the parameters have been applied and

the sub-connection is used then the parameter family will be updated with

a third set of values, the <xref href="GUID-12DF975A-B43E-336F-817E-FDD099F7060A.dita"><apiname>EGranted</apiname></xref> (which will be somewhere

between the <xref href="GUID-754AF65B-376E-3A75-97F0-8ECF4560BCEF.dita"><apiname>EAcceptable</apiname></xref> and the <xref href="GUID-ADF08336-B43B-31CB-9548-E265E1001F27.dita"><apiname>ERequested</apiname></xref>)

or an event will be raised to say that the parameters have been rejected/could

not be granted. As this may be some time after the initial request, asynchronous

event notification is used to tell your application what has been negotiated.

Your application must monitor for the granted/rejected event notification. </p>

<p>There is an overlap between the <xref href="GUID-0AFDA357-EE44-3788-9CAB-162B874134BF.dita"><apiname>RSubConnection</apiname></xref> API and

the <xref href="GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD.dita"><apiname>RConnection</apiname></xref> API as both provide sub-connection management.

The <xref href="GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD.dita"><apiname>RConnection</apiname></xref> API provides overall sub-connection management

for an entire connection whereas the <xref href="GUID-0AFDA357-EE44-3788-9CAB-162B874134BF.dita"><apiname>RSubConnection</apiname></xref> API

allows the individual setting of properties of a sub-connection as well as

the ability to associate sockets (<xref href="GUID-D4F08503-F1EF-3531-9C3C-4AF24A6255F0.dita"><apiname>RSocket</apiname></xref>) with sub-connections.

The sockets are then able to take advantage of the sub-connection's properties

when they send and receive data. </p>

<p>The <xref href="GUID-D4F08503-F1EF-3531-9C3C-4AF24A6255F0.dita"><apiname>RSocket</apiname></xref> API can be created with a sub-connection

as well as a connection. A client is able to start a sub-connection via <xref href="GUID-0AFDA357-EE44-3788-9CAB-162B874134BF.dita"><apiname>RSubConnection</apiname></xref> and

associate individual <xref href="GUID-D4F08503-F1EF-3531-9C3C-4AF24A6255F0.dita"><apiname>RSocket</apiname></xref> objects with that sub-connection.

This ensures that all data flowing over those objects uses the particular

sub-connection previously started by the application. This is implemented

using a new <xref href="GUID-D4F08503-F1EF-3531-9C3C-4AF24A6255F0.dita#GUID-D4F08503-F1EF-3531-9C3C-4AF24A6255F0/GUID-89C92445-FFCA-37F0-88D0-BF9B1B41BA2F"><apiname>RSocket::Open(…)</apiname></xref> method which takes an additional

argument specifying the sub-connection to use for the object in question.

The socket will not actually be added to the sub-connection until such time

as the socket is used. </p>

<p>As well as opening sub-connections explicitly via <xref href="GUID-0AFDA357-EE44-3788-9CAB-162B874134BF.dita"><apiname>RSubConnection</apiname></xref>,

applications may also attach to the default sub-connection (e.g. in GPRS,

the default could be the Primary PDP context without a TFT), and modify and

retrieve its properties. </p>

<p>Parameters that apply to an <xref href="GUID-0AFDA357-EE44-3788-9CAB-162B874134BF.dita"><apiname>RSubConnection</apiname></xref> are grouped

together into "families" (<xref href="GUID-5181C974-94F7-3C7D-9FFE-F38BD11001EB.dita"><apiname>CSubConParameterFamily</apiname></xref>). Each

parameter family contains parameter sets that are either "generic" (parameters

that are independent of the underlying technology) or "extension" (a group

of parameters specific to a technology). There will always be one generic

parameter set in a family and there will be zero or more extension parameter

sets. </p>