1 <?xml version="1.0" encoding="utf-8"?>

     2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

     3 <!-- This component and the accompanying materials are made available under the terms of the License 

     4 "Eclipse Public License v1.0" which accompanies this distribution, 

     5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE task

    11   PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">

    12 <task id="GUID-30DFBCAD-6A9F-5209-8C40-AB246F54F960" xml:lang="en"><title> QoS

    13 API Tutorial</title><shortdesc>How to use the <apiname>RSubConnection</apiname> API for QoS. </shortdesc><prolog><metadata><keywords/></metadata></prolog><taskbody>

    14 <context id="GUID-54E41E79-A768-4599-B22B-40CBE4D909D9"><p>Quality of Service is implemented by setting parameters on a channel,

    15 a sub-connection <xref href="GUID-0AFDA357-EE44-3788-9CAB-162B874134BF.dita"><apiname>RSubConnection</apiname></xref> within a connection <xref href="GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD.dita"><apiname>RConnection</apiname></xref>.</p></context>

    16 <steps id="GUID-08112C18-3A2F-5624-BE17-AA20C4276104">

    17 <step id="GUID-9D8E746E-B384-54A6-A6D4-2D5ECF882DC5"><cmd>Set parameters on

    18 a channel that is a sub-connection, <xref href="GUID-0AFDA357-EE44-3788-9CAB-162B874134BF.dita"><apiname>RSubConnection</apiname></xref>. </cmd>

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

    20 A default sub-connection is created automatically with the <xref href="GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD.dita"><apiname>RConnection</apiname></xref> and

    21 any added <xref href="GUID-DE825FAA-102B-3E7A-80E6-BC226BD7E64F.dita"><apiname>RSubConnections</apiname></xref>. The <xref href="GUID-0AFDA357-EE44-3788-9CAB-162B874134BF.dita"><apiname>RSubConnection</apiname></xref> API

    22 provides the functionality to divide a connection that is provided by the

    23 RConnection API into channels. The channels have properties such as bandwidth

    24 and latency. </info>

    25 </step>

    26 <step id="GUID-FB7F7F5A-498B-530B-9F45-EEEC17773A08"><cmd>Apply an <xref href="GUID-27AA9BD2-9754-3BAE-8C2D-59937E1924CF.dita"><apiname>RSubConParameterBundle</apiname></xref> to

    27 the <xref href="GUID-0AFDA357-EE44-3788-9CAB-162B874134BF.dita"><apiname>RSubConnection</apiname></xref> to set the sub-connection properties. </cmd>

    28 <info>The parameter bundle consists of families of parameters. A family is

    29 a connected set of parameters, such as QoS. Two families are defined, Quality

    30 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>. </info>

    31 </step>

    32 <step id="GUID-5F819733-168B-5793-921E-8C752D382DE7"><cmd>Group the parameters

    33 that apply to an <xref href="GUID-0AFDA357-EE44-3788-9CAB-162B874134BF.dita"><apiname>RSubConnection</apiname></xref> into <xref href="GUID-5181C974-94F7-3C7D-9FFE-F38BD11001EB.dita"><apiname>CSubConParameterFamily</apiname></xref> families. </cmd>

    34 <info>Each parameter family contains parameter sets that are either generic

    35 or extension. There is one generic parameter set in a family and zero or more

    36 extension parameter sets. </info>

    37 </step>

    38 <step id="GUID-875333D1-493F-53BA-AB9F-891F73920E7F"><cmd>Each family of parameters

    39 consists of the values <xref href="GUID-ADF08336-B43B-31CB-9548-E265E1001F27.dita"><apiname>ERequested</apiname></xref> and the minimum you want

    40 to accept <xref href="GUID-754AF65B-376E-3A75-97F0-8ECF4560BCEF.dita"><apiname>EAcceptable</apiname></xref>. </cmd>

    41 <info>If you do not 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> is

    42 used as the minimum acceptable. </info>

    43 </step>

    44 <step id="GUID-E9B31E46-CC7E-552E-8A79-8E3A803B5601"><cmd>When the parameters

    45 are applied and the subconnection is used then the parameter family is updated

    46 with a third set of values that is the <xref href="GUID-12DF975A-B43E-336F-817E-FDD099F7060A.dita"><apiname>EGranted</apiname></xref>. </cmd>

    47 <info>The <xref href="GUID-12DF975A-B43E-336F-817E-FDD099F7060A.dita"><apiname>EGranted</apiname></xref> is between the <xref href="GUID-754AF65B-376E-3A75-97F0-8ECF4560BCEF.dita"><apiname>EAcceptable</apiname></xref> and

    48 the <xref href="GUID-ADF08336-B43B-31CB-9548-E265E1001F27.dita"><apiname>ERequested</apiname></xref>. </info>

    49 </step>

    50 <step id="GUID-A7588A14-75CF-59AA-90E4-6412FEF794E4"><cmd>An event is raised

    51 to inform that the parameters are rejected or not granted. </cmd>

    52 <info>This occurs after the initial request, asynchronous event notification

    53 is used to inform the application what is negotiated. The application must

    54 monitor for the granted or rejected event notification. </info>

    55 </step>

    56 </steps>

    57 </taskbody></task>