QNetworkInformation Class

QNetworkInformation exposes various network information through native backends. More...

Header: #include <QNetworkInformation>
CMake: find_package(Qt6 REQUIRED COMPONENTS Network)
target_link_libraries(mytarget PRIVATE Qt6::Network)
qmake: QT += network
Since: Qt 6.1
Inherits: QObject

Public Types

enum class Feature { Reachability, CaptivePortal, TransportMedium, Metered }
flags Features
enum class Reachability { Unknown, Disconnected, Local, Site, Online }
(since 6.3) enum class TransportMedium { Unknown, Ethernet, Cellular, WiFi, Bluetooth }

Properties

Public Functions

QString backendName() const
bool isBehindCaptivePortal() const
bool isMetered() const
QNetworkInformation::Reachability reachability() const
(since 6.3) QNetworkInformation::Features supportedFeatures() const
bool supports(QNetworkInformation::Features features) const
QNetworkInformation::TransportMedium transportMedium() const

Signals

void isBehindCaptivePortalChanged(bool state)
void isMeteredChanged(bool isMetered)
void reachabilityChanged(QNetworkInformation::Reachability newReachability)
void transportMediumChanged(QNetworkInformation::TransportMedium current)

Static Public Members

QStringList availableBackends()
QNetworkInformation *instance()
(since 6.4) bool loadBackendByFeatures(QNetworkInformation::Features features)
(since 6.4) bool loadBackendByName(QStringView backend)
(since 6.3) bool loadDefaultBackend()

Detailed Description

QNetworkInformation provides a cross-platform interface to network-related information through plugins.

Various plugins can have various functionality supported, and so you can load() plugins based on which features are needed.

QNetworkInformation is a singleton and stays alive from the first successful load() until destruction of the QCoreApplication object. If you destroy and re-create the QCoreApplication object you must call load() again.

See also QNetworkInformation::Feature.

Member Type Documentation

enum class QNetworkInformation::Feature
flags QNetworkInformation::Features

Lists all of the features that a plugin may currently support. This can be used in QNetworkInformation::load().

ConstantValueDescription
QNetworkInformation::Feature::Reachability0x1If the plugin supports this feature then the reachability property will provide useful results. Otherwise it will always return Reachability::Unknown. See also QNetworkInformation::Reachability.
QNetworkInformation::Feature::CaptivePortal0x2If the plugin supports this feature then the isBehindCaptivePortal property will provide useful results. Otherwise it will always return false.
QNetworkInformation::Feature::TransportMedium0x4If the plugin supports this feature then the transportMedium property will provide useful results. Otherwise it will always return TransportMedium::Unknown. See also QNetworkInformation::TransportMedium.
QNetworkInformation::Feature::Metered0x8If the plugin supports this feature then the isMetered property will provide useful results. Otherwise it will always return false.

The Features type is a typedef for QFlags<Feature>. It stores an OR combination of Feature values.

enum class QNetworkInformation::Reachability

ConstantValueDescription
QNetworkInformation::Reachability::Unknown0If this value is returned then we may be connected but the OS has still not confirmed full connectivity, or this feature is not supported.
QNetworkInformation::Reachability::Disconnected1Indicates that the system may have no connectivity at all.
QNetworkInformation::Reachability::Local2Indicates that the system is connected to a network, but it might only be able to access devices on the local network.
QNetworkInformation::Reachability::Site3Indicates that the system is connected to a network, but it might only be able to access devices on the local subnet or an intranet.
QNetworkInformation::Reachability::Online4Indicates that the system is connected to a network and able to access the Internet.

See also QNetworkInformation::reachability.

[since 6.3] enum class QNetworkInformation::TransportMedium

Lists the currently recognized media with which one can connect to the internet.

ConstantValueDescription
QNetworkInformation::TransportMedium::Unknown0Returned if either the OS reports no active medium, the active medium is not recognized by Qt, or the TransportMedium feature is not supported.
QNetworkInformation::TransportMedium::Ethernet1Indicates that the currently active connection is using ethernet. Note: This value may also be returned when Windows is connected to a Bluetooth personal area network.
QNetworkInformation::TransportMedium::Cellular2Indicates that the currently active connection is using a cellular network.
QNetworkInformation::TransportMedium::WiFi3Indicates that the currently active connection is using Wi-Fi.
QNetworkInformation::TransportMedium::Bluetooth4Indicates that the currently active connection is connected using Bluetooth.

