QNetworkInformation Class
QNetworkInformation 通过原生后端提供各种网络信息。更多内容...
| 头文件: | #include <QNetworkInformation> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Network) target_link_libraries(mytarget PRIVATE Qt6::Network) |
| qmake: | QT += network |
| 自: | Qt 6.1 |
| 继承自: | QObject |
公共类型
| 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 } |
属性
(since 6.2)isBehindCaptivePortal : bool(since 6.3)isMetered : bool- reachability : Reachability
(since 6.3)transportMedium : TransportMedium
公共函数
| 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 |
信号
| void | isBehindCaptivePortalChanged(bool state) |
| void | isMeteredChanged(bool isMetered) |
| void | reachabilityChanged(QNetworkInformation::Reachability newReachability) |
| void | transportMediumChanged(QNetworkInformation::TransportMedium current) |
静态公共成员
| QStringList | availableBackends() |
| QNetworkInformation * | instance() |
(since 6.4) bool | loadBackendByFeatures(QNetworkInformation::Features features) |
(since 6.4) bool | loadBackendByName(QStringView backend) |
(since 6.3) bool | loadDefaultBackend() |
详细说明
QNetworkInformation 通过插件提供了一个跨平台的网络相关信息接口。
不同的插件可能支持不同的功能,因此您可以根据所需的功能来加载相应的插件。
在大多数情况下,推荐的做法是通过调用 `loadDefaultBackend()` 来加载特定于该平台的后端。这将自动选择当前平台上最合适的后端,并适用于绝大多数应用程序。
#include <QCoreApplication>
#include <QNetworkInformation>
#include <QDebug>
voidonReachabilityChanged(QNetworkInformation::Reachability reachability) {
switch(reachability) {
caseQNetworkInformation::Reachability::Unknown:
qDebug() << "Network reachability is unknown.";
break;
caseQNetworkInformation::可达性::断开连接:
qDebug() << "Network is disconnected.";
break;
caseQNetworkInformation::可达性::本地:
qDebug() << "Network is locally reachable.";
break;
caseQNetworkInformation::可达性::站点:
qDebug() << "Network can reach the site.";
break;
caseQNetworkInformation::可达性::在线:
qDebug() << "Network is online.";
break;
}
}
intmain(intargc, char *argv[]) {
QCoreApplication a(argc,argv);
// 检查是否支持 QNetworkInformation
if(!QNetworkInformation::loadDefaultBackend()) {
qWarning() << "QNetworkInformation is not supported on this platform or backend.";
return 1;
}
QNetworkInformation*netInfo=QNetworkInformation::instance();
// 连接到 reachabilityChanged 信号
QObject::connect(netInfo, &QNetworkInformation::reachabilityChanged,
&onReachabilityChanged);
// 打印初始状态
onReachabilityChanged(netInfo->reachability());
returna.exec();
}对于更高级的应用场景,开发者可能更倾向于根据特定的功能或偏好加载后端。loadBackendByFeatures() 允许选择支持特定功能集的后端,例如报告传输介质或信号强度。此外,loadBackendByName() 允许按名称加载插件,其中可包含特定于平台或自定义的后端实现。
QNetworkInformation 是一个单例,从首次成功加载起一直存在,直至QCoreApplication 对象被销毁。如果您销毁并重新创建了QCoreApplication 对象,则必须重新加载它以重新初始化该插件。
注意:由于 该类既是单例,又依赖于QCoreApplication ,因此 应始终在与QCoreApplication 对象相同的线程中首先加载QNetworkInformation。这是因为该对象也将在该线程中被销毁,而各种后端特有的组件可能依赖于在与创建时相同的线程中被销毁。
QNetworkInformation 的一个可能用例是监控网络连接状态。reachability() 基于底层操作系统或插件报告的信息,指示系统是否被视为在线。但是,此信息可能并不总是准确的。 例如,在 Windows 系统中,在线检查可能依赖于与微软自有服务器的连接;如果该服务器不可达(例如由于防火墙规则),系统可能会错误地报告为离线状态。 因此,不应将reachability() 作为尝试建立网络连接前的最终预检查,而应将其视为连接状态的一般性指示。
要有效使用reachability(),应用程序还必须了解其试图连接的目标属于何种类型。例如,如果目标是本地 IP 地址,那么Reachability::Local 或Reachability::Site 可能就足够了。如果目标位于公共互联网上,则需要使用Reachability::Online 。如果没有这一背景信息,对报告的可达性进行解读可能会导致对实际网络访问产生错误的假设。
警告:仅 Linux 和 Windows 支持更细粒度的Reachability::Site 和Reachability::Local 选项。在 Android 和 Apple 平台上,reachability() 仅限于报告“在线”、“离线”或“未知”状态。因此,任何依赖检测本地或站点级连接性的逻辑都必须包含相应的平台检查或备用方案。
// 用于判断 IP 地址是否为“本地”的简单辅助函数
boolisLocalAddress(constQHostAddress&address)
{
returnaddress.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();
}
intmain(intargc, char *argv[])
{
...
// 目标 IP 地址(默认: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;
}
// 确定目标所需的可达性级别
QNetworkInformation::Reachability requiredReachability=
isLocalAddress(targetIp)
?QNetworkInformation::Reachability::Local
: QNetworkInformation::Reachability::Online;
// 获取系统报告的当前可达性
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(当前可达性<所需可达性) {
qWarning() << "Current network state may not allow reaching the target address.";
}else{
qDebug() << "Target may be reachable based on current network state.";
}
...另请参阅 QNetworkInformation::Feature 。
成员类型文档
enum class QNetworkInformation::Feature
flags QNetworkInformation::Features
列出了插件当前可能支持的所有功能。可在QNetworkInformation::loadBackendByFeatures() 中使用。
| 常量 | 值 | 描述 |
|---|---|---|
QNetworkInformation::Feature::Reachability | 0x1 | 如果插件支持此功能,则reachability 属性将返回有用的结果。否则,它将始终返回Reachability::Unknown 。另请参阅QNetworkInformation::Reachability 。 |
QNetworkInformation::Feature::CaptivePortal | 0x2 | 如果插件支持此功能,则isBehindCaptivePortal 属性将提供有用的结果。否则,它将始终返回false 。 |
QNetworkInformation::Feature::TransportMedium | 0x4 | 如果插件支持此功能,则transportMedium 属性将返回有用的结果。否则,它将始终返回TransportMedium::Unknown 。另请参阅QNetworkInformation::TransportMedium 。 |
QNetworkInformation::Feature::Metered | 0x8 | 如果插件支持此功能,则isMetered 属性将提供有用的结果。否则,它将始终返回false 。 |
“Features”类型是QFlags<Feature> 的 typedef 定义。它存储了 Feature 值的“或”组合。
enum class QNetworkInformation::Reachability
| 常数 | 值 | 描述 |
|---|---|---|
QNetworkInformation::Reachability::Unknown | 0 | 如果返回此值,则可能已建立连接,但操作系统尚未确认完全连接,或者不支持此功能。 |
QNetworkInformation::Reachability::Disconnected | 1 | 表示系统可能完全无法连接。 |
QNetworkInformation::Reachability::Local | 2 | 表示系统已连接到网络,但可能只能访问本地网络上的设备。 |
QNetworkInformation::Reachability::Site | 3 | 表示系统已连接到网络,但可能只能访问本地子网或内网中的设备。 |
QNetworkInformation::Reachability::Online | 4 | 表示系统已连接到网络,并且能够访问互联网。 |
另请参阅 QNetworkInformation::reachability 。
[since 6.3] enum class QNetworkInformation::TransportMedium
列出了当前支持用于连接互联网的设备。
| 常量 | 值 | 描述 |
|---|---|---|
QNetworkInformation::TransportMedium::Unknown | 0 | 当操作系统报告没有活动介质、Qt 无法识别活动介质,或者不支持 TransportMedium 功能时,将返回此值。 |
QNetworkInformation::TransportMedium::Ethernet | 1 | 表示当前活动的连接正在使用以太网。注意:当 Windows 连接到蓝牙个人区域网络时,也可能返回此值。 |
QNetworkInformation::TransportMedium::Cellular | 2 | 表示当前活动的连接正在使用蜂窝网络。 |
QNetworkInformation::TransportMedium::WiFi | 3 | 表示当前活动的连接使用的是 Wi-Fi。 |
QNetworkInformation::TransportMedium::Bluetooth | 4 | 表示当前活动的连接是通过蓝牙建立的。 |
该枚举在 Qt 6.3 中引入。
属性文档
[read-only, since 6.2] isBehindCaptivePortal : bool
用于告知用户的设备是否位于捕获门户之后。
该属性指示是否已知用户设备当前位于捕获门户之后。此功能依赖于操作系统对捕获门户的检测,在不报告此信息的系统上不被支持。在不支持此功能的系统上,该属性将始终返回false 。
该枚举类型于 Qt 6.2 中引入。
访问函数:
| bool | isBehindCaptivePortal() const |
通知器信号:
| void | isBehindCaptivePortalChanged(bool state) |
[read-only, since 6.3] isMetered : bool
检查当前连接是否为计费连接
该属性返回当前连接是否(已知)受流量限制。您可以将其作为参考因素,以决定应用程序是否应执行某些网络请求或上传操作。例如,当该属性值为true 时,您可能不希望上传日志或诊断信息。
voiduploadLogFile()
{
...
}
intmain(intargc, char *argv[])
{
QCoreApplication app(argc,argv);
...
if(netInfo->isMetered()) {
qWarning() << "Log upload skipped: Current network is metered.";
app.quit();
}else{
uploadLogFile();
}
...
}该枚举在 Qt 6.3 中引入。
访问函数:
| bool | isMetered() const |
通知器信号:
| void | isMeteredChanged(bool isMetered) |
[read-only] reachability : Reachability
该属性存储系统当前的网络连接状态。
该属性指示可预期的连接级别。请注意,此信息仅基于插件/操作系统报告的数据。在某些情况下,该信息可能会出现错误。 例如,在 Windows 系统中,默认情况下,“在线”状态的验证是通过 Windows 连接到微软自有服务器来完成的。如果该服务器因任何原因被屏蔽,系统将默认认为无法访问在线状态。因此,在尝试建立连接前,不应将此作为预先检查。
访问功能:
| QNetworkInformation::Reachability | reachability() const |
通知信号:
| void | reachabilityChanged(QNetworkInformation::Reachability newReachability) |
[read-only, since 6.3] transportMedium : TransportMedium
该属性存储应用程序当前活动的传输介质
在可获取此类信息的操作系统上,该属性会返回应用程序当前活动的传输介质。
当当前传输介质发生变化时,会触发一个信号;例如,当用户离开WiFi 网络的覆盖范围、拔出以太网线或启用飞行模式时,就会发生这种情况。
该枚举类型于 Qt 6.3 中引入。
访问函数:
| QNetworkInformation::TransportMedium | transportMedium() const |
通知器信号:
| void | transportMediumChanged(QNetworkInformation::TransportMedium current) |
成员函数文档
[static] QStringList QNetworkInformation::availableBackends()
返回一个包含当前所有可用后端名称的列表。
QString QNetworkInformation::backendName() const
返回当前加载的后端的名称。
[static] QNetworkInformation *QNetworkInformation::instance()
返回指向QNetworkInformation 实例的指针(如有)。如果在加载后端之前调用此方法,则返回空指针。
另请参阅 loadBackendByName()、loadDefaultBackend() 以及loadBackendByFeatures()。
[static, since 6.4] bool QNetworkInformation::loadBackendByFeatures(QNetworkInformation::Features features)
加载一个支持features 的后端。
如果成功加载了请求的后端,或者该后端已加载,则返回true 。否则返回false 。
该函数自 Qt 6.4 起引入。
另请参阅 instance 。
[static, since 6.4] bool QNetworkInformation::loadBackendByName(QStringView backend)
尝试加载名称与backend 匹配(不区分大小写)的后端。
如果成功加载了请求的后端,或者该后端已加载,则返回true 。否则返回false 。
该函数在 Qt 6.4 中引入。
另请参阅 instance 。
[static, since 6.3] bool QNetworkInformation::loadDefaultBackend()
尝试加载平台默认后端。
注意:从 6.7版本开始,如果 平台默认后端不可用或加载失败,系统将尝试加载任何支持 `Reachability ` 的后端。如果此操作也失败,则会回退到一个仅为所有属性返回默认值的后端。
该平台到插件的映射关系如下:
| 平台 | 插件名称 |
|---|---|
| Windows | networklistmanager |
| Apple (macOS/iOS) | Apple网络信息 |
| Android | Android |
| Linux | networkmanager |
此函数仅为方便起见而提供,此前所述的逻辑已足够完善。若您需要特定的插件,则应直接调用loadBackendByName() 或loadBackendByFeatures()。
确定要加载的合适后端,并在该后端已加载或加载成功时返回true 。如果已加载任何其他后端,或者所选后端的加载失败,则返回false 。
该函数于 Qt 6.3 中引入。
另请参阅 instance()、loadBackendByName() 和loadBackendByFeatures()。
[since 6.3] QNetworkInformation::Features QNetworkInformation::supportedFeatures() const
返回当前后端支持的所有功能。
该函数于 Qt 6.3 中引入。
bool QNetworkInformation::supports(QNetworkInformation::Features features) const
如果当前加载的后端支持features ,则返回true 。
© 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.