Back to Qt.io
Contact Us Blog Download Qt

QNetworkInformation Class

QNetworkInformation stellt verschiedene Netzwerkinformationen über native Backends zur Verfügung. Mehr...

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

Öffentliche Typen

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 }

Eigenschaften

Öffentliche Funktionen

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

Signale

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

Statische öffentliche Mitglieder

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

Detaillierte Beschreibung

QNetworkInformation bietet eine plattformübergreifende Schnittstelle zu netzwerkbezogenen Informationen über Plugins.

Verschiedene Plugins können verschiedene Funktionen unterstützen, so dass Sie Plugins je nach den benötigten Funktionen laden können.

In den meisten Fällen ist es empfehlenswert, das plattformspezifische Backend durch den Aufruf von loadDefaultBackend() zu laden. Dadurch wird automatisch das am besten geeignete Backend ausgewählt, das auf der aktuellen Plattform verfügbar ist und für die meisten Anwendungen geeignet ist.

#include <QCoreApplication>#include <QNetworkInformation>#include <QDebug>void onReachabilityChanged(QNetworkInformation::Erreichbarkeit Erreichbarkeit) { switch (Erreichbarkeit) { case QNetworkInformation::Erreichbarkeit::Unbekannt:        qDebug() << "Network reachability is unknown.";
       break; case QNetworkInformation::Erreichbarkeit::Abgekoppelt:        qDebug() << "Network is disconnected.";
       break; case QNetworkInformation::Erreichbarkeit::Lokal:        qDebug() << "Network is locally reachable.";
       break; case QNetworkInformation::Erreichbarkeit::Standort:        qDebug() << "Network can reach the site.";
       break; case QNetworkInformation::Erreichbarkeit::Online:        qDebug() << "Network is online.";
       break; } }int main(int argc, char *argv[]) { QCoreApplication a(argc, argv); // Prüfen, ob QNetworkInformation unterstützt wird if (!QNetworkInformation::loadDefaultBackend()) {        qWarning() << "QNetworkInformation is not supported on this platform or backend.";
       return 1; } QNetworkInformation* netInfo = QNetworkInformation::instance(); // Verbindung mit dem Signal reachabilityChanged   QObject::connect(netInfo, &QNetworkInformation::reachabilityChanged, &onReachabilityChanged); // Ausgangsstatus ausgebenonReachabilityChanged(netInfo->reachability()); return a.exec(); }

Für fortgeschrittene Anwendungsfälle können Entwickler es vorziehen, ein Backend auf der Grundlage bestimmter Fähigkeiten oder Präferenzen zu laden. loadBackendByFeatures() erlaubt es, ein Backend auszuwählen, das einen bestimmten Satz von Funktionen unterstützt, wie z.B. die Meldung des Transportmediums oder der Signalstärke. Alternativ dazu ermöglicht loadBackendByName() das Laden eines Plugins anhand seines Namens, der plattformspezifische oder benutzerdefinierte Backend-Implementierungen enthalten kann.

QNetworkInformation ist ein Singleton und bleibt vom ersten erfolgreichen Laden bis zur Zerstörung des QCoreApplication Objekts aktiv. Wenn Sie das QCoreApplication Objekt zerstören und neu erstellen, müssen Sie es erneut laden, um das Plugin zu reinitialisieren.

Hinweis: Da die Klasse ein Singleton ist und gleichzeitig auf QCoreApplication basiert, sollte QNetworkInformation immer zuerst im selben Thread wie das QCoreApplication Objekt geladen werden. Dies liegt daran, dass das Objekt auch in diesem Thread zerstört wird und verschiedene Backend-spezifische Komponenten darauf angewiesen sein können, im selben Thread zerstört zu werden, in dem es erstellt wird.

Ein möglicher Anwendungsfall für QNetworkInformation ist die Überwachung des Netzwerkkonnektivitätsstatus. reachability() gibt einen Hinweis darauf, ob das System als online gilt, basierend auf Informationen, die vom zugrunde liegenden Betriebssystem oder Plugin gemeldet werden. Diese Informationen sind jedoch nicht immer genau. Wenn dieser Server nicht erreichbar ist (z. B. aufgrund von Firewall-Regeln), meldet das System möglicherweise fälschlicherweise, dass es offline ist. Daher sollte reachability() nicht als endgültige Vorprüfung vor dem Versuch einer Netzwerkverbindung verwendet werden, sondern eher als allgemeines Signal für den Verbindungsstatus.

