QNetworkInformation Class
QNetworkInformation permet d'accéder à diverses informations réseau via des backends natifs. En savoir plus...
| En-tête : | #include <QNetworkInformation> |
| CMake : | find_package(Qt6 REQUIRED COMPONENTS Network) target_link_libraries(mytarget PRIVATE Qt6::Network) |
| qmake : | QT += network |
| Depuis : | Qt 6.1 |
| Hérite de : | QObject |
Types publics
| 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 } |
Propriétés
(since 6.2)isBehindCaptivePortal : bool(since 6.3)isMetered : bool- reachability : Reachability
(since 6.3)transportMedium : TransportMedium
Fonctions publiques
| 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 |
Signaux
| void | isBehindCaptivePortalChanged(bool state) |
| void | isMeteredChanged(bool isMetered) |
| void | reachabilityChanged(QNetworkInformation::Reachability newReachability) |
| void | transportMediumChanged(QNetworkInformation::TransportMedium current) |
Membres publics statiques
| QStringList | availableBackends() |
| QNetworkInformation * | instance() |
(since 6.4) bool | loadBackendByFeatures(QNetworkInformation::Features features) |
(since 6.4) bool | loadBackendByName(QStringView backend) |
(since 6.3) bool | loadDefaultBackend() |
Description détaillée
QNetworkInformation fournit une interface multiplateforme permettant d'accéder aux informations relatives au réseau via des plugins.
Les différents plugins peuvent prendre en charge diverses fonctionnalités ; vous pouvez donc charger ceux dont vous avez besoin en fonction de vos besoins.
Dans la plupart des cas, l’approche recommandée consiste à charger le backend spécifique à la plateforme en appelant la fonction ` loadDefaultBackend()`. Cela sélectionnera automatiquement le backend le plus approprié disponible sur la plateforme actuelle et convient à la majorité des applications.
#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::Accessibilité::Déconnecté :
qDebug() << "Network is disconnected.";
break;
case QNetworkInformation::Accessibilité::Locale:
qDebug() << "Network is locally reachable.";
break;
case QNetworkInformation::Accessibilité::Site :
qDebug() << "Network can reach the site.";
break;
case QNetworkInformation::Accessibilité::En ligne:
qDebug() << "Network is online.";
break;
}
}
int main(int argc, char *argv[]) {
QCoreApplication a(argc, argv);
// Vérifier si QNetworkInformation est pris en charge
if (!QNetworkInformation::loadDefaultBackend()) {
qWarning() << "QNetworkInformation is not supported on this platform or backend.";
return 1;
}
QNetworkInformation* netInfo = QNetworkInformation::instance();
// Connexion au signal reachabilityChanged
QObject::connect(netInfo, &QNetworkInformation::reachabilityChanged,
&onReachabilityChanged);
// Afficher l'état initial
onReachabilityChanged(netInfo->reachability());
return a.exec();
}Pour des cas d’utilisation plus avancés, les développeurs peuvent préférer charger un backend en fonction de capacités ou de préférences spécifiques. La fonction ` loadBackendByFeatures()` permet de sélectionner un backend prenant en charge un ensemble spécifique de fonctionnalités, telles que la notification du support de transport ou de la puissance du signal. Par ailleurs, la fonction ` loadBackendByName()` permet de charger un plugin par son nom, ce qui peut inclure des implémentations de backend spécifiques à une plateforme ou personnalisées.
QNetworkInformation est un singleton et reste actif depuis le premier chargement réussi jusqu’à la destruction de l’objet QCoreApplication. Si vous détruisez puis recréez l’objet QCoreApplication, vous devez le charger à nouveau pour réinitialiser le plugin.
Remarque : comme la classe est un singleton et qu’elle dépend également de ` QCoreApplication`, `QNetworkInformation` doit toujours être chargé en premier dans le même thread que l’objet ` QCoreApplication `. En effet, l’objet sera également détruit dans ce thread, et divers composants spécifiques au backend peuvent nécessiter d’être détruits dans le même thread que celui où ils ont été créés.
Un cas d’utilisation possible de QNetworkInformation consiste à surveiller l’état de la connectivité réseau. La fonction ` reachability()` indique si le système est considéré comme en ligne, en se basant sur les informations fournies par le système d’exploitation sous-jacent ou le plugin. Cependant, ces informations ne sont pas toujours exactes. Par exemple, sous Windows, la vérification de la connexion peut reposer sur la connectivité à un serveur appartenant à Microsoft ; si ce serveur est inaccessible (par exemple, en raison de règles de pare-feu), le système peut indiquer à tort qu’il est hors ligne. Par conséquent, la fonction ` reachability()` ne doit pas être utilisée comme vérification préalable définitive avant de tenter une connexion réseau, mais plutôt comme une indication générale de l’état de la connectivité.
Pour utiliser efficacement reachability(), l’application doit également comprendre de quel type de destination elle tente de se connecter. Par exemple, si la cible est une adresse IP locale, alors Reachability::Local ou Reachability::Site peuvent suffire. Si la destination se trouve sur l’Internet public, alors Reachability::Online est nécessaire. Sans ce contexte, l’interprétation de l’accessibilité signalée peut conduire à des hypothèses erronées concernant l’accès réel au réseau.
Avertissement : seuls Linux et Windows prennent en charge les options plus précises « Reachability::Site » et « Reachability::Local ». Sur les plateformes Android et Apple, la fonction « reachability() » se limite à signaler uniquement « En ligne », « Hors ligne » ou « Inconnu ». Par conséquent, toute logique reposant sur la détection de la connectivité au niveau local ou du site doit inclure des vérifications de plateforme appropriées ou des solutions de repli.
// Aide simple pour déterminer si une adresse IP est « locale »
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[])
{
...
// Adresse IP cible (par défaut : DNS Google)
QString targetIpStr = argc > 1 ? argv[1]: "8.8.8.8";
QHostAddress targetIp(targetIpStr);
if (targetIp.isNull()) {
qWarning() << "Invalid IP address:" << targetIpStr;
return 1;
}
// Déterminer le niveau d'accessibilité requis pour la cible
QNetworkInformation::Accessibilité requiseAccessibilité =
isLocalAddress(adresseIPcible)
? QNetworkInformation::Reachability::Local
: QNetworkInformation::Reachability::Online;
// Récupérer l'accessibilité actuelle signalée par le système
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 (accessibilitéActuelle < accessibilitéRe requise) {
qWarning() << "Current network state may not allow reaching the target address.";
} else {
qDebug() << "Target may be reachable based on current network state.";
}
...Voir également QNetworkInformation::Feature.
Documentation sur les types de membres
enum class QNetworkInformation::Feature
flags QNetworkInformation::Features
Répertorie toutes les fonctionnalités qu'un plugin peut actuellement prendre en charge. Cette fonction peut être utilisée dans ` QNetworkInformation::loadBackendByFeatures()`.
| Constante | Valeur | Description |
|---|---|---|
QNetworkInformation::Feature::Reachability | 0x1 | Si le plugin prend en charge cette fonctionnalité, la propriété reachability fournira des résultats utiles. Sinon, elle renverra toujours Reachability::Unknown. Voir également QNetworkInformation::Reachability. |
QNetworkInformation::Feature::CaptivePortal | 0x2 | Si le plugin prend en charge cette fonctionnalité, la propriété isBehindCaptivePortal fournira des résultats utiles. Sinon, elle renverra toujours false. |
QNetworkInformation::Feature::TransportMedium | 0x4 | Si le plugin prend en charge cette fonctionnalité, la propriété transportMedium fournira des résultats utiles. Sinon, elle renverra toujours TransportMedium::Unknown. Voir également QNetworkInformation::TransportMedium. |
QNetworkInformation::Feature::Metered | 0x8 | Si le plugin prend en charge cette fonctionnalité, la propriété isMetered fournira des résultats utiles. Sinon, elle renverra toujours false. |
Le type Features est un typedef pour QFlags<Feature>. Il stocke une combinaison OU de valeurs Feature.
enum class QNetworkInformation::Reachability
| Constante | Valeur | Description |
|---|---|---|
QNetworkInformation::Reachability::Unknown | 0 | Si cette valeur est renvoyée, cela signifie soit que la connexion est établie mais que le système d’exploitation n’a pas encore confirmé la connectivité complète, soit que cette fonctionnalité n’est pas prise en charge. |
QNetworkInformation::Reachability::Disconnected | 1 | Indique que le système n'a peut-être aucune connectivité. |
QNetworkInformation::Reachability::Local | 2 | Indique que le système est connecté à un réseau, mais qu'il ne peut peut-être accéder qu'aux périphériques du réseau local. |
QNetworkInformation::Reachability::Site | 3 | Indique que le système est connecté à un réseau, mais qu'il ne peut accéder qu'aux périphériques du sous-réseau local ou d'un intranet. |
QNetworkInformation::Reachability::Online | 4 | Indique que le système est connecté à un réseau et capable d'accéder à Internet. |
Voir également QNetworkInformation::reachability.
[since 6.3] enum class QNetworkInformation::TransportMedium
Répertorie les supports actuellement pris en charge permettant de se connecter à Internet.
| Constante | Valeur | Description |
|---|---|---|
QNetworkInformation::TransportMedium::Unknown | 0 | Renvoyée si le système d’exploitation ne signale aucun support actif, si le support actif n’est pas reconnu par Qt ou si la fonctionnalité TransportMedium n’est pas prise en charge. |
QNetworkInformation::TransportMedium::Ethernet | 1 | Indique que la connexion actuellement active utilise Ethernet. Remarque : cette valeur peut également être renvoyée lorsque Windows est connecté à un réseau personnel Bluetooth. |
QNetworkInformation::TransportMedium::Cellular | 2 | Indique que la connexion actuellement active utilise un réseau cellulaire. |
QNetworkInformation::TransportMedium::WiFi | 3 | Indique que la connexion actuellement active utilise le Wi-Fi. |
QNetworkInformation::TransportMedium::Bluetooth | 4 | Indique que la connexion actuellement active utilise le Bluetooth. |
Cette énumération a été introduite dans Qt 6.3.
Voir également QNetworkInformation::transportMedium.
Documentation sur les propriétés
[read-only, since 6.2] isBehindCaptivePortal : bool
Indique si l'appareil de l'utilisateur se trouve derrière un portail captif.
Cette propriété indique si l'appareil de l'utilisateur est actuellement identifié comme étant derrière un portail captif. Cette fonctionnalité repose sur la détection des portails captifs par le système d'exploitation et n'est pas prise en charge sur les systèmes qui ne signalent pas cette information. Sur les systèmes où cette fonctionnalité n'est pas prise en charge, elle renverra toujours la valeur « false ».
Cette énumération a été introduite dans Qt 6.2.
Fonctions d'accès :
| bool | isBehindCaptivePortal() const |
Signal de notification :
| void | isBehindCaptivePortalChanged(bool state) |
[read-only, since 6.3] isMetered : bool
Vérifier si la connexion actuelle est facturée au volume
Cette propriété indique si la connexion actuelle est (à notre connaissance) limitée ou non. Vous pouvez vous en servir comme critère pour décider si votre application doit effectuer certaines requêtes réseau ou certains transferts. Par exemple, vous ne souhaiterez peut-être pas transférer de journaux ou de diagnostics lorsque cette propriété est définie sur « true ».
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();
}
...
}Cette énumération a été introduite dans Qt 6.3.
Fonctions d'accès :
| bool | isMetered() const |
Signal de notification :
| void | isMeteredChanged(bool isMetered) |
[read-only] reachability : Reachability
Cette propriété indique l'état actuel de la connectivité réseau du système.
Elle indique le niveau de connectivité auquel on peut s'attendre. Veuillez noter que cette information repose uniquement sur les données fournies par le plugin ou le système d'exploitation. Dans certains cas, ces informations peuvent s'avérer erronées. Par exemple, sous Windows, la vérification « En ligne » est, par défaut, effectuée par Windows via une connexion à un serveur appartenant à Microsoft. Si ce serveur est bloqué pour une raison quelconque, le système supposera qu’il n’est pas accessible en ligne. C’est pourquoi vous ne devez pas utiliser cette propriété comme vérification préalable avant de tenter d’établir une connexion.
Fonctions d'accès :
| QNetworkInformation::Reachability | reachability() const |
Signal de notification :
| void | reachabilityChanged(QNetworkInformation::Reachability newReachability) |
[read-only, since 6.3] transportMedium : TransportMedium
Cette propriété contient le support de transport actuellement actif pour l'application
Cette propriété renvoie le support de transport actuellement actif pour l'application, sur les systèmes d'exploitation où ces informations sont disponibles.
Lorsqu’un changement de support de transport se produit, un signal est émis ; cela peut, par exemple, se produire lorsqu’un utilisateur quitte la zone de couverture d’un réseau « WiFi », débranche son câble Ethernet ou active le mode Avion.
Cette énumération a été introduite dans Qt 6.3.
Fonctions d’accès :
| QNetworkInformation::TransportMedium | transportMedium() const |
Signal de notification :
| void | transportMediumChanged(QNetworkInformation::TransportMedium current) |
Documentation des fonctions membres
[static] QStringList QNetworkInformation::availableBackends()
Renvoie une liste contenant les noms de tous les backends actuellement disponibles.
QString QNetworkInformation::backendName() const
Renvoie le nom du backend actuellement chargé.
[static] QNetworkInformation *QNetworkInformation::instance()
Renvoie un pointeur vers l'instance de l'QNetworkInformation, le cas échéant. Si cette méthode est appelée avant le chargement d'un backend, elle renvoie un pointeur nul.
Voir également loadBackendByName(), loadDefaultBackend() et loadBackendByFeatures().
[static, since 6.4] bool QNetworkInformation::loadBackendByFeatures(QNetworkInformation::Features features)
Charge un backend prenant en charge features.
Renvoie ` true ` si le backend demandé a pu être chargé ou s'il était déjà chargé. Renvoie ` false ` dans le cas contraire.
Cette fonction a été introduite dans Qt 6.4.
Voir également instance.
[static, since 6.4] bool QNetworkInformation::loadBackendByName(QStringView backend)
Tente de charger un backend dont le nom correspond à « backend » (sans distinction de majuscules/minuscules).
Renvoie true si le backend demandé a pu être chargé ou s'il était déjà chargé. Renvoie false dans le cas contraire.
Cette fonction a été introduite dans Qt 6.4.
Voir également instance.
[static, since 6.3] bool QNetworkInformation::loadDefaultBackend()
Tentative de chargement du backend par défaut de la plateforme.
Remarque : à partir de la version 6.7, si le backend par défaut de la plateforme n'est pas disponible ou ne parvient pas à se charger, le système tente de charger n'importe quel backend prenant en charge Reachability. Si cette tentative échoue également, le système se rabattra sur un backend qui renvoie uniquement les valeurs par défaut pour toutes les propriétés.
Le mappage entre la plateforme et les plugins est le suivant :
| Plateforme | Nom du plugin |
|---|---|
| Windows | networklistmanager |
| Apple (macOS/iOS) | applenetworkinformation |
| Android | Android |
| Linux | networkmanager |
Cette fonction est fournie à titre de commodité lorsque la logique décrite précédemment est suffisante. Si vous avez besoin d'un plugin spécifique, vous devez plutôt appeler directement loadBackendByName() ou loadBackendByFeatures().
Détermine un backend approprié à charger et renvoie true si ce backend est déjà chargé ou si son chargement a réussi. Renvoie false si un autre backend a déjà été chargé, ou si le chargement du backend sélectionné échoue.
Cette fonction a été introduite dans Qt 6.3.
Voir également instance(), loadBackendByName() et loadBackendByFeatures().
[since 6.3] QNetworkInformation::Features QNetworkInformation::supportedFeatures() const
Renvoie toutes les fonctionnalités prises en charge par le backend actuel.
Cette fonction a été introduite dans Qt 6.3.
bool QNetworkInformation::supports(QNetworkInformation::Features features) const
Renvoie ` true ` si le backend actuellement chargé prend en charge ` features`.
© 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.