Setting -sub-connection parameters: Tutorial

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

+ + + + + + 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.