This enum was introduced in Qt 6.3.

See also QNetworkInformation::transportMedium.

Property Documentation

[read-only, since 6.2] isBehindCaptivePortal : const bool

Lets you know if the user's device is behind a captive portal.

This property indicates if the user's device is currently known to be behind a captive portal. This functionality relies on the operating system's detection of captive portals and is not supported on systems that don't report this. On systems where this is not supported this will always return false.

This property was introduced in Qt 6.2.

Access functions:

bool isBehindCaptivePortal() const

Notifier signal:

void isBehindCaptivePortalChanged(bool state)

[read-only, since 6.3] isMetered : const bool

Check if the current connection is metered

This property returns whether the current connection is (known to be) metered or not. You can use this as a guiding factor to decide whether your application should perform certain network requests or uploads. For instance, you may not want to upload logs or diagnostics while this property is true.

This property was introduced in Qt 6.3.

Access functions:

bool isMetered() const

Notifier signal:

void isMeteredChanged(bool isMetered)

[read-only] reachability : const Reachability

This property holds the current state of the system's network connectivity.

Indicates the level of connectivity that can be expected. Do note that this is only based on what the plugin/operating system reports. In certain scenarios this is known to be wrong. For example, on Windows the 'Online' check, by default, is performed by Windows connecting to a Microsoft-owned server. If this server is for any reason blocked then it will assume it does not have Online reachability. Because of this you should not use this as a pre-check before attempting to make a connection.

Access functions:

QNetworkInformation::Reachability reachability() const

Notifier signal:

void reachabilityChanged(QNetworkInformation::Reachability newReachability)

[read-only, since 6.3] transportMedium : const TransportMedium

This property holds the currently active transport medium for the application

This property returns the currently active transport medium for the application, on operating systems where such information is available.

When the current transport medium changes a signal is emitted, this can, for instance, occur when a user leaves the range of a WiFi network, unplugs their ethernet cable or enables Airplane mode.

This property was introduced in Qt 6.3.

Access functions:

QNetworkInformation::TransportMedium transportMedium() const

Notifier signal:

void transportMediumChanged(QNetworkInformation::TransportMedium current)

Member Function Documentation

[static] QStringList QNetworkInformation::availableBackends()

Returns a list of the names of all currently available backends.

QString QNetworkInformation::backendName() const

Returns the name of the currently loaded backend.

[static] QNetworkInformation *QNetworkInformation::instance()

Returns a pointer to the instance of the QNetworkInformation, if any.

See also load().

[static, since 6.4] bool QNetworkInformation::loadBackendByFeatures(QNetworkInformation::Features features)

Load a backend which supports features.

Returns true if it managed to load the requested backend or if it was already loaded. Returns false otherwise.

This function was introduced in Qt 6.4.

See also instance.

[static, since 6.4] bool QNetworkInformation::loadBackendByName(QStringView backend)

Attempts to load a backend whose name matches backend (case insensitively).

Returns true if it managed to load the requested backend or if it was already loaded. Returns false otherwise.

This function was introduced in Qt 6.4.

See also instance.

[static, since 6.3] bool QNetworkInformation::loadDefaultBackend()

Attempts to load the platform-default backend.

Note: Starting with 6.7 this tries to load any backend that supports Reachability if the platform-default backend is not available or fails to load. If this also fails it will fall back to a backend that only returns the default values for all properties.

This platform-to-plugin mapping is as follows:

PlatformPlugin-name
Windowsnetworklistmanager
Apple (macOS/iOS)scnetworkreachability
Androidandroid
Linuxnetworkmanager

This function is provided for convenience where the logic earlier is good enough. If you require a specific plugin then you should call loadBackendByName() or loadBackendByFeatures() directly instead.

Determines a suitable backend to load and returns true if this backend is already loaded or on successful loading of it. Returns false if any other backend has already been loaded, or if loading of the selected backend fails.

This function was introduced in Qt 6.3.

See also instance() and load().

[since 6.3] QNetworkInformation::Features QNetworkInformation::supportedFeatures() const

Returns all the supported features of the current backend.

This function was introduced in Qt 6.3.

bool QNetworkInformation::supports(QNetworkInformation::Features features) const

Returns true if the currently loaded backend supports features.

© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.