En esta página

QNetworkInformation Class

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

Encabezado: #include <QNetworkInformation>
CMake: find_package(Qt6 REQUIRED COMPONENTS Network)
target_link_libraries(mytarget PRIVATE Qt6::Network)
qmake: QT += network
Desde: Qt 6.1
Heredan de: 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 para acceder a información relacionada con la red a través de complementos.

Los distintos complementos pueden admitir diversas funcionalidades, por lo que puedes cargar los complementos en función de las características que necesites.

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

#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::Accesibilidad::Desconectado:
        qDebug() << "Network is disconnected.";
       break;
    case QNetworkInformation::Accesibilidad::Local:
        qDebug() << "Network is locally reachable.";
       break;
    case QNetworkInformation::Accesibilidad::Sitio:
        qDebug() << "Network can reach the site.";
       break;
    case QNetworkInformation::Accesibilidad::En línea:
        qDebug() << "Network is online.";
       break;
    }
}

int main(int argc, char *argv[]) {
    QCoreApplication a(argc, argv);

    // Comprueba si se admite QNetworkInformation
    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);

    // Mostrar el estado inicial
    onReachabilityChanged(netInfo->reachability());

    return a.exec();
}

Para casos de uso más avanzados, es posible que los desarrolladores prefieran cargar un backend en función de capacidades o preferencias específicas. loadBackendByFeatures() permite seleccionar un backend que admita un conjunto específico de características, como informar del medio de transporte o de la intensidad de la señal. Por otra parte, loadBackendByName() permite cargar un complemento por su nombre, lo que puede incluir implementaciones de backend específicas de la plataforma o personalizadas.

QNetworkInformation es un singleton y permanece activo desde la primera carga satisfactoria hasta la destrucción del objeto ` QCoreApplication `. Si destruyes y vuelves a crear el objeto ` QCoreApplication `, debes volver a cargarlo para reinicializar el complemento.

Nota: Dado que la clase es un singleton y, al mismo tiempo, 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 hilo, y es posible que varios componentes específicos del backend dependan de que se destruyan en el mismo hilo en el que se crearon.

Un posible caso de uso de QNetworkInformation es supervisar el estado de conectividad de red. reachability() proporciona una indicación de si el sistema se considera en línea, basándose en la información facilitada por el sistema operativo subyacente o el complemento. Sin embargo, es posible que esta información no sea siempre precisa. Por ejemplo, en Windows, la comprobación de conexión puede basarse en la conectividad con un servidor propiedad de Microsoft; si no se puede acceder a ese servidor (por ejemplo, debido a las reglas del cortafuegos), el sistema puede indicar erróneamente que está desconectado. Por lo tanto, reachability() no debe utilizarse como una comprobación previa definitiva antes de intentar establecer una conexión de red, sino más bien como una indicación general del estado de conectividad.

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

Advertencia: Solo Linux y Windows admiten las opciones más detalladas « Reachability::Site » y « Reachability::Local ». En las plataformas de Android y Apple, « reachability()» se limita a informar únicamente de «En línea», «Fuera de línea» o «Desconocido». Por lo tanto, cualquier lógica que se base en la detección de la conectividad a nivel local o de sitio debe incluir comprobaciones adecuadas para cada plataforma o soluciones alternativas.