Um reachability() effektiv zu nutzen, muss die Anwendung auch wissen, welche Art von Ziel sie zu erreichen versucht. Handelt es sich bei dem Ziel beispielsweise um eine lokale IP-Adresse, so kann Reachability::Local oder Reachability::Site ausreichend sein. Befindet sich das Ziel im öffentlichen Internet, dann ist Reachability::Online erforderlich. Ohne diesen Kontext kann die Interpretation der gemeldeten Erreichbarkeit zu falschen Annahmen über den tatsächlichen Netzzugang führen.

Warnung: Nur Linux und Windows bieten Unterstützung für die feiner abgestuften Optionen Reachability::Site und Reachability::Local. Auf Android- und Apple-Plattformen ist reachability() darauf beschränkt, nur Online, Offline oder Unbekannt zu melden. Daher muss jede Logik, die sich auf die Erkennung von Verbindungen auf lokaler oder Standortebene stützt, entsprechende Plattformprüfungen oder Fallbacks enthalten.

// Einfaches Hilfsmittel, um zu entscheiden, ob eine IP-Adresse "lokal" istbool isLocalAddress(const QHostAddress &address) { return address.isInSubnet(QHostAddress("192.168.0.0"), 16) ||address.isInSubnet(QHostAddress("10.0.0.0"), 8)    ||adresse.isInSubnet(QHostAddress("172.16.0.0"), 12) ||address.isLoopback(); }int main(int argc, char *argv[]) { ... // Ziel-IP-Adresse (Standard: Google DNS)   QString targetIpStr = argc > 1 ? argv[1]: "8.8.8.8";    QHostAddress targetIp(targetIpStr); if (targetIp.isNull()) {        qWarning() << "Invalid IP address:" << targetIpStr;
       return 1; } // Entscheiden, welcher Grad an Erreichbarkeit für das Ziel erforderlich ist  QNetworkInformation::Erreichbarkeit requiredReachability =isLocalAddress(targetIp) ? QNetworkInformation::Erreichbarkeit::Lokal : QNetworkInformation::Reachability::Online; // Abrufen der aktuellen, vom System gemeldeten Erreichbarkeit   QNetworkInformation::Erreichbarkeit currentReachability =  networkInfo->Erreichbarkeit();
    qDebug() << "Target IP:" << targetIp.toString();
    qDebug() << "Target is considered"
            << (isLocalAddress(targetIp) ? "local/site.": "extern/online.");    qDebug() << "Required reachability level:" << requiredReachability;
    qDebug() << "Current reachability:" << currentReachability;

   if (currentReachability < requiredReachability) {        qWarning() << "Current network state may not allow reaching the target address.";
    } sonst {        qDebug() << "Target may be reachable based on current network state.";
    } ...

Siehe auch QNetworkInformation::Feature.

Dokumentation der Mitgliedstypen

enum class QNetworkInformation::Feature
flags QNetworkInformation::Features

Listet alle Funktionen auf, die ein Plugin derzeit unterstützen kann. Dies kann in QNetworkInformation::loadBackendByFeatures() verwendet werden.

KonstanteWertBeschreibung
QNetworkInformation::Feature::Reachability0x1Wenn das Plugin diese Funktion unterstützt, wird die Eigenschaft reachability nützliche Ergebnisse liefern. Andernfalls wird sie immer Reachability::Unknown zurückgeben. Siehe auch QNetworkInformation::Reachability.
QNetworkInformation::Feature::CaptivePortal0x2Wenn das Plugin diese Funktion unterstützt, wird die Eigenschaft isBehindCaptivePortal nützliche Ergebnisse liefern. Andernfalls wird sie immer false zurückgeben.
QNetworkInformation::Feature::TransportMedium0x4Wenn das Plugin diese Funktion unterstützt, dann wird die Eigenschaft transportMedium nützliche Ergebnisse liefern. Andernfalls wird sie immer TransportMedium::Unknown zurückgeben. Siehe auch QNetworkInformation::TransportMedium.
QNetworkInformation::Feature::Metered0x8Wenn das Plugin diese Funktion unterstützt, wird die Eigenschaft isMetered nützliche Ergebnisse liefern. Andernfalls wird sie immer false zurückgeben.

Der Typ Features ist ein Typedef für QFlags<Feature>. Er speichert eine ODER-Kombination von Feature-Werten.

enum class QNetworkInformation::Reachability

