SubConnection Client API

This document gives an introduction to using the RSubConnection API.

The RSubConnection API creates a channel ("subconnection") within a connection ( RConnection ). Sockets can be attached to this channel and will then be bound by the properties of that channel, such as Quality of Service (values such as minimum bandwith, latency limits etc.). Depending on the state of the channel, it may not be possible to bind arbitary sockets into it. Attempting to bind sockets from different protocol families to a single channel is an error, as each channel can only be used by one protocol family.

Note: The sub-connection can represent an end-to-end channel and/or a channel from this device to an intermediate device (e.g an access server such as a GGSN using UMTS and PDP contexts.) Properties can be specified simultaneously on protocol and link level. In the case of GPRS/UMTS network interfaces, sub-connections correspond to Primary and Secondary PDP Contexts. Before using any of these services, a connection to a socket server session must have been made and the connection must be open.

An RConnection contains one or more sub-connections (a default sub-connection, which is created automatically with the RConnection plus any added RSubConnection s). Each sub-connection has properties. To set those properties you apply an RSubConParameterBundle to the RSubConnection . The parameter bundle consists of families of parameters. A "family" is a connected set of parameters, such as QoS. At present only two families are defined, Quality of Service ( KSubConQoSFamily ) and Authorisation ( KSubConAuthorisationFamily ).

Quality of Service (QoS) in Symbian platform is implemented by setting parameters on the sub-connection.

The RSubConnection API provides the functionality to divide a Connection (provided by the RConnection API) into channels that have properties such as bandwidth and latency.

Each family of parameters can consist of the values you would like to have ( ERequested ) and the minimum you're willing to accept ( EAcceptable ). If you don't specify the EAcceptable then the ERequested will be used as the minimum acceptable. When the parameters have been applied and the sub-connection is used then the parameter family will be updated with a third set of values, the EGranted (which will be somewhere between the EAcceptable and the ERequested ) or an event will be raised to say that the parameters have been rejected/could not be granted. As this may be some time after the initial request, asynchronous event notification is used to tell your application what has been negotiated. Your application must monitor for the granted/rejected event notification.

There is an overlap between the RSubConnection API and the RConnection API as both provide sub-connection management. The RConnection API provides overall sub-connection management for an entire connection whereas the RSubConnection API allows the individual setting of properties of a sub-connection as well as the ability to associate sockets ( RSocket ) with sub-connections. The sockets are then able to take advantage of the sub-connection's properties when they send and receive data.

The RSocket API can be created with a sub-connection as well as a connection. A client is able to start a sub-connection via RSubConnection and associate individual RSocket objects with that sub-connection. This ensures that all data flowing over those objects uses the particular sub-connection previously started by the application. This is implemented using a new RSocket::Open(…) method which takes an additional argument specifying the sub-connection to use for the object in question. The socket will not actually be added to the sub-connection until such time as the socket is used.

As well as opening sub-connections explicitly via RSubConnection , applications may also attach to the default sub-connection (e.g. in GPRS, the default could be the Primary PDP context without a TFT), and modify and retrieve its properties.

Parameters that apply to an RSubConnection are grouped together into "families" ( CSubConParameterFamily ). Each parameter family contains parameter sets that are either "generic" (parameters that are independent of the underlying technology) or "extension" (a group of parameters specific to a technology). There will always be one generic parameter set in a family and there will be zero or more extension parameter sets.