doc/src/network/network-programming/bearermanagement.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: Nokia Corporation (qt-info@nokia.com)
   6 **
   7 ** This file is part of the documentation of the Qt Toolkit.
   8 **
   9 ** $QT_BEGIN_LICENSE:FDL$
  10 ** GNU Free Documentation License
  11 ** Alternatively, this file may be used under the terms of the GNU Free
  12 ** Documentation License version 1.3 as published by the Free Software
  13 ** Foundation and appearing in the file included in the packaging of
  14 ** this file.
  15 **
  16 ** Other Usage
  17 ** Alternatively, this file may be used in accordance with the terms
  18 ** and conditions contained in a signed written agreement between you
  19 ** and Nokia.
  20 **
  21 **
  22 **
  23 **
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29 \page bearer-management.html
  30
  31 \title Bearer Management
  32 \ingroup qt-network
  33 \brief An API to control the system's connectivity state.
  34
  35 Bearer Management controls the connectivity state of the system so that
  36 the user can start or stop interfaces or roam transparently between
  37 access points.
  38
  39 \tableofcontents
  40
  41
  42 \section1 Overview
  43
  44 The Bearer Management API controls the system's connectivity state. This
  45 incorporates simple information such as whether the device is online and
  46 how many interfaces there are as well as enables the application developer
  47 to start, stop network interfaces and influences other connection specific
  48 details. Depending on the platform's capabilities it may even provide
  49 session management so that a network interface remains up for as long as
  50 clients have a registered interest in them while at the same time
  51 optimizes the interface's uptime.
  52
  53 This API does not provide support for management of network configurations
  54 themselves. It is up to the platform to provide infrastructure which
  55 enables to user to create, edit or delete network configurations.
  56
  57 \section2 The API in Detail
  58
  59 Computer systems manage their network interfaces via a set of configurations.
  60 Each configuration describes a set of parameters which instruct the system
  61 how a particular network interface is started. One of the most simplistic
  62 examples might be an Ethernet configuration that links a network card to a
  63 DHCP server. A more complex example might be a Wireless LAN configuration
  64 which may comprise of hardware details such as the WLAN card address,
  65 WLAN access point details (e.g ESSID, encryption details) and user specific
  66 information (for example username and password). Once the network interface
  67 was configured and started according to the configuration blue print,
  68 multiple applications are free to use this link layer connection/session
  69 for their own socket operations. Note that the QNetworkConfiguration object
  70 only provides limited information about the configuration details themselves.
  71 It's main purpose is to act as a configuration identifier through which link
  72 layer connections can be created, destroyed and monitored.
  73
  74 QNetworkSession provides two types of use cases. It enables the monitoring of
  75 physical network interfaces and management of network sessions. Network sessions
  76 are a common feature on mobile devices where multiple applications
  77 can request network sessions as they see fit. The system consolidates and tracks
  78 active network sessions for the same network interface by maintaining the link
  79 layer connections until the last session has been closed. The subsequent table
  80 lists the major QNetworkSession functions and how they fit into the session and
  81 hardware management categories:
  82
  83 \table 60%
  84 \header \o Interface management             \o Session management
  85 \row    \o QNetworkSession::stop()          \o QNetworkSession::open()
  86 \row    \o QNetworkSession::interface()     \o QNetworkSession::close()
  87 \row    \o QNetworkSession::state()         \o QNetworkSession::isOpen()
  88 \row    \o QNetworkSession::bytesWritten()  \o QNetworkSession::migrate()
  89 \row    \o QNetworkSession::bytesReceived() \o QNetworkSession::ignore()
  90 \row    \o QNetworkSession::activeTime()    \o QNetworkSession::accept()
  91 \row    \o QNetworkSession::stateChanged()  \o QNetworkSession::reject()
  92 \row    \o                                  \o QNetworkSession::opened()
  93 \row    \o                                  \o QNetworkSession::closed()
  94 \endtable
  95
  96 The state of the session represents the state of the underlying access point
  97 whereas the session's openness implies the networking/connectivity state available
  98 to the current process.
  99
 100 Possible use cases for interface management are network management related
 101 applications which intend to monitor the connectivity state but do not engage
 102 in network communication themselves. Any application wanting to open a socket
 103 to a remote address will typically use session management related functionality.
 104
 105 \section3 Service networks
 106
 107 Some mobile platforms use the concept of grouped access points (also
 108 called SNAP or Service Network Access Point). In principle multiple
 109 configurations are grouped together and possibly even prioritized when
 110 compared to each other. This is useful for use cases where all
 111 configurations serve a similar purpose or context. A common context could
 112 be that they provide access to the public Internet or possibly only to the
 113 office Intranet. By providing a pool of configurations the system can make
 114 a decision based on given priorities which usually map to factors such as
 115 speed, availability and cost. Furthermore the system can automatically
 116 roam from one access point to the next one while ensuring minimal impact on
 117 the user experience.
 118
 119 The \l{QNetworkConfiguration::Type} flag specifies to what category a
 120 configuration belongs. The \l{QNetworkConfiguration::InternetAccessPoint}
 121 type is the most common example. It represents a configuration that can be
 122 used to create a session. The above mentioned grouping behavior is provided
 123 by \l {QNetworkConfiguration::ServiceNetwork} configurations. Service
 124 networks are place holders until such time when the user attempts to
 125 \l {QNetworkSession::open()}{open()} a new session. At that point in time
 126 the system determines which of the configurations \l{QNetworkConfiguration::children()}
 127 is best to use. The selection algorithm is provided by the platform and is usually managed
 128 by network settings applications. A service network can only have one level of indirection
 129 which implies children can only be of type \l {QNetworkConfiguration::InternetAccessPoint}.
 130
 131 Most systems allow the user to define the systems default configuration.
 132 Usually the default behavior is either a service network, a particular
 133 Internet access point or the user instructs the platform to ask the user
 134 once an application requests the network. User interaction is generally
 135 implemented by some sort of system dialog which shows up at the appropriate
 136 point in time. The application does not have to handle the user input. This
 137 API provides the \l QNetworkConfigurationManager::defaultConfiguration()
 138 call which serves a similar purpose. The subsequent code snippet provides
 139 a quick way how an application can quickly create a new network session
 140 without (or only minimal) user interaction:
 141
 142 \code
 143     // Set Internet Access Point
 144     QNetworkConfigurationManager manager;
 145     const bool canStartIAP = (manager.capabilities()
 146                               & QNetworkConfigurationManager::CanStartAndStopInterfaces);
 147     // Is there default access point, use it
 148     QNetworkConfiguration cfg = manager.defaultConfiguration();
 149     if (!cfg.isValid() || (!canStartIAP && cfg.state() != QNetworkConfiguration::Active)) {
 150         QMessageBox::information(this, tr("Network"), tr(
 151                                      "No Access Point found."));
 152         return;
 153     }
 154
 155     session = new QNetworkSession(cfg, this);
 156     session->open();
 157     session->waitForOpened(-1);
 158 \endcode
 159
 160 To accommodate the "Ask user" use case the default configuration can be of
 161 type QNetworkConfiguration::UserChoice. A user choice configuration is
 162 resolved as part of the \l {QNetworkSession::open()} call. Note that a
 163 \l{QNetworkConfiguration::UserChoice}{UserChoice} configuration is only
 164 ever returned via \l {QNetworkConfigurationManager::defaultConfiguration()}
 165 and not \l QNetworkConfigurationManager::allConfigurations().
 166
 167 On systems which do not maintain a list of
 168 \l {QNetworkConfigurationManager::defaultConfiguration()}{defaultConfiguration()}
 169 an invalid configuration is returned. A possible workaround could be to
 170 implement a custom dialog which is populated based on what
 171 \l QNetworkConfigurationManager::allConfigurations() returns.
 172
 173 \section3 Managing network sessions
 174
 175 A QNetworkSession object separates a \l {QNetworkSession::state()}{state()}
 176 and an \l{QNetworkSession::isOpen()}{isOpen()} condition.
 177
 178 The state() attribute enables developers to detect whether the system
 179 currently maintains a global network session for the given
 180 QNetworkConfiguration. If \l {QNetworkSession::isOpen()}{isOpen()}
 181 returns true the QNetworkSession instance at hand was at least one of the
 182 entities requesting the global network session. This distinction is
 183 required to support the notion of session registrations. For as long as
 184 there are one or more open QNetworkSession instances the underlying
 185 network interface is not shut down. Therefore the session
 186 \l{QNetworkSession::state()}{state()} can be used to monitor the state of
 187 network interfaces.
 188
 189 An open session is created by calling \l {QNetworkSession::open()} and
 190 closed via \l{QNetworkSession::close()}, respectively. If the session
 191 is \l{QNetworkSession::Disconnected}{disconnected} at the time of the
 192 \l{QNetworkSession::open()}{open()} call the underlying interface is started;
 193 otherwise only the reference counter against the global session is
 194 incremented. The opposite behavior can be observed when using
 195 \l{QNetworkSession::close()}{close()}.
 196
 197 In some use cases it may be necessary to turn the interface off despite of
 198 open sessions. This can be achieved by calling
 199 \l{QNetworkSession::stop()}{stop()}. An example use case could be a
 200 network manager type of application allowing the user to control the
 201 overall state of the devices connectivity.
 202
 203 Global (inter-process) session support is platform dependent and can be
 204 detected via \l {QNetworkConfigurationManager::SystemSessionSupport}.
 205 If the system does not support global session calling
 206 \l{QNetworkSession::close()}{close()} never stops the interface.
 207
 208 \section3 Roaming
 209
 210 Roaming is the process of reconnecting a device from one network to another
 211 while minimizing the impact on the application. The system notifies the application
 212 about link layer changes so that the required preparation can be taken.
 213 The most common reaction would be to reinitialize sockets and to renegotiate
 214 stateful connections with other parties. In the most extreme cases applications
 215 may even prevent the roaming altogether.
 216
 217 Roaming is initiated when the system determines that a more appropriate access point
 218 becomes available to the user. In general such a decision is based on cost, network speed
 219 or network type (access to certain private networks may only be provided via certain access points).
 220 Almost all devices providing roaming support have some form of global configuration application
 221 enabling the user to define such groups of access points (service networks) and priorities.
 222
 223 This API supports two types of roaming. Application level roaming (ALR)
 224 provides the most control over the process. Applications will be notified about upcoming
 225 link layer changes and get the opportunity to test the new access point. Eventually they can
 226 reject or accept the link layer change. The second form of roaming is referred to as Forced Roaming.
 227 The system simply changes the link layer without consulting the application. It is up to
 228 the application to detect that some of its internal socket may have become invalid. As a consequence
 229 it has to reinitialize those sockets and reestablish the previous user session without
 230 any interruption. Forced roaming has the advantage that applications don't have to
 231 manage the entire roaming process by themselves.
 232
 233 QNetworkSession is the central class for managing roaming related issues.
 234
 235 \section3 Platform capabilities
 236
 237 Some API features are not available on all platforms. The
 238 \l QNetworkConfigurationManager::Capability should be used to detect
 239 platform features at runtime. The following table lists the various
 240 platform APIs being used by this API. This may assist in the process of
 241 determining the feature support:
 242
 243 \table
 244     \header
 245     \o Platform
 246     \o Backend capabilities
 247     \row
 248         \o Linux\unicode{0xAE}
 249         \o Linux uses the \l {http://projects.gnome.org/NetworkManager}{NetworkManager API} which supports interface notifications and starting and stopping of network interfaces.
 250     \row
 251         \o Windows\unicode{0xAE} XP
 252         \o This platform supports interface notifications without active polling.
 253     \row
 254         \o Windows XP SP2+Hotfixes, Windows XP SP3, Windows Vista, Windows 7
 255         \o In addition to standard Windows XP wifi access point monitoring has been improved which includes the ability to start and stop wifi interfaces. This requires Windows to manage the wifi interfaces.
 256     \row
 257         \o Symbian\unicode{0xAE}  Platform & S60 3.1
 258         \o Symbian support is based on Symbian platforms RConnection. In addition to interface notifications, starting and stopping of network it provides system wide session support and direct connection routing.
 259     \row
 260         \o Symbian Platform & S60 3.2+
 261         \o This platform enjoys the most comprehensive feature set. In addition to the features support by the S60 3.1 Network roaming is supported.
 262     \row
 263         \o Mac OS\unicode{0xAE}
 264         \o This platform has full support by way of CoreWLAN offered in Mac OS 10.6. Previous
 265            versions of Mac OS - 10.5 and 10.4 have limited support.
 266     \row
 267         \o All other platforms (*nix, Windows Mobile)
 268         \o This backend is the fallback for all platforms supports network interface notifications via active polling only.
 269 \endtable
 270
 271 */