Bearer Management

Bearer Management controls the connectivity state of the system so that the user can start or stop interfaces or roam transparently between access points.

Overview

The Bearer Management API controls the system's connectivity state. This incorporates simple information such as whether the device is online and how many interfaces there are as well as enables the application developer to start, stop network interfaces and influences other connection specific details. Depending on the platform's capabilities it may even provide session management so that a network interface remains up for as long as clients have a registered interest in them while at the same time optimizes the interface's uptime.

This API does not provide support for management of network configurations themselves. It is up to the platform to provide infrastructure which enables to user to create, edit or delete network configurations.

The API in Detail

Computer systems manage their network interfaces via a set of configurations. Each configuration describes a set of parameters which instruct the system how a particular network interface is started. One of the most simplistic examples might be an Ethernet configuration that links a network card to a DHCP server. A more complex example might be a Wireless LAN configuration which may comprise of hardware details such as the WLAN card address, WLAN access point details (e.g ESSID, encryption details) and user specific information (for example username and password). Once the network interface was configured and started according to the configuration blue print, multiple applications are free to use this link layer connection/session for their own socket operations. Note that the QNetworkConfiguration object only provides limited information about the configuration details themselves. It's main purpose is to act as a configuration identifier through which link layer connections can be created, destroyed and monitored.

QNetworkSession provides two types of use cases. It enables the monitoring of physical network interfaces and management of network sessions. Network sessions are a common feature on mobile devices where multiple applications can request network sessions as they see fit. The system consolidates and tracks active network sessions for the same network interface by maintaining the link layer connections until the last session has been closed. The subsequent table lists the major QNetworkSession functions and how they fit into the session and hardware management categories:

Interface management	Session management
QNetworkSession::stop()	QNetworkSession::open()
QNetworkSession::interface()	QNetworkSession::close()
QNetworkSession::state()	QNetworkSession::isOpen()
QNetworkSession::bytesWritten()	QNetworkSession::migrate()
QNetworkSession::bytesReceived()	QNetworkSession::ignore()
QNetworkSession::activeTime()	QNetworkSession::accept()
QNetworkSession::stateChanged()	QNetworkSession::reject()
	QNetworkSession::opened()
	QNetworkSession::closed()

The state of the session represents the state of the underlying access point whereas the session's openness implies the networking/connectivity state available to the current process.

Possible use cases for interface management are network management related applications which intend to monitor the connectivity state but do not engage in network communication themselves. Any application wanting to open a socket to a remote address will typically use session management related functionality.

Service networks

Some mobile platforms use the concept of grouped access points (also called SNAP or Service Network Access Point). In principle multiple configurations are grouped together and possibly even prioritized when compared to each other. This is useful for use cases where all configurations serve a similar purpose or context. A common context could be that they provide access to the public Internet or possibly only to the office Intranet. By providing a pool of configurations the system can make a decision based on given priorities which usually map to factors such as speed, availability and cost. Furthermore the system can automatically roam from one access point to the next one while ensuring minimal impact on the user experience.

The QNetworkConfiguration::Type flag specifies to what category a configuration belongs. The QNetworkConfiguration::InternetAccessPoint type is the most common example. It represents a configuration that can be used to create a session. The above mentioned grouping behavior is provided by QNetworkConfiguration::ServiceNetwork configurations. Service networks are place holders until such time when the user attempts to open() a new session. At that point in time the system determines which of the configurations QNetworkConfiguration::children() is best to use. The selection algorithm is provided by the platform and is usually managed by network settings applications. A service network can only have one level of indirection which implies children can only be of type QNetworkConfiguration::InternetAccessPoint.

Most systems allow the user to define the systems default configuration. Usually the default behavior is either a service network, a particular Internet access point or the user instructs the platform to ask the user once an application requests the network. User interaction is generally implemented by some sort of system dialog which shows up at the appropriate point in time. The application does not have to handle the user input. This API provides the QNetworkConfigurationManager::defaultConfiguration() call which serves a similar purpose. The subsequent code snippet provides a quick way how an application can quickly create a new network session without (or only minimal) user interaction:

// Set Internet Access Point
QNetworkConfigurationManager manager;
const bool canStartIAP = (manager.capabilities()
                          & QNetworkConfigurationManager::CanStartAndStopInterfaces);
// Is there default access point, use it
QNetworkConfiguration cfg = manager.defaultConfiguration();
if (!cfg.isValid() || (!canStartIAP && cfg.state() != QNetworkConfiguration::Active)) {
    QMessageBox::information(this, tr("Network"), tr(
                                 "No Access Point found."));
    return;
}

session = new QNetworkSession(cfg, this);
session->open();
session->waitForOpened(-1);

To accommodate the "Ask user" use case the default configuration can be of type QNetworkConfiguration::UserChoice. A user choice configuration is resolved as part of the QNetworkSession::open() call. Note that a UserChoice configuration is only ever returned via QNetworkConfigurationManager::defaultConfiguration() and not QNetworkConfigurationManager::allConfigurations().

On systems which do not maintain a list of defaultConfiguration() an invalid configuration is returned. A possible workaround could be to implement a custom dialog which is populated based on what QNetworkConfigurationManager::allConfigurations() returns.

Managing network sessions

A QNetworkSession object separates a state() and an isOpen() condition.

The state() attribute enables developers to detect whether the system currently maintains a global network session for the given QNetworkConfiguration. If isOpen() returns true the QNetworkSession instance at hand was at least one of the entities requesting the global network session. This distinction is required to support the notion of session registrations. For as long as there are one or more open QNetworkSession instances the underlying network interface is not shut down. Therefore the session state() can be used to monitor the state of network interfaces.

An open session is created by calling QNetworkSession::open() and closed via QNetworkSession::close(), respectively. If the session is disconnected at the time of the open() call the underlying interface is started; otherwise only the reference counter against the global session is incremented. The opposite behavior can be observed when using close().

In some use cases it may be necessary to turn the interface off despite of open sessions. This can be achieved by calling stop(). An example use case could be a network manager type of application allowing the user to control the overall state of the devices connectivity.

Global (inter-process) session support is platform dependent and can be detected via QNetworkConfigurationManager::SystemSessionSupport. If the system does not support global session calling close() never stops the interface.

Roaming

Roaming is the process of reconnecting a device from one network to another while minimizing the impact on the application. The system notifies the application about link layer changes so that the required preparation can be taken. The most common reaction would be to reinitialize sockets and to renegotiate stateful connections with other parties. In the most extreme cases applications may even prevent the roaming altogether.

Roaming is initiated when the system determines that a more appropriate access point becomes available to the user. In general such a decision is based on cost, network speed or network type (access to certain private networks may only be provided via certain access points). Almost all devices providing roaming support have some form of global configuration application enabling the user to define such groups of access points (service networks) and priorities.

This API supports two types of roaming. Application level roaming (ALR) provides the most control over the process. Applications will be notified about upcoming link layer changes and get the opportunity to test the new access point. Eventually they can reject or accept the link layer change. The second form of roaming is referred to as Forced Roaming. The system simply changes the link layer without consulting the application. It is up to the application to detect that some of its internal socket may have become invalid. As a consequence it has to reinitialize those sockets and reestablish the previous user session without any interruption. Forced roaming has the advantage that applications don't have to manage the entire roaming process by themselves.

QNetworkSession is the central class for managing roaming related issues.

Platform capabilities

Some API features are not available on all platforms. The QNetworkConfigurationManager::Capability should be used to detect platform features at runtime.