QDnsLookup Class
QDnsLookup 클래스는 DNS 조회 기능을 나타냅니다. 더 보기...
| 헤더: | #include <QDnsLookup> |
| CMake: | 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) |
| 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 |
공개 슬롯
신호
| 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();
}요청이 완료되면 다음 코드로 결과를 처리할 수 있습니다:
void MyObject::handleServers()
{
// 조회 성공 여부 확인.
if (dns->error() != QDnsLookup::NoError) {
qWarning("DNS lookup failed");
dns->deleteLater();
return;
}
// 결과를 처리합니다.
const auto records = dns->serviceRecords();
for (const QDnsServiceRecord&record: records) {
...
}
dns->deleteLater();
}참고: 호스트 이름과 연결된 IP 주소를 찾거나, IP 주소와 연결된 호스트 이름을 찾으려는경우에는 대신 QHostInfo 를 사용해야 합니다.
DNS-over-TLS 및 인증 데이터
QDnsLookup은 일부 플랫폼에서 DNS-over-TLS( RFC 7858에 정의된 DoT)를 지원합니다. 현재 Qt에 QSslSocket 지원이 포함되어 있다면, 일반 쿼리가 지원되는 모든 유닉스 플랫폼이 이에 해당합니다. 런타임 시 지원 여부를 확인하려면 isProtocolSupported()를 사용하십시오.
DNS-over-TLS를 사용할 때, QDnsLookup은 RFC 7858 섹션 4.1에 설명된 대로 “Opportunistic Privacy Profile” 인증 방식만 구현합니다. 이 모드에서 QDnsLookup( QSslSocket 을 통해)은 서버가 연결 대상 서버에 대해 유효한 인증서를 제시하는지 여부만 검증합니다. 클라이언트는 setSslConfiguration()을 사용하여 추가 제한을 적용하고, sslConfiguration()을 사용하여 쿼리가 완료된 후 정보를 얻을 수 있습니다.
QDnsLookup은 TLS를 통해 쿼리된 DNS 서버에 반환하는 데이터에 대한 인증을 수행하도록 요청합니다. 서버가 데이터의 유효성을 확인하면 authenticData 속성이 true로 설정됩니다. QDnsLookup은 데이터의 무결성을 직접 검증하지 않으므로, 애플리케이션은 다른 방법을 통해 신뢰할 수 있다고 확인된 서버에 대해서만 이 속성을 신뢰해야 합니다.
TLS 없이 인증된 데이터
QDnsLookup은 TLS 암호화가 필요하지 않은 경우에도 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 | UDP를 사용하고 필요에 따라 TCP로 전환되는 일반, 암호화되지 않은 DNS(기본 포트: 53) |
QDnsLookup::DnsOverTls | 1 | TCP를 통해 TLS( RFC 7858에 명시된 DoT)로 전송되는 암호화된 DNS(기본 포트: 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 : bool
이 속성은 응답이 리졸버에 의해 인증되었는지 여부를 나타냅니다.
QDnsLookup 이 함수는 자체적으로 인증을 수행하지 않습니다. 대신, 쿼리된 네임 서버가 인증을 수행하고 그 결과를 보고할 것이라고 신뢰합니다. 애플리케이션은 setNameserver()를 통해 구성된 서버가 신뢰할 수 있는지 여부를 판단할 책임이 있습니다. 서버가 설정되지 않은 경우, QDnsLookup 는 응답을 신뢰할지 여부에 대한 시스템 구성을 따릅니다.
error()가 리졸버 오류가 발생했음을 나타내는 경우에도 이 속성을 설정할 수 있습니다.
이 열거형은 Qt 6.8에서 도입되었습니다.
액세스 함수:
| bool | isAuthenticData() const |
알림 신호:
| void | finished() |
setNameserver() 및 nameserverProtocol()도 참조하십시오 .
[read-only] error : Error
이 속성은 DNS 조회가 실패했을 때 발생한 오류의 유형을 나타내거나, NoError 를 반환합니다.
액세스 함수:
| QDnsLookup::Error | error() const |
알림 신호:
| void | finished() |
[read-only] errorString : QString
이 속성은 DNS 조회에 실패한 경우, 사람이 읽을 수 있는 오류 설명을 포함합니다.
액세스 함수:
| QString | errorString() const |
알림 신호:
| void | finished() |
[bindable] name : QString
참고: 이 속성은 QProperty 바인딩을 지원합니다.
이 속성은 조회할 이름을 저장합니다.
조회할 이름이 비어 있는 경우, QDnsLookup 는 DNS의 루트 도메인을 확인하려고 시도합니다. 이 쿼리는 일반적으로 QDnsLookup::type 가 NS 로 설정된 상태에서 수행됩니다.
참고: 이름은 IDNA를 사용하여 인코딩되므로, DNS-SD 사양과 호환되는 SRV 레코드를 조회하는 데는 적합하지 않습니다.
액세스 기능:
| QString | name() const |
| void | setName(const QString &name) |
알림 신호:
| void | nameChanged(const QString &name) |
[bindable] nameserver : QHostAddress
참고: 이 속성은 QProperty 바인딩을 지원합니다.
이 속성은 DNS 조회에 사용할 네임서버를 저장합니다.
액세스 함수:
| 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) |
알림 신호:
| void | nameserverChanged(const QHostAddress &nameserver) |
[bindable, since 6.6] nameserverPort : quint16
참고: 이 속성은 QProperty 바인딩을 지원합니다.
이 속성은 DNS 조회에 사용할 네임서버의 포트 번호를 저장합니다.
값이 0인 경우, QDnsLookup 은 nameserverProtocol()에 대한 기본 포트를 사용해야 함을 나타냅니다.
참고: 포트 번호를 기본값(53) 이외의 다른 값으로설정하면 , 사용하려는 nameserverProtocol()이 QDnsLookup::Standard 인 경우 운영 체제의 제한 사항 및 방화벽에 따라 이름 확인이 실패할 수 있습니다. 특히, QDnsLookup 에서 사용하는 Windows API는 다른 포트 번호를 처리할 수 없습니다.
이 열거형은 Qt 6.6에서 도입되었습니다.
액세스 함수:
| quint16 | nameserverPort() const |
| void | setNameserverPort(quint16 port) |
Notifier 시그널:
| void | nameserverPortChanged(quint16 port) |
[bindable, since 6.8] nameserverProtocol : Protocol
참고: 이 속성은 QProperty 바인딩을 지원합니다.
이 속성은 DNS 쿼리를 전송할 때 사용할 프로토콜을 저장합니다.
이 열거형은 Qt 6.8에서 도입되었습니다.
액세스 함수:
| QDnsLookup::Protocol | nameserverProtocol() const |
| void | setNameserverProtocol(QDnsLookup::Protocol protocol) |
알림 신호:
| void | nameserverProtocolChanged(QDnsLookup::Protocol protocol) |
isProtocolSupported()도 참조하십시오 .
[bindable] type : Type
참고: 이 속성은 QProperty 바인딩을 지원합니다.
이 속성은 DNS 조회 유형을 나타냅니다.
액세스 함수:
| QDnsLookup::Type | type() const |
| void | setType(QDnsLookup::Type) |
알림 신호:
| void | typeChanged(QDnsLookup::Type type) |
멤버 함수 설명서
[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)
기본 DNS 포트에서 실행 중인 DNS 서버 nameserver 를 사용하여 레코드 유형 type 의 name 에 대한 쿼리를 실행하는 QDnsLookup 객체를 생성하고, parent 를 상위 객체로 설정합니다.
[since 6.6] QDnsLookup::QDnsLookup(QDnsLookup::Type type, const QString &name, const QHostAddress &nameserver, quint16 port, QObject *parent = nullptr)
포트 port 에서 실행 중인 DNS 서버 nameserver 을 사용하여 레코드 유형 type 의 name 에 대한 쿼리를 실행하도록 QDnsLookup 객체를 생성하고, parent 을 상위 객체로 설정합니다.
참고: nameserverProtocol()에서 사용될 QDnsLookup::Standard 의 포트 번호를 기본값(53) 이외의 값으로설정하면 , 운영 체제의 제한 사항 및 방화벽에 따라 이름 확인이 실패할 수 있습니다. 특히, 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)
포트 port 에서 실행 중인 DNS 서버 nameserver 를 사용하여 레코드 유형 type 의 name 에 대한 쿼리를 실행하는 QDnsLookup 객체를 생성하고, parent 를 상위 객체로 설정합니다.
지원되는 경우 protocol 를 사용하여 쿼리가 전송됩니다. 지원 여부를 확인하려면 isProtocolSupported()를 사용하십시오.
QDnsLookup::Standard참고: nameserverProtocol()를 사용할 때 포트 번호를 기본값(53) 이외의 값으로설정하면 , 운영 체제의 제한 사항 및 방화벽에 따라 이름 확인이 실패할 수 있습니다. 특히, 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 에 대한알림 신호입니다.
© 2026 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.