Sur cette page

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

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()`.

ConstanteValeurDescription
QNetworkInformation::Feature::Reachability0x1Si 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::CaptivePortal0x2Si le plugin prend en charge cette fonctionnalité, la propriété isBehindCaptivePortal fournira des résultats utiles. Sinon, elle renverra toujours false.
QNetworkInformation::Feature::TransportMedium0x4Si 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::Metered0x8Si 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

ConstanteValeurDescription
QNetworkInformation::Reachability::Unknown0Si 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::Disconnected1Indique que le système n'a peut-être aucune connectivité.
QNetworkInformation::Reachability::Local2Indique 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::Site3Indique 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::Online4Indique 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.

ConstanteValeurDescription
QNetworkInformation::TransportMedium::Unknown0Renvoyé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::Ethernet1Indique 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::Cellular2Indique que la connexion actuellement active utilise un réseau cellulaire.
QNetworkInformation::TransportMedium::WiFi3Indique que la connexion actuellement active utilise le Wi-Fi.
QNetworkInformation::TransportMedium::Bluetooth4Indique 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 :

PlateformeNom du plugin
Windowsnetworklistmanager
Apple (macOS/iOS)applenetworkinformation
AndroidAndroid
Linuxnetworkmanager

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.