RSubConnection::SetParameters(). The SetParameters function takes an instance of
the RSubConParameterBundle class as a parameter. RSubConParameterBundle specifies the parameters. RSubConParameterBundle is a container for at least one CSubConParameterFamily object. The CSubConParameterFamily objects are referred to as parameter families. An RSubConnection is updated by filling in
an RSubConParameterBundle and calling RSubConnection::SetParameters(). When the CSubConParameterFamily 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.
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 ERequested, EAcceptable, and EGranted. The EGranted parameter
set is created and updated by the underlying communications link and
so should not be changed by your application.
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 RSubConnection::SetParameters(); to add another
family or an additional extension set to the existing parameter family,
it must be added to the original RSubConParameterBundle instance and another call made to RSubConnection::SetParameters(). If the original parameter bundle is not available you may create
a totally new parameter bundle and (optionally) make a call to RSubConnection::GetParameters() to obtain the current settings.
When a family is added to the bundle, the bundle will take ownership
of that object. All added CSubConParameterFamily objects will be destroyed when the parameter bundle is destroyed.
The GetParameters() and SetParameters() methods are used to retrieve and set bundles of properties on the
sub-connection. GetParameters() will return KErrNotReady if no properties have been negotiated. This
may not happen until the sub-connection has been used. The SetParameters() method, like the Add() and Remove() methods returns an error code indicating the success
or failure of the request to perform the action. Upon negotiation
of the properties either the CSubConGenEventParamsGranted or CSubConGenEventParamsRejected event will be
notified for each family within the parameter bundle. A call to the SetParameters() method may not result in any negotiation
until such time as the sub-connection is used.
Remember that
an RSubConnection is updated by filling in an RSubConParameterBundle and calling RSubConnection::SetParameters(). This means that changes to parameter sets will only be applied
when SetParameters() is called. Also note that retrieving
the EGranted parameters will only be effective once
the sub-connection is used and the CSubConGenEventParamsGranted event has been sent.
The AddFamilyL() and FindFamily() methods do just as their names
suggest. It is unlikely that the AddFamilyL() call
will ever be required since the constructor of CSubConParameterFamily adds the family to the passed in parameter bundle automatically.
It is present mainly for internal use.
The ClearAllParameters() method will clear parameters of the given parameter set type from
all families that the bundle owns.
The Load() and Store() methods are used for serialisation
of the parameter bundle, whilst Length() will return
the number of bytes the serialised data will occupy.
An application could add a parameter set of the type TParameterSetType:ERequested to request an ideal level of bandwidth and latency, and a parameter set type of TParameterSetType:EAcceptable could be added to indicate the bare minimum required for the application to operate. A parameter set of the type TParameterSetType:EGranted 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.
Before a call to SetParameters() is made on the sub-connection the family must at least contain a
parameter set of the type TParameterSetType:ERequested. If the parameter set type TParameterSetType:EAcceptable 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 (CSubConGenEventParamsRejected). Any parameter sets of the type EGranted will
be ignored by a call to SetParameters().
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.
The LoadL() method is used to create
a new CSubConParameterFamily from a previously
serialised object. It will be added to the given bundle, which will
taken ownership of the new family.
The SetGenericSetL() and AddExtensionSetL() 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 CSubConParameterFamily the method will leave with KErrAlreadyExists . For example, if an extension set is
added for the type TParameterSetType:ERequested, then another extension set (of the same type) is also added for TParameterSetType:ERequested the method will leave.
The GetGenericSet() and FindExtensionSet() 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.
The ClearAllParameters() method will clear both generic and extension parameter sets of the
given parameter set type from the family.
Id() will return the family identifier.
The Load() and Store() methods are used for serialisation
of the parameter family, whilst Length() will return
the number of bytes the serialised data will occupy.