QDnsLookup Class | Qt Network | Qt 6.11.0
Description: The QDnsLookup class represents a DNS lookup.

- Qt 6.11
- Qt Network
- C++ Classes
- QDnsLookup
- Qt 6.11.0 Reference Documentation

# 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

- List of all members, including inherited members
- QDnsLookup is part of Network Programming API.

## Public Types

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

## Properties

`(since 6.8)` authenticData : bool error : Error errorString : QString name : QString | nameserver : QHostAddress `(since 6.6)` nameserverPort : quint16 `(since 6.8)` nameserverProtocol : Protocol type : Type

## 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)
`(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)
void | setNameserver(const QHostAddress &nameserver)
void | setNameserver(QDnsLookup::Protocol protocol, const QHostAddress &nameserver, quint16 port = 0)
`(since 6.6)` void | setNameserver(const QHostAddress &nameserver, quint16 port)
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

## Public Slots

void | abort()
void | lookup()

## Signals

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)

## Static Public Members

`(since 6.8)` quint16 | defaultPortForProtocol(QDnsLookup::Protocol protocol)
`(since 6.8)` bool | isProtocolSupported(QDnsLookup::Protocol protocol)

## 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.

### DNS-over-TLS and Authentic Data

QDnsLookup supports DNS-over-TLS (DoT, as specified by RFC 7858) on some platforms. That currently includes all Unix platforms where regular queries are supported, if QSslSocket support is present in Qt. To query if support is present at runtime, use isProtocolSupported().

When using DNS-over-TLS, QDnsLookup only implements the "Opportunistic Privacy Profile" method of authentication, as described in RFC 7858 section 4.1. In this mode, QDnsLookup (through QSslSocket) only validates that the server presents a certificate that is valid for the server being connected to. Clients may use setSslConfiguration() to impose additional restrictions and sslConfiguration() to obtain information after the query is complete.

QDnsLookup will request DNS servers queried over TLS to perform authentication on the data they return. If they confirm the data is valid, the authenticData property will be set to true. QDnsLookup does not verify the integrity of the data by itself, so applications should only trust this property on servers they have confirmed through other means to be trustworthy.

#### Authentic Data without TLS

QDnsLookup request Authentic Data for any server set with setNameserver(), even if TLS encryption is not required. This is useful when querying a caching nameserver on the same host as the application or on a trusted network. Though similar to the TLS case, the application is responsible for determining if the server it chose to use is trustworthy, and if the unencrypted connection cannot be tampered with.

QDnsLookup obeys the system configuration to request Authentic Data on the default nameserver (that is, if setNameserver() is not called). This is currently only supported on Linux systems using glibc 2.31 or later. On any other systems, QDnsLookup will ignore the AD bit in the query header.

## Member Type Documentation

### enum QDnsLookup::Error

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

Constant | Value | Description
--- | --- | ---
`QDnsLookup::NoError` | `0` | no error condition.
`QDnsLookup::ResolverError` | `1` | there was an error initializing the system's DNS resolver.
`QDnsLookup::OperationCancelledError` | `2` | the lookup was aborted using the abort() method.
`QDnsLookup::InvalidRequestError` | `3` | the requested DNS lookup was invalid.
`QDnsLookup::InvalidReplyError` | `4` | the reply returned by the server was invalid.
`QDnsLookup::ServerFailureError` | `5` | the server encountered an internal failure while processing the request (SERVFAIL).
`QDnsLookup::ServerRefusedError` | `6` | the server refused to process the request for security or policy reasons (REFUSED).
`QDnsLookup::NotFoundError` | `7` | the requested domain name does not exist (NXDOMAIN).
`QDnsLookup::TimeoutError` | `8` | the server was not reached or did not reply in time (since 6.6).

### enum QDnsLookup::Protocol

Indicates the type of DNS server that is being queried.

Constant | Value | Description
--- | --- | ---
`QDnsLookup::Standard` | `0` | Regular, unencrypted DNS, using UDP and falling back to TCP as necessary (default port: 53)
`QDnsLookup::DnsOverTls` | `1` | Encrypted DNS over TLS (DoT, as specified by RFC 7858), over TCP (default port: 853)

See also isProtocolSupported(), nameserverProtocol, and setNameserver().

### enum QDnsLookup::Type

Indicates the type of DNS lookup that was performed.

Constant | Value | Description
--- | --- | ---
`QDnsLookup::A` | `1` | IPv4 address records.
`QDnsLookup::AAAA` | `28` | IPv6 address records.
`QDnsLookup::ANY` | `255` | any records.
`QDnsLookup::CNAME` | `5` | canonical name records.
`QDnsLookup::MX` | `15` | mail exchange records.
`QDnsLookup::NS` | `2` | name server records.
`QDnsLookup::PTR` | `12` | pointer records.
`QDnsLookup::SRV` | `33` | service records.
`QDnsLookup::TLSA (since Qt 6.8)` | `52` | TLS association records.
`QDnsLookup::TXT` | `16` | text records.

## Property Documentation

### `[read-only, since 6.8]` authenticData : bool

This property holds whether the reply was authenticated by the resolver.

QDnsLookup does not perform the authentication itself. Instead, it trusts the name server that was queried to perform the authentication and report it. The application is responsible for determining if any servers it configured with setNameserver() are trustworthy; if no server was set, QDnsLookup obeys system configuration on whether responses should be trusted.

This property may be set even if error() indicates a resolver error occurred.

This property was introduced in Qt 6.8.

Access functions:

bool | isAuthenticData() const

Notifier signal:

void | finished()

See also setNameserver() and nameserverProtocol().

### `[read-only]` error : 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 : 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.

Access functions:

QString | name() const
void | setName(const QString &name)

Notifier signal:

void | nameChanged(const QString &name)

### `[bindable]` nameserver : QHostAddress

Note: This property supports QProperty bindings.

This property holds the nameserver to use for DNS lookup.

Access functions:

QHostAddress | nameserver() const
void | setNameserver(const QHostAddress &nameserver)
void | setNameserver(QDnsLookup::Protocol protocol, const QHostAddress &nameserver, quint16 port = 0)
void | setNameserver(const QHostAddress &nameserver, quint16 port)

Notifier signal:

void | nameserverChanged(const QHostAddress &nameserver)

### `[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.

The value of 0 indicates that QDnsLookup should use the default port for the nameserverProtocol().

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, if the nameserverProtocol() to be used QDnsLookup::Standard. Notably, the Windows API used by QDnsLookup is unable to handle alternate port numbers.

This property was introduced in Qt 6.6.

Access functions:

quint16 | nameserverPort() const
void | setNameserverPort(quint16 port)

Notifier signal:

void | nameserverPortChanged(quint16 port)

### `[bindable, since 6.8]` nameserverProtocol : Protocol

Note: This property supports QProperty bindings.

This property holds the protocol to use when sending the DNS query

This property was introduced in Qt 6.8.

Access functions:

QDnsLookup::Protocol | nameserverProtocol() const
void | setNameserverProtocol(QDnsLookup::Protocol protocol)

Notifier signal:

void | nameserverProtocolChanged(QDnsLookup::Protocol protocol)

See also isProtocolSupported().

### `[bindable]` type : Type

Note: This property supports QProperty bindings.

This property holds the type of DNS lookup.

Access functions:

QDnsLookup::Type | type() const
void | setType(QDnsLookup::Type)

Notifier signal:

void | typeChanged(QDnsLookup::Type type)

## 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, if the nameserverProtocol() to be used QDnsLookup::Standard. Notably, the Windows API used by QDnsLookup is unable to handle alternate port numbers.

This function was introduced in 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)

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.

