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 : const bool(since 6.3)
isMetered : const bool- reachability : const Reachability
(since 6.3)
transportMedium : const 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::Reachability::Disconnected: qDebug() << "Network is disconnected."; break;caseQNetworkInformation::Reachability::Local: qDebug() << "Network is locally reachable."; break;caseQNetworkInformation::Reachability::Site: qDebug() << "Network can reach the site."; break;caseQNetworkInformation::Reachability::Online: qDebug() << "Network is online."; break; } }intmain(intargc, char *argv[]) { QCoreApplicationa(argc,argv);// 检查是否支持 QNetworkInformation if(!QNetworkInformation::loadDefaultBackend()) { qWarning() << "QNetworkInformation is not supported on this platform or backend."; 返回 1; } QNetworkInformation* netInfo=QNetworkInformation::instance();// 连接到 reachabilityChanged 信号 QObject连接(netInfo, &QNetworkInformation::reachabilityChanged, &onReachabilityChanged);// 打印初始状态onReachabilityChanged(netInfo->reachability());returna.exec(); }
对于更高级的用例,开发人员可能更喜欢根据特定功能或偏好加载后端。loadBackendByFeatures() 允许选择支持特定功能的后端,例如报告传输介质或信号强度。另外,loadBackendByName() 允许根据插件名称加载插件,其中可包括特定平台或自定义后端实现。
QNetworkInformation 是一个单例,从首次成功加载到QCoreApplication 对象被销毁,它一直都是存活的。如果销毁并重新创建QCoreApplication 对象,则必须再次加载该对象以重新初始化插件。
注意: 由于该类是一个单例,同时也依赖于QCoreApplication ,因此 QNetworkInformation 应始终首先在与QCoreApplication 对象相同的线程中加载。这是因为该对象也将在该线程中销毁,而各种特定于后端组件可能依赖于在创建该对象时在同一线程中销毁。
QNetworkInformation 的一个可能用例是监控网络连接状态。reachability(QNetworkInformation()根据底层操作系统或插件报告的信息,提供系统是否在线的指示。不过,这些信息不一定总是准确的。例如,在 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 地址(默认:谷歌 DNS QStringtargetIpStr=argc> 1 ?argv[1]:"8.8.8.8"; QHostAddresstargetIp(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)? "本地/站点。:"外部/在线"); qDebug() << "Required reachability level:" << requiredReachability; qDebug() << "Current reachability:" << currentReachability; 如果(currentReachability<requiredReachability) { qWarning() << "Current network state may not allow reaching the target address."; 否则{ qDebug() << "Target may be reachable based on current network state."; } ...
另请参见 QNetworkInformation::Feature 。
成员类型文档
枚举类 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 。 |
特征类型是QFlags<Feature> 的类型定义。它存储特征值的 OR 组合。
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 : const bool
让你知道用户的设备是否在安全门户后面。
该属性显示用户的设备当前是否处于安全门户之后。该功能依赖于操作系统对自带门户的检测,不支持不报告自带门户的系统。在不支持此功能的系统上,将始终返回false
。
此属性在 Qt 6.2 中引入。
访问功能:
bool | isBehindCaptivePortal() const |
Notifier 信号:
void | isBehindCaptivePortalChanged(bool state) |
[read-only, since 6.3]
isMetered : const bool
检查当前连接是否已计量
此属性返回当前连接是否(已知)已计量。您可以将此作为指导因素,决定应用程序是否应执行某些网络请求或上传。例如,当该属性为true
时,您可能不想上传日志或诊断信息。
voiduploadLogFile() { ... }intmain(intargc, char *argv[]) { QCoreApplicationapp(argc,argv); ...if(netInfo->isMetered()) { qWarning() << "Log upload skipped: Current network is metered."; app.quit(); }else{ uploadLogFile(); } ... }
此属性在 Qt 6.3 中引入。
访问函数:
bool | isMetered() const |
Notifier 信号:
void | isMeteredChanged(bool isMetered) |
[read-only]
reachability : const Reachability
该属性显示系统网络连接的当前状态。
表示可预期的连接水平。请注意,这只是基于插件/操作系统的报告。在某些情况下,这可能是错误的。例如,在 Windows 系统中,"在线 "检查默认由 Windows 连接到 Microsoft 所有的服务器进行。如果该服务器由于某种原因被阻塞,那么它就会假定自己不具备 "联机 "能力。因此,在尝试进行连接之前,不应将其用作预先检查。
访问功能:
QNetworkInformation::Reachability | reachability() const |
通知信号:
void | reachabilityChanged(QNetworkInformation::Reachability newReachability) |
[read-only, since 6.3]
transportMedium : const TransportMedium
该属性保存应用程序当前活动的传输介质。
在有此类信息的操作系统上,该属性会返回应用程序当前使用的传输介质。
例如,当用户离开WiFi 网络范围、拔下以太网电缆或启用飞行模式时,当前传输介质就会发生变化。
此属性在 Qt 6.3 中引入。
访问功能:
QNetworkInformation::TransportMedium | transportMedium() const |
Notifier 信号:
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 的后端。如果加载失败,它将退回到只返回所有属性默认值的后端。
平台到插件的映射如下:
平台 | 插件名称 |
---|---|
平台 | 网络列表管理器 |
苹果(macOS/iOS) | 应用程序网络信息 |
安卓 | 安卓 |
Linux | 网络管理员 |
提供该函数是为了方便使用,因为前面的逻辑已经足够好了。如果需要特定插件,则应直接调用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
。
© 2025 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.