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

公共类型

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 abort()
void lookup()

信号

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 查找。要执行查询,您需要指定nametype ,然后调用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::NoError0无错误条件。
QDnsLookup::ResolverError1系统 DNS 解析器初始化出错。
QDnsLookup::OperationCancelledError2使用abort() 方法中止了查询。
QDnsLookup::InvalidRequestError3请求的 DNS 查询无效。
QDnsLookup::InvalidReplyError4服务器返回的回复无效。
QDnsLookup::ServerFailureError5服务器在处理请求时遇到内部故障 (SERVFAIL)。
QDnsLookup::ServerRefusedError6服务器因安全或策略原因拒绝处理请求 (REFUSED)。
QDnsLookup::NotFoundError7请求的域名不存在(NXDOMAIN)。
QDnsLookup::TimeoutError8无法联系到服务器或服务器未及时回复(自 6.6 版起)。

enum QDnsLookup::Protocol

表示查询的 DNS 服务器类型。

常数说明
QDnsLookup::Standard0常规、未加密 DNS,使用 UDP,必要时回退到 TCP(默认端口:53)
QDnsLookup::DnsOverTls1通过 TCP 的 TLS 加密 DNS(DoT,由RFC 7858 规定)(默认端口:853)

另请参阅 isProtocolSupported()、nameserverProtocolsetNameserver()。

enum QDnsLookup::Type

表示执行的 DNS 查询类型。

常数说明
QDnsLookup::A1IPv4 地址记录。
QDnsLookup::AAAA28IPv6 地址记录。
QDnsLookup::ANY255任何记录。
QDnsLookup::CNAME5规范名称记录。
QDnsLookup::MX15邮件交换记录。
QDnsLookup::NS2名称服务器记录。
QDnsLookup::PTR12指针记录
QDnsLookup::SRV33服务记录
QDnsLookup::TLSA (since Qt 6.8)52TLS 关联记录。
QDnsLookup::TXT16文本记录

属性文档

[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)

为给定的typename 构造一个 QDnsLookup 对象,并将parent 设置为父对象。

QDnsLookup::QDnsLookup(QDnsLookup::Type type, const QString &name, const QHostAddress &nameserver, QObject *parent = nullptr)

构造一个 QDnsLookup 对象,使用运行在默认 DNS 端口上的 DNS 服务器nameserver 对记录类型为typename 进行查询,并将parent 设置为父对象。

[since 6.6] QDnsLookup::QDnsLookup(QDnsLookup::Type type, const QString &name, const QHostAddress &nameserver, quint16 port, QObject *parent = nullptr)

构造一个 QDnsLookup 对象,使用运行在端口port 上的 DNS 服务器nameserver 对记录类型为typename 进行查询,并将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 ,查询记录类型为typename ,并将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::nameserverQDnsLookup::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.