/*!
Returns \c true if the system is considered to be connected to another device via an active
network interface; otherwise returns \c false.
This is equivalent to the following code snippet:
\snippet code/src_network_bearer_qnetworkconfigmanager.cpp 0
\sa onlineStateChanged()
*/
bool QNetworkConfigurationManager::isOnline() const
{
QNetworkConfigurationManagerPrivate *priv = qNetworkConfigurationManagerPrivate();
if (priv)
return priv->isOnline();
return false;
}
/*!
Returns the capabilities supported by the current platform.
*/
QNetworkConfigurationManager::Capabilities QNetworkConfigurationManager::capabilities() const
{
QNetworkConfigurationManagerPrivate *priv = qNetworkConfigurationManagerPrivate();
if (priv)
return priv->capabilities();
return QNetworkConfigurationManager::Capabilities(0);
}
/*!
Returns the QNetworkConfiguration for \a identifier; otherwise returns an
invalid QNetworkConfiguration.
\sa QNetworkConfiguration::identifier()
*/
QNetworkConfiguration QNetworkConfigurationManager::configurationFromIdentifier(const QString &identifier) const
{
QNetworkConfigurationManagerPrivate *priv = qNetworkConfigurationManagerPrivate();
if (priv)
return priv->configurationFromIdentifier(identifier);
return QNetworkConfiguration();
}
/*!
Returns the list of configurations which comply with the given \a filter.
By default this function returns all (defined and undefined) configurations.
A wireless network with a particular SSID may only be accessible in a
certain area despite the fact that the system has a valid configuration
for it. Therefore the filter flag may be used to limit the list to
discovered and possibly connected configurations only.
If \a filter is set to zero this function returns all possible configurations.
Note that this function returns the states for all configurations as they are known at
the time of this function call. If for instance a configuration of type WLAN is defined
the system may have to perform a WLAN scan in order to determine whether it is
actually available. To obtain the most accurate state updateConfigurations() should
be used to update each configuration's state. Note that such an update may require
some time. It's completion is signalled by updateCompleted(). In the absence of a
configuration update this function returns the best estimate at the time of the call.
Therefore, if WLAN configurations are of interest, it is recommended that
updateConfigurations() is called once after QNetworkConfigurationManager
instantiation (WLAN scans are too time consuming to perform in constructor).
After this the data is kept automatically up-to-date as the system reports
any changes.
*/
QList<QNetworkConfiguration> QNetworkConfigurationManager::allConfigurations(QNetworkConfiguration::StateFlags filter) const
{
QNetworkConfigurationManagerPrivate *priv = qNetworkConfigurationManagerPrivate();
if (priv)
return priv->allConfigurations(filter);
return QList<QNetworkConfiguration>();
}
/*!
Returns the default configuration to be used. This function always returns a discovered
configuration; otherwise an invalid configuration.
In some cases it may be required to call updateConfigurations() and wait for the
updateCompleted() signal before calling this function.
\sa allConfigurations()
*/
QNetworkConfiguration QNetworkConfigurationManager::defaultConfiguration() const
{
QNetworkConfigurationManagerPrivate *priv = qNetworkConfigurationManagerPrivate();
if (priv)
return priv->defaultConfiguration();
return QNetworkConfiguration();
}
/*!
Constructs a QNetworkConfigurationManager with the given \a parent.
*/
QNetworkConfigurationManager::QNetworkConfigurationManager( QObject* parent )
: QObject(parent)
{
QNetworkConfigurationManagerPrivate *priv = qNetworkConfigurationManagerPrivate();
connect(priv, SIGNAL(configurationAdded(QNetworkConfiguration)),
this, SIGNAL(configurationAdded(QNetworkConfiguration)));
connect(priv, SIGNAL(configurationRemoved(QNetworkConfiguration)),
this, SIGNAL(configurationRemoved(QNetworkConfiguration)));
connect(priv, SIGNAL(configurationUpdateComplete()),
this, SIGNAL(updateCompleted()));
connect(priv, SIGNAL(onlineStateChanged(bool)),
this, SIGNAL(onlineStateChanged(bool)));
connect(priv, SIGNAL(configurationChanged(QNetworkConfiguration)),
this, SIGNAL(configurationChanged(QNetworkConfiguration)));
priv->enablePolling();
}
/*!
Initiates an update of all configurations. This may be used to initiate WLAN scans or other
time consuming updates which may be required to obtain the correct state for configurations.
This call is asynchronous. On completion of this update the updateCompleted() signal is
emitted. If new configurations are discovered or old ones were removed or changed the update
process may trigger the emission of one or multiple configurationAdded(),
configurationRemoved() and configurationChanged() signals.
If a configuration state changes as a result of this update all existing QNetworkConfiguration
instances are updated automatically.
\sa allConfigurations()
*/
void QNetworkConfigurationManager::updateConfigurations()
{
QNetworkConfigurationManagerPrivate *priv = qNetworkConfigurationManagerPrivate();
if (priv)
priv->performAsyncConfigurationUpdate();
}
/*!
Frees the resources associated with the QNetworkConfigurationManager object.
*/
QNetworkConfigurationManager::~QNetworkConfigurationManager()
{
QNetworkConfigurationManagerPrivate *priv = qNetworkConfigurationManagerPrivate();
if (priv)
priv->disablePolling();
}
QT_BEGIN_NAMESPACE
/*!
\class QNetworkSession
\brief 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.
\since 4.7
\inmodule QtNetwork
\ingroup network
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 \l{open()}{opening} and \l{close()}{closing} of network sessions
a developer can start and stop the systems network interfaces. If the configuration represents
multiple access points (see \l 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.
\section1 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.
\image roaming-states.png
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().
\sa QNetworkConfiguration, QNetworkConfigurationManager
*/
/*!
\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.
\value Invalid 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.
\value NotAvailable The session is based on a defined but not yet discovered QNetworkConfiguration
(see \l QNetworkConfiguration::StateFlag).
\value Connecting The network session is being established.
\value Connected 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.
\value Closing The network session is in the process of being shut down.
\value Disconnected The network session is not connected. The associated QNetworkConfiguration
has the state QNetworkConfiguration::Discovered.
\value Roaming The network session is roaming from one access point to another
access point.
*/
/*!
\enum QNetworkSession::SessionError
This enum describes the session errors that can occur.
\value UnknownSessionError An unidentified error occurred.
\value SessionAbortedError The session was aborted by the user or system.
\value RoamingError The session cannot roam to a new configuration.
\value OperationNotSupportedError The operation is not supported for current configuration.
\value InvalidConfigurationError The operation cannot currently be performed for the
current configuration.
*/
/*!
\fn void QNetworkSession::stateChanged(QNetworkSession::State state)
This signal is emitted whenever the state of the network session changes.
The \a state parameter is the new state.
\sa state()
*/
/*!
\fn void QNetworkSession::error(QNetworkSession::SessionError error)
This signal is emitted after an error occurred. The \a error parameter
describes the error that occurred.
\sa error(), errorString()
*/
/*!
\fn void QNetworkSession::preferredConfigurationChanged(const QNetworkConfiguration& config, bool isSeamless)
This signal is emitted when the preferred configuration/access point for the
session changes. Only sessions which are based on service network configurations
may emit this signal. \a config can be used to determine access point specific
details such as proxy settings and \a isSeamless indicates whether roaming will
break the sessions IP address.
As a consequence to this signal the application must either start the roaming process
by calling migrate() or choose to ignore() the new access point.
If the roaming process is non-seamless the IP address will change which means that
a socket becomes invalid. However seamless mobility can ensure that the local IP address
does not change. This is achieved by using a virtual IP address which is bound to the actual
link address. During the roaming process the virtual address is attached to the new link
address.
Some platforms may support the concept of Forced Roaming and Application Level Roaming (ALR).
Forced roaming implies that the platform may simply roam to a new configuration without
consulting applications. It is up to the application to detect the link layer loss and reestablish
its sockets. In contrast ALR provides the opportunity to prevent the system from roaming.
If this session is based on a configuration that supports roaming the application can choose
whether it wants to be consulted (ALR use case) by connecting to this signal. For as long as this signal
connection remains the session remains registered as a roaming stakeholder; otherwise roaming will
be enforced by the platform.
\sa migrate(), ignore(), QNetworkConfiguration::isRoamingAvailable()
*/
/*!
\fn void QNetworkSession::newConfigurationActivated()
This signal is emitted once the session has roamed to the new access point.
The application may reopen its socket and test the suitability of the new network link.
Subsequently it must either accept() or reject() the new access point.
\sa accept(), reject()
*/
/*!
\fn void QNetworkSession::opened()
This signal is emitted when the network session has been opened.
The underlying network interface will not be shut down as long as the session remains open.
Note that this feature is dependent on \l{QNetworkConfigurationManager::SystemSessionSupport}{system wide session support}.
*/
/*!
\fn void QNetworkSession::closed()
This signal is emitted when the network session has been closed.
*/
/*!
Constructs a session based on \a connectionConfig with the given \a parent.
\sa QNetworkConfiguration
*/
QNetworkSession::QNetworkSession(const QNetworkConfiguration& connectionConfig, QObject* parent)
: QObject(parent), d(0)
{
foreach (QBearerEngine *engine, qNetworkConfigurationManagerPrivate()->engines()) {
if (engine->hasIdentifier(connectionConfig.identifier())) {
d = engine->createSessionBackend();
d->q = this;
d->publicConfig = connectionConfig;
d->syncStateWithInterface();
connect(d, SIGNAL(quitPendingWaitsForOpened()), this, SIGNAL(opened()));
connect(d, SIGNAL(error(QNetworkSession::SessionError)),
this, SIGNAL(error(QNetworkSession::SessionError)));
connect(d, SIGNAL(stateChanged(QNetworkSession::State)),
this, SIGNAL(stateChanged(QNetworkSession::State)));
connect(d, SIGNAL(closed()), this, SIGNAL(closed()));
connect(d, SIGNAL(preferredConfigurationChanged(QNetworkConfiguration,bool)),
this, SIGNAL(preferredConfigurationChanged(QNetworkConfiguration,bool)));
connect(d, SIGNAL(newConfigurationActivated()),
this, SIGNAL(newConfigurationActivated()));
break;
}
}