The query will be sent using protocol, if supported. Use isProtocolSupported() to check if it is supported.

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, if the nameserverProtocol() to be used QDnsLookup::Standard. Notably, the Windows API used by QDnsLookup is unable to handle alternate port numbers.

This function was introduced in Qt 6.8.

### `[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.

### `[static noexcept, since 6.8]` quint16 QDnsLookup::defaultPortForProtocol(QDnsLookup::Protocol protocol)

Returns the standard (default) port number for the protocol protocol.

This function was introduced in Qt 6.8.

See also isProtocolSupported().

### `[signal]` void QDnsLookup::finished()

This signal is emitted when the reply has finished processing.

Note: Notifier signal for properties authenticData, error, and 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.

### `[static, since 6.8]` bool QDnsLookup::isProtocolSupported(QDnsLookup::Protocol protocol)

Returns true if DNS queries using protocol are supported with QDnsLookup.

This function was introduced in Qt 6.8.

See also nameserverProtocol.

### `[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, if the nameserverProtocol() to be used QDnsLookup::Standard. 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.

### `[since 6.8]` void QDnsLookup::setSslConfiguration(const QSslConfiguration &sslConfiguration)

Sets the sslConfiguration to use for outgoing DNS-over-TLS connections.

This function was introduced in Qt 6.8.

See also sslConfiguration() and QSslSocket::setSslConfiguration().

### QSslConfiguration QDnsLookup::sslConfiguration() const

Returns the current SSL configuration.

See also setSslConfiguration().

### QList<QDnsTextRecord> QDnsLookup::textRecords() const

Returns the list of text records associated with this lookup.

### `[since 6.8]` QList<QDnsTlsAssociationRecord> QDnsLookup::tlsAssociationRecords() const

Returns the list of TLS association records associated with this lookup.

According to the standards relating to DNS-based Authentication of Named Entities (DANE), this field should be ignored and must not be used for verifying the authentity of a given server if the authenticity of the DNS reply cannot itself be confirmed. See isAuthenticData() for more information.

This function was introduced in Qt 6.8.

### `[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.