Setting sub-connection parameters: Tutorial

Introduction

This topic describes how to set parameters on a subconnection. Parameters are set on a subconnection using 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.

Procedure

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.

Using RSubConParameterBundle

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.

Using CSubConParameterFamily

An application could add a parameter set of the type ERequested to request an ideal level of bandwidth and latency, and a parameter set type of EAcceptable could be added to indicate the bare minimum required for the application to operate. A parameter set of the type 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 ERequested. If the parameter set type 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 ERequested, then another extension set (of the same type) is also added for 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.

See Also

RSubConnection Events Reference

RSubConnection QoS Parameters Reference