KonstanteWertBeschreibung
QNetworkInformation::Reachability::Unknown0Wenn dieser Wert zurückgegeben wird, kann es sein, dass wir verbunden sind, aber das Betriebssystem noch nicht die volle Konnektivität bestätigt hat, oder diese Funktion nicht unterstützt wird.
QNetworkInformation::Reachability::Disconnected1Zeigt an, dass das System möglicherweise überhaupt keine Verbindung hat.
QNetworkInformation::Reachability::Local2Zeigt an, dass das System mit einem Netzwerk verbunden ist, aber möglicherweise nur auf Geräte im lokalen Netzwerk zugreifen kann.
QNetworkInformation::Reachability::Site3Zeigt an, dass das System mit einem Netzwerk verbunden ist, aber möglicherweise nur auf Geräte im lokalen Subnetz oder einem Intranet zugreifen kann.
QNetworkInformation::Reachability::Online4Zeigt an, dass das System mit einem Netzwerk verbunden ist und auf das Internet zugreifen kann.

Siehe auch QNetworkInformation::reachability.

[since 6.3] enum class QNetworkInformation::TransportMedium

Listet die derzeit anerkannten Medien auf, mit denen man sich mit dem Internet verbinden kann.

KonstanteWertBeschreibung
QNetworkInformation::TransportMedium::Unknown0Wird zurückgegeben, wenn entweder das Betriebssystem kein aktives Medium meldet, das aktive Medium von Qt nicht erkannt wird oder die TransportMedium-Funktion nicht unterstützt wird.
QNetworkInformation::TransportMedium::Ethernet1Zeigt an, dass die derzeit aktive Verbindung über Ethernet besteht. Hinweis: Dieser Wert kann auch zurückgegeben werden, wenn Windows mit einem Bluetooth Personal Area Network verbunden ist.
QNetworkInformation::TransportMedium::Cellular2Zeigt an, dass die derzeit aktive Verbindung ein Mobilfunknetz verwendet.
QNetworkInformation::TransportMedium::WiFi3Zeigt an, dass die derzeit aktive Verbindung Wi-Fi verwendet.
QNetworkInformation::TransportMedium::Bluetooth4Zeigt an, dass die derzeit aktive Verbindung über Bluetooth hergestellt wird.

Dieses Enum wurde in Qt 6.3 eingeführt.

Siehe auch QNetworkInformation::transportMedium.

Dokumentation der Eigenschaft

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

Zeigt an, ob sich das Gerät des Benutzers hinter einem firmeneigenen Portal befindet.

Diese Eigenschaft zeigt an, ob das Gerät des Benutzers derzeit bekannt ist, dass es sich hinter einem firmeneigenen Portal befindet. Diese Funktionalität beruht auf der Erkennung von Captive Portals durch das Betriebssystem und wird auf Systemen, die dies nicht melden, nicht unterstützt. Auf Systemen, auf denen dies nicht unterstützt wird, wird immer false zurückgegeben.

Diese Eigenschaft wurde in Qt 6.2 eingeführt.

Zugriffsfunktionen:

bool isBehindCaptivePortal() const

Benachrichtigungssignal:

void isBehindCaptivePortalChanged(bool state)

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

Prüfen, ob die aktuelle Verbindung gebührenpflichtig ist

Diese Eigenschaft gibt zurück, ob die aktuelle Verbindung (bekanntermaßen) gebührenpflichtig ist oder nicht. Sie können dies als Richtwert verwenden, um zu entscheiden, ob Ihre Anwendung bestimmte Netzwerkanforderungen oder Uploads durchführen soll. Sie können zum Beispiel keine Protokolle oder Diagnosen hochladen, wenn diese Eigenschaft true lautet.

void uploadLogFile() { ... }int main(int argc, char *argv[]) { QCoreApplication app(argc, argv); ... if (netInfo->isMetered()) {            qWarning() << "Log upload skipped: Current network is metered.";
            app.quit(); } else { uploadLogFile(); } ... }

Diese Eigenschaft wurde in Qt 6.3 eingeführt.

Zugriffsfunktionen:

bool isMetered() const

Benachrichtigungssignal:

void isMeteredChanged(bool isMetered)

[read-only] reachability : const Reachability

Diese Eigenschaft enthält den aktuellen Zustand der Netzkonnektivität des Systems.

