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 concept

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

    12 <concept id="GUID-0116F567-D005-5480-AB37-9799398C0E6F" xml:lang="en"><title> Setting

    13 sub-connection parameters: Tutorial</title><prolog><metadata><keywords/></metadata></prolog><conbody>

    14 <section><title>Introduction</title> This topic describes how to set parameters

    15 on a subconnection. Parameters are set on a subconnection using <xref href="GUID-0AFDA357-EE44-3788-9CAB-162B874134BF.dita#GUID-0AFDA357-EE44-3788-9CAB-162B874134BF/GUID-FA1056C6-FAE7-3E0F-9375-9F5A6315AE24"><apiname>RSubConnection::SetParameters()</apiname></xref>.

    16 The <codeph>SetParameters</codeph> function takes an instance of the <xref href="GUID-27AA9BD2-9754-3BAE-8C2D-59937E1924CF.dita"><apiname>RSubConParameterBundle</apiname></xref> class

    17 as a parameter. <codeph>RSubConParameterBundle</codeph> specifies the parameters. <codeph>RSubConParameterBundle</codeph> is

    18 a container for at least one <xref href="GUID-5181C974-94F7-3C7D-9FFE-F38BD11001EB.dita"><apiname>CSubConParameterFamily</apiname></xref> object.

    19 The <codeph>CSubConParameterFamily</codeph> objects are referred to as parameter

    20 families. </section>

    21 <section><title>Procedure</title> <p> An <xref href="GUID-0AFDA357-EE44-3788-9CAB-162B874134BF.dita"><apiname>RSubConnection</apiname></xref> is

    22 updated by filling in an <xref href="GUID-27AA9BD2-9754-3BAE-8C2D-59937E1924CF.dita"><apiname>RSubConParameterBundle</apiname></xref> and calling <xref href="GUID-0AFDA357-EE44-3788-9CAB-162B874134BF.dita#GUID-0AFDA357-EE44-3788-9CAB-162B874134BF/GUID-FA1056C6-FAE7-3E0F-9375-9F5A6315AE24"><apiname>RSubConnection::SetParameters()</apiname></xref>.

    23 When the <xref href="GUID-5181C974-94F7-3C7D-9FFE-F38BD11001EB.dita"><apiname>CSubConParameterFamily</apiname></xref> constructor is called,

    24 it adds the family to the named bundle automatically. The bundle takes ownership

    25 of the family and when the bundle is destroyed, it will destroy the parameter

    26 family. </p><p> For example, a particular bundle may contain a QoS family.

    27 The QoS family may contain (for example) one generic and two extension parameter

    28 sets. Each of those parameter sets may exist as <xref href="GUID-ADF08336-B43B-31CB-9548-E265E1001F27.dita"><apiname>ERequested</apiname></xref>, <xref href="GUID-754AF65B-376E-3A75-97F0-8ECF4560BCEF.dita"><apiname>EAcceptable</apiname></xref>,

    29 and <xref href="GUID-12DF975A-B43E-336F-817E-FDD099F7060A.dita"><apiname>EGranted</apiname></xref>. The <xref href="GUID-12DF975A-B43E-336F-817E-FDD099F7060A.dita"><apiname>EGranted</apiname></xref> parameter

    30 set is created and updated by the underlying communications link and so should

    31 not be changed by your application. </p> <p> An instance of a parameter bundle

    32 can only be applied as a single action. That is, if one parameter family is

    33 added to the bundle and a call is made to <xref href="GUID-0AFDA357-EE44-3788-9CAB-162B874134BF.dita#GUID-0AFDA357-EE44-3788-9CAB-162B874134BF/GUID-FA1056C6-FAE7-3E0F-9375-9F5A6315AE24"><apiname>RSubConnection::SetParameters()</apiname></xref>;

    34 to add another family or an additional extension set to the existing parameter

    35 family, it must be added to the original <xref href="GUID-27AA9BD2-9754-3BAE-8C2D-59937E1924CF.dita"><apiname>RSubConParameterBundle</apiname></xref> instance

    36 and another call made to <xref href="GUID-0AFDA357-EE44-3788-9CAB-162B874134BF.dita#GUID-0AFDA357-EE44-3788-9CAB-162B874134BF/GUID-FA1056C6-FAE7-3E0F-9375-9F5A6315AE24"><apiname>RSubConnection::SetParameters()</apiname></xref>.

    37 If the original parameter bundle is not available you may create a totally

    38 new parameter bundle and (optionally) make a call to <xref href="GUID-0AFDA357-EE44-3788-9CAB-162B874134BF.dita#GUID-0AFDA357-EE44-3788-9CAB-162B874134BF/GUID-6E4D49A9-CBD3-3A1C-8CDC-C33E8E26928F"><apiname>RSubConnection::GetParameters()</apiname></xref> to

    39 obtain the current settings. When a family is added to the bundle, the bundle

    40 will take ownership of that object. All added <xref href="GUID-5181C974-94F7-3C7D-9FFE-F38BD11001EB.dita"><apiname>CSubConParameterFamily</apiname></xref> objects

    41 will be destroyed when the parameter bundle is destroyed. </p> <p>The <codeph>GetParameters() </codeph> and <codeph>SetParameters()</codeph> methods

    42 are used to retrieve and set bundles of properties on the sub-connection. <codeph>GetParameters()</codeph> will

    43 return <xref href="GUID-51298FCE-7857-39F8-BFAB-49AF5556D0CC.dita"><apiname>KErrNotReady</apiname></xref> if no properties have been negotiated.

    44 This may not happen until the sub-connection has been used. The <codeph>SetParameters()</codeph> method,

    45 like the <codeph>Add()</codeph> and <codeph>Remove()</codeph> methods returns

    46 an error code indicating the success or failure of the request to perform

    47 the action. Upon negotiation of the properties either the <xref href="GUID-AA6CFA1E-0B17-3603-9065-34D05322C0A5.dita"><apiname>CSubConGenEventParamsGranted</apiname></xref> or <xref href="GUID-7103CFA3-2119-3356-9460-B26D88036FEB.dita"><apiname>CSubConGenEventParamsRejected</apiname></xref> event will be notified for each family within the parameter bundle. A call

    48 to the <codeph>SetParameters()</codeph> method may not result in any negotiation

    49 until such time as the sub-connection is used. </p> <p>Remember that an <xref href="GUID-0AFDA357-EE44-3788-9CAB-162B874134BF.dita"><apiname>RSubConnection</apiname></xref> is

    50 updated by filling in an <xref href="GUID-27AA9BD2-9754-3BAE-8C2D-59937E1924CF.dita"><apiname>RSubConParameterBundle</apiname></xref> and calling <codeph>RSubConnection::SetParameters()</codeph>.

    51 This means that changes to parameter sets will only be applied when <codeph>SetParameters()</codeph> is

    52 called. Also note that retrieving the <xref href="GUID-12DF975A-B43E-336F-817E-FDD099F7060A.dita"><apiname>EGranted</apiname></xref> parameters

    53 will only be effective once the sub-connection is used and the <xref href="GUID-AA6CFA1E-0B17-3603-9065-34D05322C0A5.dita"><apiname>CSubConGenEventParamsGranted</apiname></xref> event

    54 has been sent. </p></section>

    55 <section/>

    56 <section><title>Using RSubConParameterBundle</title> <p>The <codeph>AddFamilyL()</codeph> and <codeph>FindFamily()</codeph> methods

    57 do just as their names suggest. It is unlikely that the <codeph>AddFamilyL()</codeph> call

    58 will ever be required since the constructor of <xref href="GUID-5181C974-94F7-3C7D-9FFE-F38BD11001EB.dita"><apiname>CSubConParameterFamily</apiname></xref> adds

    59 the family to the passed in parameter bundle automatically. It is present

    60 mainly for internal use. </p> <p>The <codeph>ClearAllParameters()</codeph> method

    61 will clear parameters of the given parameter set type from all families that

    62 the bundle owns. </p> <p>The <codeph>Load()</codeph> and <codeph>Store()</codeph> methods

    63 are used for serialisation of the parameter bundle, whilst <codeph>Length()</codeph> will

    64 return the number of bytes the serialised data will occupy. </p> </section>

    65 <section><title>Using CSubConParameterFamily</title> <p>An application could

    66 add a parameter set of the type <xref href="GUID-ADF08336-B43B-31CB-9548-E265E1001F27.dita"><apiname>ERequested</apiname></xref> to request an

    67 ideal level of bandwidth and latency, and a parameter set type of <xref href="GUID-754AF65B-376E-3A75-97F0-8ECF4560BCEF.dita"><apiname>EAcceptable</apiname></xref> could

    68 be added to indicate the bare minimum required for the application to operate.

    69 A parameter set of the type <xref href="GUID-12DF975A-B43E-336F-817E-FDD099F7060A.dita"><apiname>EGranted</apiname></xref> must never be added

    70 by an application. The sub-connection's parameter bundle will be updated with

    71 parameter sets of this (granted) type when the negotiated settings change,

    72 such as when the sub-connection is established/used. </p> <p>Before a call

    73 to <codeph>SetParameters()</codeph> is made on the sub-connection the family

    74 must at least contain a parameter set of the type <xref href="GUID-ADF08336-B43B-31CB-9548-E265E1001F27.dita"><apiname>ERequested</apiname></xref>.

    75 If the parameter set type <xref href="GUID-754AF65B-376E-3A75-97F0-8ECF4560BCEF.dita"><apiname>EAcceptable</apiname></xref> is omitted the requested

    76 values will used as the acceptable values. This means that if you request

    77 a bandwidth of 256k and only 128k is available, an event will be returned

    78 saying that the requested bandwidth is not available (<xref href="GUID-7103CFA3-2119-3356-9460-B26D88036FEB.dita"><apiname>CSubConGenEventParamsRejected</apiname></xref>).

    79 Any parameter sets of the type <xref href="GUID-12DF975A-B43E-336F-817E-FDD099F7060A.dita"><apiname>EGranted</apiname></xref> will be ignored

    80 by a call to <codeph>SetParameters()</codeph>. </p> <p>When a generic or extension

    81 set is added to the family, the parameter family object will take ownership

    82 of that parameter set. All added parameter sets will be deleted along with

    83 the parameter family. </p> <p>The <codeph>LoadL()</codeph> method is used

    84 to create a new <xref href="GUID-5181C974-94F7-3C7D-9FFE-F38BD11001EB.dita"><apiname>CSubConParameterFamily</apiname></xref> from a previously

    85 serialised object. It will be added to the given bundle, which will taken

    86 ownership of the new family. </p> <p>The <codeph>SetGenericSetL()</codeph> and <codeph>AddExtensionSetL()</codeph> methods

    87 are used to add parameter sets to the family. If the type of parameter set

    88 added/set is the same as a parameter set type already contained by the <xref href="GUID-5181C974-94F7-3C7D-9FFE-F38BD11001EB.dita"><apiname>CSubConParameterFamily</apiname></xref> the

    89 method will leave with <xref href="GUID-D1D25122-F2B8-3C78-8599-84905BFD47B8.dita"><apiname>KErrAlreadyExists</apiname></xref>. For example,

    90 if an extension set is added for the type <xref href="GUID-ADF08336-B43B-31CB-9548-E265E1001F27.dita"><apiname>ERequested</apiname></xref>, then

    91 another extension set (of the same type) is also added for <xref href="GUID-ADF08336-B43B-31CB-9548-E265E1001F27.dita"><apiname>ERequested</apiname></xref> the

    92 method will leave. </p> <p>The <codeph>GetGenericSet()</codeph> and <codeph>FindExtensionSet()</codeph> methods

    93 are used to retrieve a parameter set from the parameter family. If there is

    94 no generic set or extension set of the specified type then NULL is returned. </p> <p>The <codeph>ClearAllParameters()</codeph> method

    95 will clear both generic and extension parameter sets of the given parameter

    96 set type from the family. </p> <p> <codeph>Id()</codeph> will return the family

    97 identifier. </p> <p>The <codeph>Load()</codeph> and <codeph>Store()</codeph> methods

    98 are used for serialisation of the parameter family, whilst <codeph>Length()</codeph> will

    99 return the number of bytes the serialised data will occupy. </p> </section>

   100 <section><title>See Also</title> <p> <xref href="GUID-12C9C36B-8AD4-544E-A6A3-54A799EF0280.dita#GUID-12C9C36B-8AD4-544E-A6A3-54A799EF0280/GUID-7803B89A-6ABF-529C-A0B8-CA06BA410F3B">RSubConnection

   101 Events</xref> Reference </p> <p> <xref href="GUID-12C9C36B-8AD4-544E-A6A3-54A799EF0280.dita#GUID-12C9C36B-8AD4-544E-A6A3-54A799EF0280/GUID-7F057E16-0E56-5989-8647-7DAFF6E343D3">RSubConnection

   102 QoS Parameters</xref> Reference </p> </section>

   103 </conbody></concept>