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
(since 6.2)isBehindCaptivePortal : bool(since 6.3)isMetered : bool- reachability : Reachability
(since 6.3)transportMedium : TransportMedium
Ö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.
| Konstante | Wert | Beschreibung |
|---|---|---|
QNetworkInformation::Feature::Reachability | 0x1 | Wenn 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::CaptivePortal | 0x2 | Wenn das Plugin diese Funktion unterstützt, liefert die Eigenschaft ` isBehindCaptivePortal ` aussagekräftige Ergebnisse. Andernfalls gibt sie immer ` false` zurück. |
QNetworkInformation::Feature::TransportMedium | 0x4 | Wenn 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::Metered | 0x8 | Wenn 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
| Konstante | Wert | Beschreibung |
|---|---|---|
QNetworkInformation::Reachability::Unknown | 0 | Wird 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::Disconnected | 1 | Zeigt an, dass das System möglicherweise überhaupt keine Verbindung hat. |
QNetworkInformation::Reachability::Local | 2 | Zeigt an, dass das System mit einem Netzwerk verbunden ist, jedoch möglicherweise nur auf Geräte im lokalen Netzwerk zugreifen kann. |
QNetworkInformation::Reachability::Site | 3 | Zeigt 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::Online | 4 | Zeigt 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.
| Konstante | Wert | Beschreibung |
|---|---|---|
QNetworkInformation::TransportMedium::Unknown | 0 | Wird 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::Ethernet | 1 | Gibt 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::Cellular | 2 | Gibt an, dass die derzeit aktive Verbindung ein Mobilfunknetz nutzt. |
QNetworkInformation::TransportMedium::WiFi | 3 | Gibt an, dass die derzeit aktive Verbindung über WLAN hergestellt ist. |
QNetworkInformation::TransportMedium::Bluetooth | 4 | Gibt 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:
| Plattform | Plugin-Name |
|---|---|
| Windows | networklistmanager |
| Apple (macOS/iOS) | applenetworkinformation |
| Android | Android |
| Linux | networkmanager |
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.