QDnsLookup Class

The QDnsLookup class represents a DNS lookup. More...

Header: #include <QDnsLookup>
CMake: find_package(Qt6 REQUIRED COMPONENTS Network)
target_link_libraries(mytarget PRIVATE Qt6::Network)
qmake: QT += network
Inherits: QObject

Public Types

enum Error { NoError, ResolverError, OperationCancelledError, InvalidRequestError, InvalidReplyError, …, TimeoutError }
enum Type { A, AAAA, ANY, CNAME, MX, …, TXT }

Properties

Public Functions

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)
virtual ~QDnsLookup()
QBindable<QString> bindableName()
QBindable<QHostAddress> bindableNameserver()
QBindable<quint16> bindableNameserverPort()
QBindable<QDnsLookup::Type> bindableType()
QList<QDnsDomainNameRecord> canonicalNameRecords() const
QDnsLookup::Error error() const
QString errorString() const
QList<QDnsHostAddressRecord> hostAddressRecords() const
bool isFinished() const
QList<QDnsMailExchangeRecord> mailExchangeRecords() const
QString name() const
QList<QDnsDomainNameRecord> nameServerRecords() const
QHostAddress nameserver() const
quint16 nameserverPort() const
QList<QDnsDomainNameRecord> pointerRecords() const
QList<QDnsServiceRecord> serviceRecords() const
void setName(const QString &name)
void setNameserver(const QHostAddress &nameserver)
(since 6.6) void setNameserver(const QHostAddress &nameserver, quint16 port)
void setNameserverPort(quint16 port)
void setType(QDnsLookup::Type)
QList<QDnsTextRecord> textRecords() const
QDnsLookup::Type type() const

Public Slots

void abort()
void lookup()

Signals

void finished()
void nameChanged(const QString &name)
void nameserverChanged(const QHostAddress &nameserver)
void nameserverPortChanged(quint16 port)
void typeChanged(QDnsLookup::Type type)

Detailed Description

QDnsLookup uses the mechanisms provided by the operating system to perform DNS lookups. To perform a lookup you need to specify a name and type then invoke the lookup() slot. The finished() signal will be emitted upon completion.

For example, you can determine which servers an XMPP chat client should connect to for a given domain with:

 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();
 }

Once the request finishes you can handle the results with:

 void MyObject::handleServers()
 {
     // Check the lookup succeeded.
     if (dns->error() != QDnsLookup::NoError) {
         qWarning("DNS lookup failed");
         dns->deleteLater();
         return;
     }

     // Handle the results.
     const auto records = dns->serviceRecords();
     for (const QDnsServiceRecord &record : records) {
         ...
     }
     dns->deleteLater();
 }

Note: If you simply want to find the IP address(es) associated with a host name, or the host name associated with an IP address you should use QHostInfo instead.

Member Type Documentation

enum QDnsLookup::Error

Indicates all possible error conditions found during the processing of the DNS lookup.

ConstantValueDescription
QDnsLookup::NoError0no error condition.
QDnsLookup::ResolverError1there was an error initializing the system's DNS resolver.
QDnsLookup::OperationCancelledError2the lookup was aborted using the abort() method.
QDnsLookup::InvalidRequestError3the requested DNS lookup was invalid.
QDnsLookup::InvalidReplyError4the reply returned by the server was invalid.
QDnsLookup::ServerFailureError5the server encountered an internal failure while processing the request (SERVFAIL).
QDnsLookup::ServerRefusedError6the server refused to process the request for security or policy reasons (REFUSED).
QDnsLookup::NotFoundError7the requested domain name does not exist (NXDOMAIN).
QDnsLookup::TimeoutError8the server was not reached or did not reply in time (since 6.6).

enum QDnsLookup::Type

Indicates the type of DNS lookup that was performed.

ConstantValueDescription
QDnsLookup::A1IPv4 address records.
QDnsLookup::AAAA28IPv6 address records.
QDnsLookup::ANY255any records.
QDnsLookup::CNAME5canonical name records.
QDnsLookup::MX15mail exchange records.
QDnsLookup::NS2name server records.
QDnsLookup::PTR12pointer records.
QDnsLookup::SRV33service records.
QDnsLookup::TXT16text records.

Property Documentation

[read-only] error : const Error

This property holds the type of error that occurred if the DNS lookup failed, or NoError.

Access functions:

QDnsLookup::Error error() const

Notifier signal:

void finished()

[read-only] errorString : const QString

This property holds a human-readable description of the error if the DNS lookup failed.

Access functions:

