<?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-0116F567-D005-5480-AB37-9799398C0E6F" xml:lang="en"><title> Setting
sub-connection parameters: Tutorial</title><prolog><metadata><keywords/></metadata></prolog><conbody>
<section><title>Introduction</title> This topic describes how to set parameters
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>.
The <codeph>SetParameters</codeph> function takes an instance of the <xref href="GUID-27AA9BD2-9754-3BAE-8C2D-59937E1924CF.dita"><apiname>RSubConParameterBundle</apiname></xref> class
as a parameter. <codeph>RSubConParameterBundle</codeph> specifies the parameters. <codeph>RSubConParameterBundle</codeph> is
a container for at least one <xref href="GUID-5181C974-94F7-3C7D-9FFE-F38BD11001EB.dita"><apiname>CSubConParameterFamily</apiname></xref> object.
The <codeph>CSubConParameterFamily</codeph> objects are referred to as parameter
families. </section>
<section><title>Procedure</title> <p> An <xref href="GUID-0AFDA357-EE44-3788-9CAB-162B874134BF.dita"><apiname>RSubConnection</apiname></xref> is
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>.
When the <xref href="GUID-5181C974-94F7-3C7D-9FFE-F38BD11001EB.dita"><apiname>CSubConParameterFamily</apiname></xref> constructor is called,
it adds the family to the named bundle automatically. The bundle takes ownership
of the family and when the bundle is destroyed, it will destroy the parameter
family. </p><p> For example, a particular bundle may contain a QoS family.
The QoS family may contain (for example) one generic and two extension parameter
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>,
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
set is created and updated by the underlying communications link and so should
not be changed by your application. </p> <p> An instance of a parameter bundle
can only be applied as a single action. That is, if one parameter family is
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>;
to add another family or an additional extension set to the existing parameter
family, it must be added to the original <xref href="GUID-27AA9BD2-9754-3BAE-8C2D-59937E1924CF.dita"><apiname>RSubConParameterBundle</apiname></xref> instance
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>.
If the original parameter bundle is not available you may create a totally
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
obtain the current settings. When a family is added to the bundle, the bundle
will take ownership of that object. All added <xref href="GUID-5181C974-94F7-3C7D-9FFE-F38BD11001EB.dita"><apiname>CSubConParameterFamily</apiname></xref> objects
will be destroyed when the parameter bundle is destroyed. </p> <p>The <codeph>GetParameters() </codeph> and <codeph>SetParameters()</codeph> methods
are used to retrieve and set bundles of properties on the sub-connection. <codeph>GetParameters()</codeph> will
return <xref href="GUID-51298FCE-7857-39F8-BFAB-49AF5556D0CC.dita"><apiname>KErrNotReady</apiname></xref> if no properties have been negotiated.
This may not happen until the sub-connection has been used. The <codeph>SetParameters()</codeph> method,
like the <codeph>Add()</codeph> and <codeph>Remove()</codeph> methods returns
an error code indicating the success or failure of the request to perform
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
to the <codeph>SetParameters()</codeph> method may not result in any negotiation
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
updated by filling in an <xref href="GUID-27AA9BD2-9754-3BAE-8C2D-59937E1924CF.dita"><apiname>RSubConParameterBundle</apiname></xref> and calling <codeph>RSubConnection::SetParameters()</codeph>.
This means that changes to parameter sets will only be applied when <codeph>SetParameters()</codeph> is
called. Also note that retrieving the <xref href="GUID-12DF975A-B43E-336F-817E-FDD099F7060A.dita"><apiname>EGranted</apiname></xref> parameters
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
has been sent. </p></section>
<section/>
<section><title>Using RSubConParameterBundle</title> <p>The <codeph>AddFamilyL()</codeph> and <codeph>FindFamily()</codeph> methods
do just as their names suggest. It is unlikely that the <codeph>AddFamilyL()</codeph> call
will ever be required since the constructor of <xref href="GUID-5181C974-94F7-3C7D-9FFE-F38BD11001EB.dita"><apiname>CSubConParameterFamily</apiname></xref> adds
the family to the passed in parameter bundle automatically. It is present
mainly for internal use. </p> <p>The <codeph>ClearAllParameters()</codeph> method
will clear parameters of the given parameter set type from all families that
the bundle owns. </p> <p>The <codeph>Load()</codeph> and <codeph>Store()</codeph> methods
are used for serialisation of the parameter bundle, whilst <codeph>Length()</codeph> will
return the number of bytes the serialised data will occupy. </p> </section>
<section><title>Using CSubConParameterFamily</title> <p>An application could
add a parameter set of the type <xref href="GUID-ADF08336-B43B-31CB-9548-E265E1001F27.dita"><apiname>ERequested</apiname></xref> to request an
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
be added to indicate the bare minimum required for the application to operate.
A parameter set of the type <xref href="GUID-12DF975A-B43E-336F-817E-FDD099F7060A.dita"><apiname>EGranted</apiname></xref> must never be added
by an application. The sub-connection's parameter bundle will be updated with
parameter sets of this (granted) type when the negotiated settings change,
such as when the sub-connection is established/used. </p> <p>Before a call
to <codeph>SetParameters()</codeph> is made on the sub-connection the family
must at least contain a parameter set of the type <xref href="GUID-ADF08336-B43B-31CB-9548-E265E1001F27.dita"><apiname>ERequested</apiname></xref>.
If the parameter set type <xref href="GUID-754AF65B-376E-3A75-97F0-8ECF4560BCEF.dita"><apiname>EAcceptable</apiname></xref> is omitted the requested
values will used as the acceptable values. This means that if you request
a bandwidth of 256k and only 128k is available, an event will be returned
saying that the requested bandwidth is not available (<xref href="GUID-7103CFA3-2119-3356-9460-B26D88036FEB.dita"><apiname>CSubConGenEventParamsRejected</apiname></xref>).
Any parameter sets of the type <xref href="GUID-12DF975A-B43E-336F-817E-FDD099F7060A.dita"><apiname>EGranted</apiname></xref> will be ignored
by a call to <codeph>SetParameters()</codeph>. </p> <p>When a generic or extension
set is added to the family, the parameter family object will take ownership
of that parameter set. All added parameter sets will be deleted along with
the parameter family. </p> <p>The <codeph>LoadL()</codeph> method is used
to create a new <xref href="GUID-5181C974-94F7-3C7D-9FFE-F38BD11001EB.dita"><apiname>CSubConParameterFamily</apiname></xref> from a previously
serialised object. It will be added to the given bundle, which will taken
ownership of the new family. </p> <p>The <codeph>SetGenericSetL()</codeph> and <codeph>AddExtensionSetL()</codeph> methods
are used to add parameter sets to the family. If the type of parameter set
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
method will leave with <xref href="GUID-D1D25122-F2B8-3C78-8599-84905BFD47B8.dita"><apiname>KErrAlreadyExists</apiname></xref>. For example,
if an extension set is added for the type <xref href="GUID-ADF08336-B43B-31CB-9548-E265E1001F27.dita"><apiname>ERequested</apiname></xref>, then
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
method will leave. </p> <p>The <codeph>GetGenericSet()</codeph> and <codeph>FindExtensionSet()</codeph> methods
are used to retrieve a parameter set from the parameter family. If there is
no generic set or extension set of the specified type then NULL is returned. </p> <p>The <codeph>ClearAllParameters()</codeph> method
will clear both generic and extension parameter sets of the given parameter
set type from the family. </p> <p> <codeph>Id()</codeph> will return the family
identifier. </p> <p>The <codeph>Load()</codeph> and <codeph>Store()</codeph> methods
are used for serialisation of the parameter family, whilst <codeph>Length()</codeph> will
return the number of bytes the serialised data will occupy. </p> </section>
<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
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
QoS Parameters</xref> Reference </p> </section>
</conbody></concept>