QDnsLookup Class
QDnsLookup 类表示 DNS 查询。更多
Header: | #include <QDnsLookup> |
CMake.QDnsLookup | find_package(Qt6 REQUIRED COMPONENTS Network) target_link_libraries(mytarget PRIVATE Qt6::Network) |
qmake: | QT += network |
继承: | QObject |
- 所有成员(包括继承成员)的列表
- QDnsLookup 是网络编程 API 的一部分。
公共类型
enum | Error { NoError, ResolverError, OperationCancelledError, InvalidRequestError, InvalidReplyError, …, TimeoutError } |
enum | Protocol { Standard, DnsOverTls } |
enum | Type { A, AAAA, ANY, CNAME, MX, …, TXT } |
属性
|
|
公共职能
QDnsLookup(QObject *parent = nullptr) | |
QDnsLookup(QDnsLookup::Type type, const QString &name, QObject *parent = nullptr) | |
QDnsLookup(QDnsLookup::Type type, const QString &name, const QHostAddress &nameserver, QObject *parent = nullptr) | |
(since 6.6) | QDnsLookup(QDnsLookup::Type type, const QString &name, const QHostAddress &nameserver, quint16 port, QObject *parent = nullptr) |
(since 6.8) | QDnsLookup(QDnsLookup::Type type, const QString &name, QDnsLookup::Protocol protocol, const QHostAddress &nameserver, quint16 port = 0, QObject *parent = nullptr) |
virtual | ~QDnsLookup() |
QBindable<QString> | bindableName() |
QBindable<QHostAddress> | bindableNameserver() |
QBindable<quint16> | bindableNameserverPort() |
QBindable<QDnsLookup::Protocol> | bindableNameserverProtocol() |
QBindable<QDnsLookup::Type> | bindableType() |
QList<QDnsDomainNameRecord> | canonicalNameRecords() const |
QDnsLookup::Error | error() const |
QString | errorString() const |
QList<QDnsHostAddressRecord> | hostAddressRecords() const |
bool | isAuthenticData() const |
bool | isFinished() const |
QList<QDnsMailExchangeRecord> | mailExchangeRecords() const |
QString | name() const |
QList<QDnsDomainNameRecord> | nameServerRecords() const |
QHostAddress | nameserver() const |
quint16 | nameserverPort() const |
QDnsLookup::Protocol | nameserverProtocol() const |
QList<QDnsDomainNameRecord> | pointerRecords() const |
QList<QDnsServiceRecord> | serviceRecords() const |
void | setName(const QString &name) |
(since 6.6) void | setNameserver(const QHostAddress &nameserver, quint16 port) |
void | setNameserver(const QHostAddress &nameserver) |
void | setNameserver(QDnsLookup::Protocol protocol, const QHostAddress &nameserver, quint16 port = 0) |
void | setNameserverPort(quint16 port) |
void | setNameserverProtocol(QDnsLookup::Protocol protocol) |
(since 6.8) void | setSslConfiguration(const QSslConfiguration &sslConfiguration) |
void | setType(QDnsLookup::Type) |
QSslConfiguration | sslConfiguration() const |
QList<QDnsTextRecord> | textRecords() const |
(since 6.8) QList<QDnsTlsAssociationRecord> | tlsAssociationRecords() const |
QDnsLookup::Type | type() const |
公共插槽
信号
void | finished() |
void | nameChanged(const QString &name) |
void | nameserverChanged(const QHostAddress &nameserver) |
void | nameserverPortChanged(quint16 port) |
void | nameserverProtocolChanged(QDnsLookup::Protocol protocol) |
void | typeChanged(QDnsLookup::Type type) |
静态公共成员
(since 6.8) quint16 | defaultPortForProtocol(QDnsLookup::Protocol protocol) |
(since 6.8) bool | isProtocolSupported(QDnsLookup::Protocol protocol) |
详细说明
QDnsLookup 使用操作系统提供的机制来执行 DNS 查找。要执行查询,您需要指定name 和type ,然后调用lookup() 槽。完成后将发出finished() 信号。
例如,您可以通过以下方式确定 XMPP 聊天客户端应连接给定域的哪些服务器:
void MyObject::lookupServers() { // Create a DNS lookup. dns = new QDnsLookup(this); connect(dns, &QDnsLookup::finished, this, &MyObject::handleServers); // Find the XMPP servers for gmail.com dns->setType(QDnsLookup::SRV); dns->setName("_xmpp-client._tcp.gmail.com"); dns->lookup(); }
请求完成后,您可以使用
voidMyObject::handleServers() {// 检查查找 是否 成功。QDnsLookup::NoError) { qWarning("DNS lookup failed"); const auto records = dns->serviceRecords();for(constQDnsServiceRecord&record: records) { ...} dns->deleteLater(); }
注: 如果只想查找与主机名相关联的 IP 地址,或与 IP 地址相关联的主机名,则应使用QHostInfo 。
DNS-over-TLS 和真实数据
QDnsLookup 支持某些平台上的 DNS-over-TLS(DoT,由RFC 7858 规定)。如果 Qt XML 中存在QSslSocket 支持,目前包括所有支持常规查询的 Unix 平台。要查询运行时是否支持,请使用isProtocolSupported() 。
在使用 DNS-over-TLS 时,QDnsLookup 只实施RFC 7858第 4.1 节中描述的 "Opportunistic Privacy Profile"(机会隐私配置文件)验证方法。在这种模式下,QDnsLookup(通过QSslSocket )只验证服务器是否出示了对所连接服务器有效的证书。客户端可使用setSslConfiguration() 施加额外限制,也可使用sslConfiguration() 在查询完成后获取信息。
QDnsLookup 会要求通过 TLS 查询的 DNS 服务器对其返回的数据执行身份验证。如果它们确认数据有效,authenticData 属性将被设置为 true。QDnsLookup 本身不会验证数据的完整性,因此应用程序只应信任通过其他方式确认可信的服务器。
不使用 TLS 的真实数据
即使不需要 TLS 加密,QDnsLookup 也会请求使用setNameserver() 设置的任何服务器的真实数据。这在查询与应用程序位于同一主机或可信网络上的缓存名称服务器时非常有用。虽然与 TLS 的情况类似,但应用程序要负责确定其选择使用的服务器是否可信,以及未加密连接是否无法篡改。
QDnsLookup 遵循系统配置,在默认名称服务器上请求真实数据(也就是说,如果setNameserver() 没有被调用)。目前只有使用 glibc 2.31 或更高版本的 Linux 系统才支持此功能。在其他系统上,QDnsLookup 将忽略查询头中的 AD 位。
成员类型文档
enum QDnsLookup::Error
表示在处理 DNS 查询过程中发现的所有可能的错误条件。
常数 | 值 | 说明 |
---|---|---|
QDnsLookup::NoError | 0 | 无错误条件。 |
QDnsLookup::ResolverError | 1 | 系统 DNS 解析器初始化出错。 |
QDnsLookup::OperationCancelledError | 2 | 使用abort() 方法中止了查询。 |
QDnsLookup::InvalidRequestError | 3 | 请求的 DNS 查询无效。 |
QDnsLookup::InvalidReplyError | 4 | 服务器返回的回复无效。 |
QDnsLookup::ServerFailureError | 5 | 服务器在处理请求时遇到内部故障 (SERVFAIL)。 |
QDnsLookup::ServerRefusedError | 6 | 服务器因安全或策略原因拒绝处理请求 (REFUSED)。 |
QDnsLookup::NotFoundError | 7 | 请求的域名不存在(NXDOMAIN)。 |
QDnsLookup::TimeoutError | 8 | 无法联系到服务器或服务器未及时回复(自 6.6 版起)。 |
enum QDnsLookup::Protocol
表示查询的 DNS 服务器类型。
常数 | 值 | 说明 |
---|---|---|
QDnsLookup::Standard | 0 | 常规、未加密 DNS,使用 UDP,必要时回退到 TCP(默认端口:53) |
QDnsLookup::DnsOverTls | 1 | 通过 TCP 的 TLS 加密 DNS(DoT,由RFC 7858 规定)(默认端口:853) |
另请参阅 isProtocolSupported()、nameserverProtocol 和setNameserver()。
enum QDnsLookup::Type
表示执行的 DNS 查询类型。
常数 | 值 | 说明 |
---|---|---|
QDnsLookup::A | 1 | IPv4 地址记录。 |
QDnsLookup::AAAA | 28 | IPv6 地址记录。 |
QDnsLookup::ANY | 255 | 任何记录。 |
QDnsLookup::CNAME | 5 | 规范名称记录。 |
QDnsLookup::MX | 15 | 邮件交换记录。 |
QDnsLookup::NS | 2 | 名称服务器记录。 |
QDnsLookup::PTR | 12 | 指针记录 |
QDnsLookup::SRV | 33 | 服务记录 |
QDnsLookup::TLSA (since Qt 6.8) | 52 | TLS 关联记录。 |
QDnsLookup::TXT | 16 | 文本记录 |
属性文档
[read-only, since 6.8]
authenticData : const bool
该属性表示回复是否经过解析器验证。
QDnsLookup 解析器本身不执行身份验证。相反,它相信被查询的名称服务器会执行验证并报告验证结果。应用程序负责确定其使用 () 配置的任何服务器是否可信;如果没有设置服务器, 会服从系统配置,确定是否应信任回复。setNameserver QDnsLookup
即使error() 显示发生了解析器错误,也可以设置该属性。
此属性在 Qt 6.8 中引入。
访问函数:
bool | isAuthenticData() const |
Notifier 信号:
void | finished() |
另请参见 setNameserver() 和nameserverProtocol()。
[read-only]
error : const Error
此属性保存 DNS 查找失败时发生的错误类型,或NoError 。
访问功能:
QDnsLookup::Error | error() const |
通知信号:
void | finished() |
[read-only]
errorString : const QString
如果 DNS 查找失败,该属性将保存可由人工读取的错误描述。
访问功能:
QString | errorString() const |
通知信号:
void | finished() |
[bindable]
name : QString
注意: 该属性支持QProperty 绑定。
该属性包含要查询的名称。
如果要查询的名称为空,QDnsLookup 将尝试解析 DNS 根域。该查询通常在QDnsLookup::type 设置为NS 时进行。
注意: 该名称将使用 IDNA 编码,这意味着它不适合查询与 DNS-SD 规范兼容的 SRV 记录。
[bindable]
nameserver : QHostAddress
注意: 该属性支持QProperty 绑定。
该属性包含用于 DNS 查询的名称服务器。
[bindable, since 6.6]
nameserverPort : quint16
注意: 该属性支持QProperty 绑定。
该属性包含用于 DNS 查询的名称服务器端口号。
值为 0 表示QDnsLookup 应使用nameserverProtocol() 的默认端口。
注意: 将端口号设置为默认值(53)以外的任何值都可能导致名称解析失败,这取决于操作系统的限制和防火墙,如果nameserverProtocol() 要使用QDnsLookup::Standard 。值得注意的是,QDnsLookup 使用的 Windows API 无法处理备用端口号。
此属性在 Qt 6.6 中引入。
[bindable, since 6.8]
nameserverProtocol : Protocol
注意: 该属性支持QProperty 绑定。
该属性用于保存发送 DNS 查询时使用的协议。
此属性在 Qt 6.8 中引入。
另请参阅 isProtocolSupported().
[bindable]
type : Type
注意: 此属性支持QProperty 绑定。
该属性用于保存 DNS 查询类型。
成员函数文档
[explicit]
QDnsLookup::QDnsLookup(QObject *parent = nullptr)
构造一个 QDnsLookup 对象,并将parent 设置为父对象。
type 属性将默认为QDnsLookup::A 。
QDnsLookup::QDnsLookup(QDnsLookup::Type type, const QString &name, QObject *parent = nullptr)
为给定的type 和name 构造一个 QDnsLookup 对象,并将parent 设置为父对象。
QDnsLookup::QDnsLookup(QDnsLookup::Type type, const QString &name, const QHostAddress &nameserver, QObject *parent = nullptr)
构造一个 QDnsLookup 对象,使用运行在默认 DNS 端口上的 DNS 服务器nameserver 对记录类型为type 的name 进行查询,并将parent 设置为父对象。
[since 6.6]
QDnsLookup::QDnsLookup(QDnsLookup::Type type, const QString &name, const QHostAddress &nameserver, quint16 port, QObject *parent = nullptr)
构造一个 QDnsLookup 对象,使用运行在端口port 上的 DNS 服务器nameserver 对记录类型为type 的name 进行查询,并将parent 设置为父对象。
注意: 将端口号设置为默认值(53)以外的任何值都可能导致名称解析失败,这取决于操作系统的限制和防火墙,如果要使用的nameserverProtocol() 是QDnsLookup::Standard 。值得注意的是,QDnsLookup 使用的 Windows API 无法处理备用端口号。
该函数在 Qt 6.6 中引入。
[since 6.8]
QDnsLookup::QDnsLookup(QDnsLookup::Type type, const QString &name, QDnsLookup::Protocol protocol, const QHostAddress &nameserver, quint16 port = 0, QObject *parent = nullptr)
构造一个 QDnsLookup 对象,使用运行在port 端口上的 DNS 服务器nameserver ,查询记录类型为type 的name ,并将parent 设置为父对象。
如果支持,查询将使用protocol 发送。使用isProtocolSupported() 查看是否支持。
注意: 将端口号设置为默认值 (53) 以外的任何值都可能导致名称解析失败,这取决于操作系统的限制和防火墙,如果nameserverProtocol() 要使用QDnsLookup::Standard 。值得注意的是,QDnsLookup 使用的 Windows API 无法处理备用端口号。
该函数在 Qt 6.8 中引入。
[virtual noexcept]
QDnsLookup::~QDnsLookup()
销毁QDnsLookup 对象。
删除QDnsLookup 对象是安全的,即使它还没有完成,您也不会收到它的结果。
[slot]
void QDnsLookup::abort()
终止 DNS 查询操作。
如果查询已经完成,则什么也不做。
QList<QDnsDomainNameRecord> QDnsLookup::canonicalNameRecords() const
返回与此查询相关的规范名称记录列表。
[static noexcept, since 6.8]
quint16 QDnsLookup::defaultPortForProtocol(QDnsLookup::Protocol protocol)
返回协议protocol 的标准(默认)端口号。
此函数在 Qt 6.8 中引入。
另请参阅 isProtocolSupported()。
[signal]
void QDnsLookup::finished()
该信号在回复处理完毕后发出。
注: 属性authenticData 的通知信号。error 属性的通知信号。errorString 属性的通知信号。
QList<QDnsHostAddressRecord> QDnsLookup::hostAddressRecords() const
返回与此查询相关的主机地址记录列表。
bool QDnsLookup::isFinished() const
返回回复是已完成还是已中止。
[static, since 6.8]
bool QDnsLookup::isProtocolSupported(QDnsLookup::Protocol protocol)
如果QDnsLookup 支持使用protocol 进行 DNS 查询,则返回 true。
此函数在 Qt 6.8 中引入。
另请参见 nameserverProtocol 。
[slot]
void QDnsLookup::lookup()
执行 DNS 查找。
完成后会发出finished() 信号。
QList<QDnsMailExchangeRecord> QDnsLookup::mailExchangeRecords() const
返回与此查询相关的邮件交换记录列表。
这些记录是根据RFC 5321 排序的,因此如果要使用它们连接服务器,应按照列出的顺序进行尝试。
[signal]
void QDnsLookup::nameChanged(const QString &name)
name name 是新的查找名称。
注: 属性name 的通知信号。
QList<QDnsDomainNameRecord> QDnsLookup::nameServerRecords() const
返回与此查询相关的名称服务器记录列表。
QList<QDnsDomainNameRecord> QDnsLookup::pointerRecords() const
返回与此查询相关的指针记录列表。
QList<QDnsServiceRecord> QDnsLookup::serviceRecords() const
返回与此查询相关的服务记录列表。
这些记录是根据RFC 2782 排序的,因此如果要使用它们连接服务器,应按照列出的顺序进行尝试。
[since 6.6]
void QDnsLookup::setNameserver(const QHostAddress &nameserver, quint16 port)
将名称服务器设置为nameserver ,端口设置为port 。
注意: 将端口号设置为默认值(53)以外的任何值都可能导致名称解析失败,这取决于操作系统的限制和防火墙,如果nameserverProtocol() 要使用QDnsLookup::Standard 。值得注意的是,QDnsLookup 使用的 Windows API 无法处理备用端口号。
注: 属性nameserver 的设置函数。
该函数在 Qt 6.6 中引入。
另请参阅 QDnsLookup::nameserver 和QDnsLookup::nameserverPort 。
[since 6.8]
void QDnsLookup::setSslConfiguration(const QSslConfiguration &sslConfiguration)
设置用于外发 DNS-over-TLS 连接的sslConfiguration 。
此函数在 Qt 6.8 中引入。
另请参阅 sslConfiguration() 和QSslSocket::setSslConfiguration()。
QSslConfiguration QDnsLookup::sslConfiguration() const
返回当前 SSL 配置。
另请参阅 setSslConfiguration()。
QList<QDnsTextRecord> QDnsLookup::textRecords() const
返回与此查询相关的文本记录列表。
[since 6.8]
QList<QDnsTlsAssociationRecord> QDnsLookup::tlsAssociationRecords() const
返回与此查询相关的 TLS 关联记录列表。
根据与基于 DNS 的命名实体身份验证(DANE)相关的标准,如果 DNS 回复本身的真实性无法确认,则应忽略此字段,且不得将其用于验证指定服务器的真实性。更多信息请参阅isAuthenticData()。
此函数在 Qt 6.8 中引入。
[signal]
void QDnsLookup::typeChanged(QDnsLookup::Type type)
type type 是新的查找类型。
注: 属性type 的通知信号。
© 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.