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
(since 6.2)isBehindCaptivePortal : bool(since 6.3)isMetered : bool- reachability : Reachability
(since 6.3)transportMedium : TransportMedium
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().
| Constante | Valor | Descripción |
|---|---|---|
QNetworkInformation::Feature::Reachability | 0x1 | Si 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::CaptivePortal | 0x2 | Si el complemento es compatible con esta función, la propiedad isBehindCaptivePortal proporcionará resultados útiles. En caso contrario, siempre devolverá false. |
QNetworkInformation::Feature::TransportMedium | 0x4 | Si 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::Metered | 0x8 | Si 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
| Constante | Valor | Descripción |
|---|---|---|
QNetworkInformation::Reachability::Unknown | 0 | Si 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::Disconnected | 1 | Indica que el sistema puede no tener conectividad en absoluto. |
QNetworkInformation::Reachability::Local | 2 | Indica 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::Site | 3 | Indica 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::Online | 4 | Indica 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.
| Constante | Valor | Descripción |
|---|---|---|
QNetworkInformation::TransportMedium::Unknown | 0 | Devuelto 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::Ethernet | 1 | Indica 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::Cellular | 2 | Indica que la conexión activa actualmente utiliza una red celular. |
QNetworkInformation::TransportMedium::WiFi | 3 | Indica que la conexión activa actualmente está utilizando Wi-Fi. |
QNetworkInformation::TransportMedium::Bluetooth | 4 | Indica 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:
| Plataforma | Nombre del plugin |
|---|---|
| Windows | networklistmanager |
| Apple (macOS/iOS) | aplicación de información de red |
| Android | android |
| Linux | gestor 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.