En esta página

QNetworkInformation Class

QNetworkInformation expone diversa información de red a través de backends nativos. Más...

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

Tipos Públicos

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 }

Propiedades

Funciones públicas

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

Señales

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

Miembros públicos estáticos

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

Descripción detallada

QNetworkInformation proporciona una interfaz multiplataforma a la información relacionada con la red a través de plugins.

Varios plugins pueden tener varias funcionalidades soportadas, por lo que se pueden cargar plugins en función de las características que se necesiten.

En la mayoría de los casos, el enfoque recomendado es cargar el backend específico de la plataforma llamando a loadDefaultBackend(). Esto seleccionará automáticamente el backend más apropiado disponible en la plataforma actual y es adecuado para la mayoría de las aplicaciones.

#include <QCoreApplication>#include <QNetworkInformation>#include <QDebug>void onReachabilityChanged(QNetworkInformation::Reachability reachability) { switch (reachability) { case QNetworkInformation::Reachability::Desconocido:        qDebug() << "Network reachability is unknown.";
       break; case QNetworkInformation::Reachability::Desconectado:        qDebug() << "Network is disconnected.";
       break; case QNetworkInformation::Reachability::Local:        qDebug() << "Network is locally reachable.";
       break; case QNetworkInformation::Reachability::Site:        qDebug() << "Network can reach the site.";
       break; case QNetworkInformation::Reachability::Online:        qDebug() << "Network is online.";
       break; } }int main(int argc, char *argv[]) { QCoreApplication ¡a(argc, argv); // Comprueba si QNetworkInformation está soportado if (!QNetworkInformation::loadDefaultBackend()) {        qWarning() << "QNetworkInformation is not supported on this platform or backend.";
       return 1; } QNetworkInformation* netInfo = QNetworkInformation::instance(); // Conectar a la señal reachabilityChanged   QObject::connect(netInfo, &QNetworkInformation::reachabilityChanged, &onReachabilityChanged); // Imprimir estado inicialonReachabilityChanged(netInfo->reachability()); return a.exec(); }

Para casos de uso más avanzados, los desarrolladores pueden preferir cargar un backend basado en capacidades o preferencias específicas. loadBackendByFeatures() permite seleccionar un backend que soporte un conjunto específico de características, como informar del mediom de transporte o de la intensidad de la señal. Alternativamente, loadBackendByName() permite cargar un plugin por su nombre, que puede incluir implementaciones de backend específicas de la plataforma o personalizadas.

QNetworkInformation es un singleton y permanece vivo desde la primera carga con éxito hasta la destrucción del objeto QCoreApplication. Si destruyes y vuelves a crear el objeto QCoreApplication deberás cargarlo de nuevo para reinicializar el plugin.

Nota: Debido a que la clase es un singleton mientras que también depende de QCoreApplication, QNetworkInformation siempre debe cargarse primero en el mismo hilo que el objeto QCoreApplication. Esto se debe a que el objeto también se destruirá en este subproceso, y varios componentes específicos del backend pueden depender de que se destruya en el mismo subproceso en el que se crea.

Un posible caso de uso para QNetworkInformation es monitorizar el estado de conectividad de la red. reachability QNetworkInformation () proporciona una indicación de si el sistema se considera en línea, basándose en la información reportada por el sistema operativo subyacente o el plugin. Sin embargo, esta información puede no ser siempre exacta. Por ejemplo, en Windows, la comprobación en línea puede depender de la conectividad a un servidor propiedad de Microsoft; si no se puede acceder a ese servidor (por ejemplo, debido a las reglas del cortafuegos), el sistema puede informar incorrectamente de que está desconectado. Por ello, reachability() no debe utilizarse como una comprobación previa definitiva antes de intentar una conexión de red, sino como una señal general del estado de la conectividad.

Para utilizar reachability() de forma efectiva, la aplicación también debe entender qué tipo de destino está intentando alcanzar. Por ejemplo, si el destino es una dirección IP local, entonces Reachability::Local o Reachability::Site pueden ser suficientes. Si el destino está en la Internet pública, entonces se requiere Reachability::Online. Sin este contexto, la interpretación de la accesibilidad notificada puede llevar a suposiciones incorrectas sobre el acceso real a la red.

Advertencia: Sólo Linux y Windows ofrecen soporte para las opciones más precisas Reachability::Site y Reachability::Local. En las plataformas Android y Apple reachability() se limita a informar únicamente de Online, Offline o Unknown. Por lo tanto, cualquier lógica que se base en la detección de conectividad a nivel local o de sitio debe incluir las comprobaciones de plataforma adecuadas o fallbacks.

