Auf dieser Seite

QNetworkInformation Class

QNetworkInformation stellt über native Backends verschiedene Netzwerkinformationen bereit. Mehr...

Header: #include <QNetworkInformation>
CMake: find_package(Qt6 REQUIRED COMPONENTS Network)
target_link_libraries(mytarget PRIVATE Qt6::Network)
qmake: QT += network
Seit: Qt 6.1
Erbt von: 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()

Ausführliche Beschreibung

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

Verschiedene Plugins können unterschiedliche Funktionen unterstützen, sodass Sie Plugins je nach den benötigten Funktionen laden können.

In den meisten Fällen empfiehlt es sich, das plattformspezifische Backend durch den Aufruf von ` loadDefaultBackend()` zu laden. Dadurch wird automatisch das für die aktuelle Plattform am besten geeignete Backend ausgewählt, was für die meisten Anwendungen ausreichend ist.

#include <QCoreApplication>
#include <QNetworkInformation>
#include <QDebug>

void onReachabilityChanged(QNetworkInformation::Reachability reachability) {
    switch (reachability) {
    case QNetworkInformation::Reachability::Unknown:
        qDebug() << "Network reachability is unknown.";
       break;
    case QNetworkInformation::Erreichbarkeit::Nicht verbunden:
        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 zum Signal „reachabilityChanged“ herstellen
    QObject::connect(netInfo, &QNetworkInformation::reachabilityChanged,
                     &onReachabilityChanged);

    // Anfangsstatus ausgeben
    onReachabilityChanged(netInfo->reachability());

    return a.exec();
}

Für fortgeschrittenere Anwendungsfälle möchten Entwickler möglicherweise ein Backend basierend auf bestimmten Funktionen oder Präferenzen laden. Mit ` loadBackendByFeatures()` lässt sich ein Backend auswählen, das einen bestimmten Funktionsumfang unterstützt, wie beispielsweise die Meldung des Übertragungsmediums oder der Signalstärke. Alternativ ermöglicht ` loadBackendByName()` das Laden eines Plugins anhand seines Namens, was plattformspezifische oder benutzerdefinierte Backend-Implementierungen einschließen kann.

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

Hinweis: Da es sich bei der Klasse um ein Singleton handelt, das zudem auf ` QCoreApplication` angewiesen ist, sollte `QNetworkInformation` immer zuerst im selben Thread wie das ` QCoreApplication `-Objekt geladen werden. Der Grund dafür ist, dass das Objekt ebenfalls in diesem Thread zerstört wird und verschiedene backend-spezifische Komponenten möglicherweise darauf angewiesen sind, im selben Thread zerstört zu werden, in dem sie erstellt wurden.

Ein möglicher Anwendungsfall für `QNetworkInformation` ist die Überwachung des Netzwerkverbindungsstatus. ` reachability()` liefert 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 möglicherweise nicht immer korrekt. Unter Windows beispielsweise stützt sich die Online-Prüfung möglicherweise auf die Verbindung zu einem Microsoft-eigenen Server; ist dieser Server nicht erreichbar (z. B. aufgrund von Firewall-Regeln), meldet das System möglicherweise fälschlicherweise, dass es offline ist. Daher sollte ` reachability()` nicht als endgültige Vorabprüfung vor dem Versuch einer Netzwerkverbindung verwendet werden, sondern vielmehr als allgemeiner Hinweis auf den Verbindungsstatus.

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

Warnung: Nur Linux und Windows bieten Unterstützung für die detaillierteren Optionen „ Reachability::Site “ und „ Reachability::Local “. Auf Android- und Apple-Plattformen ist „ reachability()“ darauf beschränkt, lediglich „Online“, „Offline“ oder „Unbekannt“ zu melden. Daher muss jede Logik, die auf der Erkennung der Konnektivität auf lokaler oder Standortebene basiert, entsprechende Plattformprüfungen oder Ausweichmöglichkeiten enthalten.

// Einfache Hilfsfunktion zur Feststellung, ob eine IP-Adresse „lokal“ ist
bool isLocalAddress(const QHostAddress&address)
{
    return address.isInSubnet(QHostAddress("192.168.0.0"), 16)||
           address.isInSubnet(QHostAddress("10.0.0.0"), 8)     ||
           address.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;
    }

    // Festlegen, welche Erreichbarkeitsstufe für das Ziel erforderlich ist
    QNetworkInformation::Erreichbarkeitsstufe requiredReachability =
        isLocalAddress(targetIp)
            ? QNetworkInformation::Reachability::Local
            : QNetworkInformation::Reachability::Online;

    // Die aktuell vom System gemeldete Erreichbarkeit abrufen
    QNetworkInformation::Reachability currentReachability = networkInfo->reachability();

    qDebug() << "Target IP:" << targetIp.toString();
    qDebug() << "Target is considered"
            << (isLocalAddress(targetIp) ? "local/site.": "external/online.");
    qDebug() << "Required reachability level:" << requiredReachability;
    qDebug() << "Current reachability:" << currentReachability;

   if (aktuelle Erreichbarkeit < erforderliche Erreichbarkeit) {
        qWarning() << "Current network state may not allow reaching the target address.";
    } else {
        qDebug() << "Target may be reachable based on current network state.";
    }
    ...

Siehe auch QNetworkInformation::Feature.

Dokumentation zu Mitgliedstypen

enum class QNetworkInformation::Feature
flags QNetworkInformation::Features

Listet alle Funktionen auf, die ein Plugin derzeit möglicherweise unterstützt. Dies kann in ` QNetworkInformation::loadBackendByFeatures()` verwendet werden.

KonstanteWertBeschreibung
QNetworkInformation::Feature::Reachability0x1Wenn das Plugin diese Funktion unterstützt, liefert die Eigenschaft „ reachability “ aussagekräftige Ergebnisse. Andernfalls wird stets „ Reachability::Unknown “ zurückgegeben. Siehe auch „ QNetworkInformation::Reachability “.
QNetworkInformation::Feature::CaptivePortal0x2Wenn das Plugin diese Funktion unterstützt, liefert die Eigenschaft ` isBehindCaptivePortal ` aussagekräftige Ergebnisse. Andernfalls gibt sie immer ` false` zurück.
QNetworkInformation::Feature::TransportMedium0x4Wenn das Plugin diese Funktion unterstützt, liefert die Eigenschaft „ transportMedium “ nützliche Ergebnisse. Andernfalls gibt sie immer „ TransportMedium::Unknown “ zurück. Siehe auch QNetworkInformation::TransportMedium.
QNetworkInformation::Feature::Metered0x8Wenn das Plugin diese Funktion unterstützt, liefert die Eigenschaft „ isMetered “ nützliche Ergebnisse. Andernfalls gibt sie immer „ false “ zurück.

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::Unknown0Wird dieser Wert zurückgegeben, besteht möglicherweise eine Verbindung, das Betriebssystem hat jedoch noch keine vollständige Konnektivität bestätigt, oder diese Funktion wird nicht unterstützt.
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, jedoch 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 in 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 unterstützten Medien auf, über die man eine Verbindung zum Internet herstellen 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 Funktion „TransportMedium“ nicht unterstützt wird.
QNetworkInformation::TransportMedium::Ethernet1Gibt an, dass die derzeit aktive Verbindung über Ethernet hergestellt ist. Hinweis: Dieser Wert kann auch zurückgegeben werden, wenn Windows mit einem Bluetooth-Personal-Area-Netzwerk verbunden ist.
QNetworkInformation::TransportMedium::Cellular2Gibt an, dass die derzeit aktive Verbindung ein Mobilfunknetz nutzt.
QNetworkInformation::TransportMedium::WiFi3Gibt an, dass die derzeit aktive Verbindung über WLAN hergestellt ist.
QNetworkInformation::TransportMedium::Bluetooth4Gibt an, dass die derzeit aktive Verbindung über Bluetooth hergestellt ist.

Diese Enumeration wurde in Qt 6.3 eingeführt.

Siehe auch „ QNetworkInformation::transportMedium “.

Dokumentation zur Eigenschaft

[read-only, since 6.2] isBehindCaptivePortal : bool

Gibt an, ob sich das Gerät des Benutzers hinter einem Captive Portal befindet.

Diese Eigenschaft gibt an, ob das Gerät des Benutzers derzeit bekanntermaßen hinter einem Captive Portal liegt. Diese Funktion stützt sich auf die 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 stets „ false “ zurückgegeben.

Diese Aufzählung wurde in Qt 6.2 eingeführt.

Zugriffsfunktionen:

bool isBehindCaptivePortal() const

Notifier-Signal:

void isBehindCaptivePortalChanged(bool state)

[read-only, since 6.3] isMetered : bool

Prüfen, ob bei der aktuellen Verbindung eine Datenvolumenbegrenzung gilt

Diese Eigenschaft gibt an, ob die aktuelle Verbindung (nach bekanntermaßen) datenvolumebegrenzt ist oder nicht. Sie können dies als Entscheidungshilfe nutzen, um zu bestimmen, ob Ihre Anwendung bestimmte Netzwerkanfragen oder Uploads durchführen soll. Beispielsweise möchten Sie möglicherweise keine Protokolle oder Diagnosedaten hochladen, solange diese Eigenschaft den Wert „ true “ hat.

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 Aufzählung wurde in Qt 6.3 eingeführt.

Zugriffsfunktionen:

bool isMetered() const

Notifier-Signal:

void isMeteredChanged(bool isMetered)

[read-only] reachability : Reachability

Diese Eigenschaft gibt den aktuellen Status der Netzwerkverbindung des Systems an.

Sie gibt den zu erwartenden Verbindungsstatus an. Bitte beachten Sie, dass diese Angabe ausschließlich auf den Meldungen des Plugins bzw. des Betriebssystems basiert. In bestimmten Szenarien kann diese Angabe fehlerhaft sein. Unter Windows wird beispielsweise die Überprüfung des „Online“-Status standardmäßig dadurch durchgeführt, dass Windows eine Verbindung zu einem Microsoft-eigenen Server herstellt. Ist dieser Server aus irgendeinem Grund blockiert, geht das System davon aus, dass keine Online-Erreichbarkeit besteht. Aus diesem Grund sollten Sie diese Eigenschaft 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 : TransportMedium

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

Diese Eigenschaft gibt das derzeit aktive Transportmedium für die Anwendung zurück, sofern diese Information auf dem jeweiligen Betriebssystem verfügbar ist.

Wenn sich das aktuelle Transportmedium ändert, wird ein Signal ausgelöst; dies kann beispielsweise geschehen, wenn ein Benutzer den Empfangsbereich eines „ WiFi “-Netzwerks verlässt, sein Ethernet-Kabel abzieht oder den Flugmodus aktiviert.

Diese Aufzählung wurde in Qt 6.3 eingeführt.

Zugriffsfunktionen:

QNetworkInformation::TransportMedium transportMedium() const

Notifier-Signal:

void transportMediumChanged(QNetworkInformation::TransportMedium current)

Dokumentation der Mitgliedsfunktionen

[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, sofern vorhanden. Wird diese Methode aufgerufen, bevor ein Backend geladen wurde, gibt sie einen Nullzeiger 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 das angeforderte Backend erfolgreich geladen wurde oder bereits geladen war. Andernfalls wird „ false “ zurückgegeben.

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ß-/Kleinschreibung wird nicht berücksichtigt).

Gibt „ true “ zurück, wenn das angeforderte Backend geladen werden konnte oder bereits geladen war. Andernfalls wird „ false “ zurückgegeben.

Diese Funktion wurde in Qt 6.4 eingeführt.

Siehe auch instance.

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

Es wird versucht, das plattformstandardmäßige Backend zu laden.

Hinweis: Ab Version 6.7 wird versucht, ein beliebiges Backend zu laden, das „ Reachability “ unterstützt, falls das plattformspezifische Standard-Backend nicht verfügbar ist oder nicht geladen werden kann. Gelingt auch dies nicht, wird auf ein Backend zurückgegriffen, das für alle Eigenschaften lediglich die Standardwerte zurückgibt.

Die Zuordnung zwischen Plattform und Plugin sieht wie folgt aus:

PlattformPlugin-Name
Windowsnetworklistmanager
Apple (macOS/iOS)applenetworkinformation
AndroidAndroid
Linuxnetworkmanager

Diese Funktion dient der Vereinfachung, sofern die zuvor beschriebene Logik ausreichend ist. Wenn Sie ein bestimmtes Plugin benötigen, sollten Sie stattdessen direkt ` loadBackendByName()` oder ` loadBackendByFeatures()` aufrufen.

Ermittelt ein geeignetes Backend zum Laden und gibt ` true ` zurück, wenn dieses Backend bereits geladen ist oder das Laden erfolgreich war. Gibt ` false ` zurück, wenn bereits ein anderes Backend geladen wurde oder 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 Funktionen 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.

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