QNetworkSession Class
The QNetworkSession class provides control over the system's access points and enables session management for cases when multiple clients access the same access point. More...
| Header: | #include <QNetworkSession> |
| qmake: | QT += network |
| Since: | Qt 4.7 |
| Inherits: | QObject |
This class is obsolete. It is provided to keep old source code working. We strongly advise against using it in new code.
This class was introduced in Qt 4.7.
Public Types
| enum | SessionError { UnknownSessionError, SessionAbortedError, RoamingError, OperationNotSupportedError, InvalidConfigurationError } |
| enum | State { Invalid, NotAvailable, Connecting, Connected, Closing, …, Roaming } |
| enum | UsagePolicy { NoPolicy, NoBackgroundTrafficPolicy } |
Detailed Description
A QNetworkSession enables control over the system's network interfaces. The session's configuration parameter are determined via the QNetworkConfiguration object to which it is bound. Depending on the type of the session (single access point or service network) a session may be linked to one or more network interfaces. By means of opening and closing of network sessions a developer can start and stop the systems network interfaces. If the configuration represents multiple access points (see QNetworkConfiguration::ServiceNetwork) more advanced features such as roaming may be supported.
QNetworkSession supports session management within the same process and depending on the platform's capabilities may support out-of-process sessions. If the same network configuration is used by multiple open sessions the underlying network interface is only terminated once the last session has been closed.
Roaming
Applications may connect to the preferredConfigurationChanged() signal in order to receive notifications when a more suitable access point becomes available. In response to this signal the application must either initiate the roaming via migrate() or ignore() the new access point. Once the session has roamed the newConfigurationActivated() signal is emitted. The application may now test the carrier and must either accept() or reject() it. The session will return to the previous access point if the roaming was rejected. The subsequent state diagram depicts the required state transitions.
Some platforms may distinguish forced roaming and application level roaming (ALR). ALR implies that the application controls (via migrate(), ignore(), accept() and reject()) whether a network session can roam from one access point to the next. Such control is useful if the application maintains stateful socket connections and wants to control the transition from one interface to the next. Forced roaming implies that the system automatically roams to the next network without consulting the application. This has the advantage that the application can make use of roaming features without actually being aware of it. It is expected that the application detects that the underlying socket is broken and automatically reconnects via the new network link.
If the platform supports both modes of roaming, an application indicates its preference by connecting to the preferredConfigurationChanged() signal. Connecting to this signal means that the application wants to take control over the roaming behavior and therefore implies application level roaming. If the client does not connect to the preferredConfigurationChanged(), forced roaming is used. If forced roaming is not supported the network session will not roam by default.
Some applications may want to suppress any form of roaming altogether. Possible use cases may be high priority downloads or remote services which cannot handle a roaming enabled client. Clients can suppress roaming by connecting to the preferredConfigurationChanged() signal and answer each signal emission with ignore().
See also QNetworkConfiguration and QNetworkConfigurationManager.
Member Type Documentation
enum QNetworkSession::SessionError
This enum describes the session errors that can occur.
| Constant | Value | Description |
|---|---|---|
QNetworkSession::UnknownSessionError | 0 | An unidentified error occurred. |
QNetworkSession::SessionAbortedError | 1 | The session was aborted by the user or system. |
QNetworkSession::RoamingError | 2 | The session cannot roam to a new configuration. |
QNetworkSession::OperationNotSupportedError | 3 | The operation is not supported for current configuration. |
QNetworkSession::InvalidConfigurationError | 4 | The operation cannot currently be performed for the current configuration. |
enum QNetworkSession::State
This enum describes the connectivity state of the session. If the session is based on a single access point configuration the state of the session is the same as the state of the associated network interface.
| Constant | Value | Description |
|---|---|---|
QNetworkSession::Invalid | 0 | The session is invalid due to an invalid configuration. This may happen due to a removed access point or a configuration that was invalid to begin with. |
QNetworkSession::NotAvailable | 1 | The session is based on a defined but not yet discovered QNetworkConfiguration (see QNetworkConfiguration::StateFlag). |
QNetworkSession::Connecting | 2 | The network session is being established. |
QNetworkSession::Connected | 3 | The network session is connected. If the current process wishes to use this session it has to register its interest by calling open(). A network session is considered to be ready for socket operations if it isOpen() and connected. |
QNetworkSession::Closing | 4 | The network session is in the process of being shut down. |
QNetworkSession::Disconnected | 5 | The network session is not connected. The associated QNetworkConfiguration has the state QNetworkConfiguration::Discovered. |
QNetworkSession::Roaming | 6 | The network session is roaming from one access point to another access point. |
enum QNetworkSession::UsagePolicy
These flags allow the system to inform the application of network usage restrictions that may be in place.
| Constant | Value | Description |
|---|---|---|
QNetworkSession::NoPolicy | 0 | No policy in force, usage is unrestricted. |
QNetworkSession::NoBackgroundTrafficPolicy | 1 | Background network traffic (not user initiated) should be avoided for example to save battery or data charges |
This enum was introduced or modified in Qt 5.0.