QString errorString() const

Notifier signal:

void finished()

[bindable] name : QString

Note: This property supports QProperty bindings.

This property holds the name to lookup.

If the name to look up is empty, QDnsLookup will attempt to resolve the root domain of DNS. That query is usually performed with QDnsLookup::type set to NS.

Note: The name will be encoded using IDNA, which means it's unsuitable for querying SRV records compatible with the DNS-SD specification.

[bindable] nameserver : QHostAddress

Note: This property supports QProperty bindings.

This property holds the nameserver to use for DNS lookup.

[bindable, since 6.6] nameserverPort : quint16

Note: This property supports QProperty bindings.

This property holds the port number of nameserver to use for DNS lookup.

Note: Setting the port number to any value other than the default (53) can cause the name resolution to fail, depending on the operating system limitations and firewalls. Notably, the Windows API used by QDnsLookup is unable to handle alternate port numbers.

This property was introduced in Qt 6.6.

[bindable] type : Type

Note: This property supports QProperty bindings.

This property holds the type of DNS lookup.

Member Function Documentation

[explicit] QDnsLookup::QDnsLookup(QObject *parent = nullptr)

Constructs a QDnsLookup object and sets parent as the parent object.

The type property will default to QDnsLookup::A.

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

Constructs a QDnsLookup object for the given type and name and sets parent as the parent object.

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

Constructs a QDnsLookup object to issue a query for name of record type type, using the DNS server nameserver running on the default DNS port, and sets parent as the parent object.

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

Constructs a QDnsLookup object to issue a query for name of record type type, using the DNS server nameserver running on port port, and sets parent as the parent object.

Note: Setting the port number to any value other than the default (53) can cause the name resolution to fail, depending on the operating system limitations and firewalls. Notably, the Windows API used by QDnsLookup is unable to handle alternate port numbers.

This function was introduced in Qt 6.6.

[virtual noexcept] QDnsLookup::~QDnsLookup()

Destroys the QDnsLookup object.

It is safe to delete a QDnsLookup object even if it is not finished, you will simply never receive its results.

[slot] void QDnsLookup::abort()

Aborts the DNS lookup operation.

If the lookup is already finished, does nothing.

QList<QDnsDomainNameRecord> QDnsLookup::canonicalNameRecords() const

Returns the list of canonical name records associated with this lookup.

[signal] void QDnsLookup::finished()

This signal is emitted when the reply has finished processing.

Note: Notifier signal for property error. Notifier signal for property errorString.

QList<QDnsHostAddressRecord> QDnsLookup::hostAddressRecords() const

Returns the list of host address records associated with this lookup.

bool QDnsLookup::isFinished() const

Returns whether the reply has finished or was aborted.

[slot] void QDnsLookup::lookup()

Performs the DNS lookup.

The finished() signal is emitted upon completion.

QList<QDnsMailExchangeRecord> QDnsLookup::mailExchangeRecords() const

Returns the list of mail exchange records associated with this lookup.

The records are sorted according to RFC 5321, so if you use them to connect to servers, you should try them in the order they are listed.

[signal] void QDnsLookup::nameChanged(const QString &name)

This signal is emitted when the lookup name changes. name is the new lookup name.

Note: Notifier signal for property name.

QList<QDnsDomainNameRecord> QDnsLookup::nameServerRecords() const

Returns the list of name server records associated with this lookup.

QList<QDnsDomainNameRecord> QDnsLookup::pointerRecords() const

Returns the list of pointer records associated with this lookup.

QList<QDnsServiceRecord> QDnsLookup::serviceRecords() const

Returns the list of service records associated with this lookup.

The records are sorted according to RFC 2782, so if you use them to connect to servers, you should try them in the order they are listed.

[since 6.6] void QDnsLookup::setNameserver(const QHostAddress &nameserver, quint16 port)

Sets the nameserver to nameserver and the port to port.

Note: Setting the port number to any value other than the default (53) can cause the name resolution to fail, depending on the operating system limitations and firewalls. Notably, the Windows API used by QDnsLookup is unable to handle alternate port numbers.

Note: Setter function for property nameserver.

This function was introduced in Qt 6.6.

See also QDnsLookup::nameserver and QDnsLookup::nameserverPort.

QList<QDnsTextRecord> QDnsLookup::textRecords() const

Returns the list of text records associated with this lookup.

[signal] void QDnsLookup::typeChanged(QDnsLookup::Type type)

This signal is emitted when the lookup type changes. type is the new lookup type.

Note: Notifier signal for property type.