// Simple helper para decidir si una dirección IP es "local"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[]) { ... // Dirección IP de destino (por defecto: 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; } // Decidir qué nivel de accesibilidad se necesita para el objetivo   QNetworkInformation::Reachability requiredReachability =isLocalAddress(targetIp) ? QNetworkInformation::Reachability::Local : QNetworkInformation::Reachability::Online; // Obtener la accesibilidad actual del sistema   QNetworkInformation::Reachability currentReachability =  networkInfo->reachability();
    qDebug() << "Target IP:" << targetIp.toString();
    qDebug() << "Target is considered"
            << (isLocalAddress(targetIp) ? "local/sitio.": " externo/en línea.");    qDebug() << "Required reachability level:" << requiredReachability;
    qDebug() << "Current reachability:" << currentReachability;

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

Véase también QNetworkInformation::Feature.

Documentación de tipos de miembros

enum class QNetworkInformation::Feature
flags QNetworkInformation::Features

Lista todas las características que un plugin puede soportar actualmente. Puede utilizarse en QNetworkInformation::loadBackendByFeatures().

ConstanteValorDescripción
QNetworkInformation::Feature::Reachability0x1Si el plugin soporta esta característica entonces la propiedad reachability proporcionará resultados útiles. En caso contrario, siempre devolverá Reachability::Unknown. Véase también QNetworkInformation::Reachability.
QNetworkInformation::Feature::CaptivePortal0x2Si el complemento es compatible con esta función, la propiedad isBehindCaptivePortal proporcionará resultados útiles. En caso contrario, siempre devolverá false.
QNetworkInformation::Feature::TransportMedium0x4Si el complemento es compatible con esta función, la propiedad transportMedium proporcionará resultados útiles. En caso contrario, siempre devolverá TransportMedium::Unknown. Véase también QNetworkInformation::TransportMedium.
QNetworkInformation::Feature::Metered0x8Si el complemento es compatible con esta función, la propiedad isMetered proporcionará resultados útiles. En caso contrario, siempre devolverá false.

El tipo Features es un typedef para QFlags<Feature>. Almacena una combinación OR de valores Feature.

enum class QNetworkInformation::Reachability

ConstanteValorDescripción
QNetworkInformation::Reachability::Unknown0Si se devuelve este valor, es posible que estemos conectados pero que el sistema operativo aún no haya confirmado la conectividad total, o que esta función no esté soportada.
QNetworkInformation::Reachability::Disconnected1Indica que el sistema puede no tener conectividad en absoluto.
QNetworkInformation::Reachability::Local2Indica que el sistema está conectado a una red, pero es posible que sólo pueda acceder a los dispositivos de la red local.
QNetworkInformation::Reachability::Site3Indica que el sistema está conectado a una red, pero es posible que sólo pueda acceder a los dispositivos de la subred local o de una intranet.
QNetworkInformation::Reachability::Online4Indica que el sistema está conectado a una red y puede acceder a Internet.

Véase también QNetworkInformation::reachability.

[since 6.3] enum class QNetworkInformation::TransportMedium

Enumera los medios reconocidos actualmente con los que uno puede conectarse a Internet.

ConstanteValorDescripción
QNetworkInformation::TransportMedium::Unknown0Devuelto si el sistema operativo informa que no hay medio activo, el medio activo no es reconocido por Qt, o la característica TransportMedium no está soportada.
QNetworkInformation::TransportMedium::Ethernet1Indica que la conexión actualmente activa está usando ethernet. Nota: Este valor también puede ser devuelto cuando Windows está conectado a una red de área personal Bluetooth.
QNetworkInformation::TransportMedium::Cellular2Indica que la conexión activa actualmente utiliza una red celular.
QNetworkInformation::TransportMedium::WiFi3Indica que la conexión activa actualmente está utilizando Wi-Fi.
QNetworkInformation::TransportMedium::Bluetooth4Indica que la conexión activa actualmente está utilizando Bluetooth.

Este enum se introdujo en Qt 6.3.

Véase también QNetworkInformation::transportMedium.

Documentación de propiedades

[read-only, since 6.2] isBehindCaptivePortal : bool

Le permite saber si el dispositivo del usuario está detrás de un portal cautivo.

Esta propiedad indica si se sabe que el dispositivo del usuario está detrás de un portal cautivo. Esta funcionalidad depende de la detección de portales cautivos por parte del sistema operativo y no está soportada en sistemas que no informan de ello. En los sistemas en los que no esté soportada, siempre devolverá false.

