This topic introduces the concept of Connection Management and the APIs needed to perform Connection Management operations. The APIs discussed include RConnection and RHostResolver .
The RConnection API provides:
an interface for actively creating and managing connections
facilities that are not available when creating connections by other methods. Such facilities include support for multihoming.
Introduced with the multihoming functionality, which allows multiple Circuit/Packet Switched Data connections to be active.
Implementation
The connection management API is implemented by RConnection .
RConnection objects are implemented as sub-sessions to the RSocketServ .
Connections and subconnections
An RConnection is the handle for an application onto an underlying interface. (But there may be a number of RConnections per interface).
Technologies such as W-CDMA and later releases of GPRS are capable of establishing multiple subconnections within a connection. This is supported by the management interface.
Note that all subconnections within a connection will have certain parameters in common, such as the Access Point Name in the case of GPRS and WCDMA. However, each subconnection may have a different Quality-of-Service.
Guidelines for use
RConnection s need to be opened on an existing socket server session, RSocketServ .
In the API as a whole, there is an important distinction made between an RConnection object which has been newly opened on an socket server session but not yet associated with an underlying interface on the server, and one which is opened and associated. There are certain operations that require a RConnection object to be in the associated state to work successfully. The RConnection::Start() and RConnection::Attach() methods are used to associate an RConnection object with an interface.
There is no restriction on the number of RConnection objects per socket server session. It is also possible for several RConnection objects to refer to the same underlying interface. For example, several applications, each with its own socket server session and RConnection object, could refer to the same underlying interface. It is also technically possible for the said RConnection objects to be on the same socket server session, though this may be somewhat redundant.
Rather like RSocket / RHostResolver objects, an individual RConnection object is not designed to be used by multiple clients simultaneously (i.e. have multiple requests outstanding on it from different clients).
Although RConnection objects are automatically closed when the corresponding socket server session is closed, appropriate use of CleanupClosePushL(RConnection&) is more likely to ensure proper operation.
RSocket and RHostResolver objects can be associated with an RConnection object. In this case, data will flow over the same underlying interface as the RConnection to which they have been associated. For this to work, the RSocket/RHostResolver/RConnection objects must all be on the same socket server session, and the RConnection object must have been previously opened and active (i.e. associated with an underlying interface).
RConnection provides clients with the following functionality:
Opening and closing the connection
Starting a connection, which means associating it with a new underlying interface
Attaching the RConnection instance to an existing interface
Stopping the connection, which means disassociating it from the underlying interface
Obtaining progress information and notification during connection start-up
This is useful because the process of dialling an ISP, logging in and starting network protocols can be quite lengthy, taking up to a minute in some cases. In addition, the application can get the last error which occurred in setting up the connection.
Notifying when subconnections come up and go down
Notifying when there is a service change for the connection
Notifying when a given amount of data has been sent or received on a connection or subconnection
Reading CommDB fields specific to an active connection
Collecting statistical information on the network connection and subconnections. A UI component can display the collected statistical information in order to allow the user to examine the status of connections. The information that can be gathered is the following:
All available internet access point names and internet access point 'friendly' names as appropriate for each network (GPRS/UMTS) connection
Enumerating the currently active connections and subconnections
The current status of all network connections e.g. active/suspended
The amount of data (in bytes) transferred uplink and downlink by the network connection and subconnections
The amount of time each network connection has been active (in seconds)
The current status of the connection and subconnections with respect to data transfer, i.e. active/inactive
The Quality of Service profile associated with each Packet Data Protocol (GPRS/UMTS) context, e.g. low/medium/high
Copyright ©2010 Nokia Corporation and/or its subsidiary(-ies).
All rights
reserved. Unless otherwise stated, these materials are provided under the terms of the Eclipse Public License
v1.0.