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.