// Función auxiliar sencilla para determinar 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: DNS de Google)
    QString targetIpStr = argc > 1 ? argv[1]: "8.8.8.8";
    QHostAddress targetIp(targetIpStr);

    if (targetIp.isNull()) {
        qWarning() << "Invalid IP address:" << targetIpStr;
       return 1;
    }

    // Determinar qué nivel de accesibilidad se necesita para el destino
    QNetworkInformation::Reachability requiredReachability =
        isLocalAddress(targetIp)
            ? QNetworkInformation::Reachability::Local
            : QNetworkInformation::Reachability::Online;

    // Obtiene la accesibilidad actual informada por el sistema
    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 (alcanceActual < alcanceRequerido) {
        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 sobre tipos de miembros

enum class QNetworkInformation::Feature
flags QNetworkInformation::Features

Enumera todas las funciones que un complemento puede admitir actualmente. Se puede utilizar en QNetworkInformation::loadBackendByFeatures().

ConstanteValorDescripción
QNetworkInformation::Feature::Reachability0x1Si el complemento admite esta función, la propiedad reachability proporcionará resultados útiles. De lo contrario, siempre devolverá Reachability::Unknown. Véase también QNetworkInformation::Reachability.
QNetworkInformation::Feature::CaptivePortal0x2Si el complemento admite esta función, la propiedad isBehindCaptivePortal proporcionará resultados útiles. De lo contrario, siempre devolverá false.
QNetworkInformation::Feature::TransportMedium0x4Si el complemento admite esta función, la propiedad transportMedium proporcionará resultados útiles. De lo contrario, siempre devolverá TransportMedium::Unknown. Véase también QNetworkInformation::TransportMedium.
QNetworkInformation::Feature::Metered0x8Si el complemento admite esta característica, la propiedad « isMetered » proporcionará resultados útiles. De lo contrario, siempre devolverá « false ».

El tipo «Features» es una definición de tipo (typedef) para QFlags<Feature>. Almacena una combinación «O» de valores de «Feature».

enum class QNetworkInformation::Reachability

ConstanteValorDescripción
QNetworkInformation::Reachability::Unknown0Si se devuelve este valor, es posible que estemos conectados, pero el sistema operativo aún no ha confirmado la conectividad total, o bien esta función no es compatible.
QNetworkInformation::Reachability::Disconnected1Indica que es posible que el sistema no tenga ninguna conectividad.
QNetworkInformation::Reachability::Local2Indica que el sistema está conectado a una red, pero es posible que solo pueda acceder a dispositivos de la red local.
QNetworkInformation::Reachability::Site3Indica que el sistema está conectado a una red, pero es posible que solo pueda acceder a 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 dispositivos actualmente compatibles con los que se puede conectarse a Internet.

ConstanteValorDescripción
QNetworkInformation::TransportMedium::Unknown0Se devuelve si el sistema operativo no detecta ningún medio activo, si Qt no reconoce el medio activo o si la característica TransportMedium no es compatible.
QNetworkInformation::TransportMedium::Ethernet1Indica que la conexión actualmente activa utiliza Ethernet. Nota: Este valor también puede devolverse cuando Windows está conectado a una red de área personal Bluetooth.
QNetworkInformation::TransportMedium::Cellular2Indica que la conexión activa actualmente utiliza una red móvil.
QNetworkInformation::TransportMedium::WiFi3Indica que la conexión activa actualmente utiliza Wi-Fi.
QNetworkInformation::TransportMedium::Bluetooth4Indica que la conexión activa actualmente está conectada mediante Bluetooth.

Esta enumeración se introdujo en Qt 6.3.

Véase también QNetworkInformation::transportMedium.

Documentación de la propiedad

[read-only, since 6.2] isBehindCaptivePortal : bool

Indica si el dispositivo del usuario se encuentra detrás de un portal cautivo.

Esta propiedad indica si se sabe que el dispositivo del usuario se encuentra actualmente detrás de un portal cautivo. Esta funcionalidad se basa en la detección de portales cautivos por parte del sistema operativo y no es compatible con sistemas que no informen de ello. En los sistemas en los que no sea compatible, siempre devolverá « false ».

Esta enumeración 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

Comprueba si la conexión actual es de tarifa por consumo

Esta propiedad indica si la conexión actual es (según se sabe) de pago o no. Puede utilizar esta información como guía para decidir si su aplicación debe realizar determinadas solicitudes de red o cargas. Por ejemplo, es posible que no desee cargar registros o datos de diagnóstico 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 enumeración se introdujo en Qt 6.3.

Funciones de acceso:

bool isMetered() const

Señal «Notifier»:

void isMeteredChanged(bool isMetered)

[read-only] reachability : Reachability

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

Indica el nivel de conectividad que cabe esperar. Ten en cuenta que esto se basa únicamente en la información que facilitan el complemento o el sistema operativo. Se sabe que, en determinados casos, esta información puede ser errónea. Por ejemplo, en Windows, la comprobación de «En línea», de forma predeterminada, se realiza mediante la conexión de Windows a un servidor propiedad de Microsoft. Si este servidor está bloqueado por cualquier motivo, se asumirá que no hay accesibilidad en línea. Por este motivo, no debes utilizar esta información como comprobación previa antes de intentar establecer una conexión.

Funciones de acceso:

QNetworkInformation::Reachability reachability() const

Señal del notificador:

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 los sistemas operativos en los que dicha información está disponible.

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

Esta enumeración se introdujo en Qt 6.3.

Funciones de acceso:

QNetworkInformation::TransportMedium transportMedium() const

Señal del 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 invoca 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 ha conseguido 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 backend cuyo nombre coincida con « backend » (sin distinguir entre mayúsculas y minúsculas).

Devuelve true si ha conseguido 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 predeterminado de la plataforma.

Nota: A partir de la versión 6.7, si el backend predeterminado de la plataforma no está disponible o no se carga correctamente, se intenta cargar cualquier backend que admita Reachability. Si esto tampoco funciona, se recurrirá a un backend que solo devuelva los valores predeterminados para todas las propiedades.

Esta correspondencia entre la plataforma y los complementos es la siguiente:

PlataformaNombre del complemento
Windowsnetworklistmanager
Apple (macOS/iOS)applenetworkinformation
Androidandroid
Linuxnetworkmanager

Esta función se proporciona por comodidad cuando la lógica anterior es suficiente. Si necesitas un complemento específico, debes llamar directamente a loadBackendByName() o loadBackendByFeatures() en su lugar.

Determina un backend adecuado para cargar y devuelve true si este backend ya está cargado o si su carga se ha realizado correctamente. Devuelve false si ya se ha cargado cualquier otro backend, o si falla la carga del backend seleccionado.

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 funciones compatibles con el 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.