Esta propiedad se introdujo en Qt 6.2.

Funciones de acceso:

bool isBehindCaptivePortal() const

Señal de notificador:

void isBehindCaptivePortalChanged(bool state)

[read-only, since 6.3] isMetered : bool

Comprobar si la conexión actual tiene contador

Esta propiedad devuelve si la conexión actual es de pago o no. Puedes usar esto como un factor guía para decidir si tu aplicación debe realizar ciertas peticiones o subidas a la red. Por ejemplo, puede que no quieras subir logs o diagnósticos mientras esta propiedad esté en 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(); } ... }

Esta propiedad se introdujo en Qt 6.3.

Funciones de acceso:

bool isMetered() const

Señal de notificador:

void isMeteredChanged(bool isMetered)

[read-only] reachability : Reachability

Esta propiedad contiene el estado actual de la conectividad de red del sistema.

Indica el nivel de conectividad que se puede esperar. Tenga en cuenta que esto sólo se basa en lo que informa el plugin/sistema operativo. En algunos casos, se sabe que es incorrecto. Por ejemplo, en Windows la comprobación 'Online', por defecto, la realiza Windows conectándose a un servidor propiedad de Microsoft. Si este servidor está bloqueado por alguna razón, asumirá que no tiene accesibilidad en línea. Por este motivo, no debe utilizar esta opción como comprobación previa antes de intentar establecer una conexión.

Funciones de acceso:

QNetworkInformation::Reachability reachability() const

Notificador de señal:

void reachabilityChanged(QNetworkInformation::Reachability newReachability)

[read-only, since 6.3] transportMedium : TransportMedium

Esta propiedad contiene el medio de transporte actualmente activo para la aplicación

Esta propiedad devuelve el medio de transporte actualmente activo para la aplicación, en sistemas operativos donde dicha información esté disponible.

Cuando el medio de transporte actual cambia se emite una señal, esto puede ocurrir, por ejemplo, cuando un usuario sale del alcance de una red WiFi, desenchufa su cable ethernet o activa el modo Avión.

Esta propiedad se introdujo en Qt 6.3.

Funciones de acceso:

QNetworkInformation::TransportMedium transportMedium() const

Señal de notificador:

void transportMediumChanged(QNetworkInformation::TransportMedium current)

Documentación de funciones miembro

[static] QStringList QNetworkInformation::availableBackends()

Devuelve una lista con los nombres de todos los backends disponibles actualmente.

QString QNetworkInformation::backendName() const

Devuelve el nombre del backend cargado actualmente.

[static] QNetworkInformation *QNetworkInformation::instance()

Devuelve un puntero a la instancia de QNetworkInformation, si existe. Si se llama a este método antes de que se haya cargado un backend, devuelve un puntero nulo.

Véase también loadBackendByName(), loadDefaultBackend() y loadBackendByFeatures().

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

Carga un backend compatible con features.

Devuelve true si consiguió cargar el backend solicitado o si ya estaba cargado. En caso contrario, devuelve false.

Esta función se introdujo en Qt 6.4.

Véase también instance.

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

Intenta cargar un servidor cuyo nombre coincida con backend (sin distinguir mayúsculas de minúsculas).

Devuelve true si consiguió cargar el backend solicitado o si ya estaba cargado. En caso contrario, devuelve false.

Esta función se introdujo en Qt 6.4.

Véase también instance.

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

Intenta cargar el backend por defecto de la plataforma.

Nota: A partir de 6.7 se intenta cargar cualquier backend que soporte Reachability si el backend por defecto de la plataforma no está disponible o falla al cargar. Si esto también falla, volverá a un backend que sólo devuelva los valores por defecto para todas las propiedades.

Esta asignación de plataforma a plugin es la siguiente:

PlataformaNombre del plugin
Windowsnetworklistmanager
Apple (macOS/iOS)aplicación de información de red
Androidandroid
Linuxgestor de red

Esta función se proporciona por conveniencia cuando la lógica anterior es suficientemente buena. Si necesita un complemento específico, deberá llamar directamente a loadBackendByName() o loadBackendByFeatures().

Determina un backend adecuado para cargar y devuelve true si este backend ya está cargado o al cargarlo con éxito. Devuelve false si cualquier otro backend ya ha sido cargado, o si la carga del backend seleccionado falla.

Esta función se introdujo en Qt 6.3.

Véase también instance(), loadBackendByName(), y loadBackendByFeatures().

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

Devuelve todas las características soportadas del backend actual.

Esta función se introdujo en Qt 6.3.

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

Devuelve true si el backend cargado actualmente admite 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.