Sie gibt den Grad der Konnektivität an, der erwartet werden kann. Bitte beachten Sie, dass dies nur auf dem basiert, was das Plugin/Betriebssystem meldet. In bestimmten Szenarien ist dies bekanntermaßen falsch. Unter Windows zum Beispiel wird die Online-Prüfung standardmäßig von Windows durchgeführt, indem eine Verbindung zu einem Microsoft-eigenen Server hergestellt wird. Wenn dieser Server aus irgendeinem Grund blockiert ist, wird angenommen, dass er nicht online erreichbar ist. Aus diesem Grund sollten Sie dies nicht als Vorabprüfung verwenden, bevor Sie versuchen, eine Verbindung herzustellen.

Zugriffsfunktionen:

QNetworkInformation::Reachability reachability() const

Benachrichtigungssignal:

void reachabilityChanged(QNetworkInformation::Reachability newReachability)

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

Diese Eigenschaft enthält das derzeit aktive Transportmedium für die Anwendung

Diese Eigenschaft gibt das derzeit aktive Transportmedium für die Anwendung auf Betriebssystemen zurück, auf denen diese Information verfügbar ist.

Wenn sich das aktuelle Transportmedium ändert, wird ein Signal ausgegeben. Dies kann beispielsweise der Fall sein, wenn ein Benutzer die Reichweite eines WiFi Netzwerks verlässt, sein Ethernetkabel abzieht oder den Flugzeugmodus aktiviert.

Diese Eigenschaft wurde in Qt 6.3 eingeführt.

Zugriffsfunktionen:

QNetworkInformation::TransportMedium transportMedium() const

Notifier Signal:

void transportMediumChanged(QNetworkInformation::TransportMedium current)

Member Function Dokumentation

[static] QStringList QNetworkInformation::availableBackends()

Gibt eine Liste mit den Namen aller derzeit verfügbaren Backends zurück.

QString QNetworkInformation::backendName() const

Gibt den Namen des aktuell geladenen Backends zurück.

[static] QNetworkInformation *QNetworkInformation::instance()

Gibt einen Zeiger auf die Instanz von QNetworkInformation zurück, falls vorhanden. Wenn diese Methode aufgerufen wird, bevor ein Backend geladen ist, gibt sie einen Null-Zeiger zurück.

Siehe auch loadBackendByName(), loadDefaultBackend(), und loadBackendByFeatures().

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

Lädt ein Backend, das features unterstützt.

Gibt true zurück, wenn es gelungen ist, das angeforderte Backend zu laden, oder wenn es bereits geladen wurde. Gibt andernfalls false zurück.

Diese Funktion wurde in Qt 6.4 eingeführt.

Siehe auch instance.

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

Versucht, ein Backend zu laden, dessen Name mit backend übereinstimmt (Groß- und Kleinschreibung wird nicht beachtet).

Gibt true zurück, wenn es gelungen ist, das angeforderte Backend zu laden oder wenn es bereits geladen wurde. Gibt andernfalls false zurück.

Diese Funktion wurde in Qt 6.4 eingeführt.

Siehe auch instance.

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

Versucht, das Standard-Backend der Plattform zu laden.

Hinweis: Ab 6.7 wird versucht, ein beliebiges Backend zu laden, das Reachability unterstützt, wenn das Plattform-Standard-Backend nicht verfügbar ist oder nicht geladen werden kann. Wenn auch dies fehlschlägt, wird auf ein Backend zurückgegriffen, das nur die Standardwerte für alle Eigenschaften zurückgibt.

Diese Plattform-Plugin-Zuordnung ist wie folgt:

PlattformPlugin-Name
WindowsNetzwerklisten-Manager
Apple (macOS/iOS)applenetzwerkinformation
Androidandroid
LinuxNetzwerkmanager

Diese Funktion dient der Bequemlichkeit, wenn die vorherige Logik ausreichend ist. Wenn Sie ein bestimmtes Plugin benötigen, sollten Sie stattdessen loadBackendByName() oder loadBackendByFeatures() direkt aufrufen.

Ermittelt ein geeignetes Backend zum Laden und gibt true zurück, wenn dieses Backend bereits geladen ist oder wenn es erfolgreich geladen wurde. Gibt false zurück, wenn ein anderes Backend bereits geladen wurde, oder wenn das Laden des ausgewählten Backends fehlschlägt.

Diese Funktion wurde in Qt 6.3 eingeführt.

Siehe auch instance(), loadBackendByName(), und loadBackendByFeatures().

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

Gibt alle unterstützten Features des aktuellen Backends zurück.

Diese Funktion wurde in Qt 6.3 eingeführt.

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

Gibt true zurück, wenn das aktuell geladene Backend features unterstützt.

© 2025 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.