DnsQueryEx-Funktion (windns.h)

Artikel
03/09/2024

Die DnsQueryEx-Funktion ist die asynchrone generische Abfrageschnittstelle für den DNS-Namespace. Es bietet Anwendungsentwicklern eine DNS-Abfrageauflösungsschnittstelle.

Wie DnsQuery kannauch DnsQueryEx verwendet werden, um synchrone Abfragen an den DNS-Namespace durchzuführen.

Syntax

DNS_STATUS DnsQueryEx(
  [in]                PDNS_QUERY_REQUEST pQueryRequest,
  [in, out]           PDNS_QUERY_RESULT  pQueryResults,
  [in, out, optional] PDNS_QUERY_CANCEL  pCancelHandle
);

Parameter

[in] pQueryRequest

Ein Zeiger auf eine DNS_QUERY_REQUEST - oder DNS_QUERY_REQUEST3-Struktur , die die Abfrageanforderungsinformationen enthält.

Hinweis Durch Weglassen des DNS_QUERY_COMPLETION_ROUTINE Rückrufs aus dem pQueryCompleteCallback-Member dieser Struktur wird DnsQueryEx synchron aufgerufen.

[in, out] pQueryResults

Ein Zeiger auf eine DNS_QUERY_RESULT-Struktur , die die Ergebnisse der Abfrage enthält. Bei der Eingabe muss das Versionsmember von pQueryResultsDNS_QUERY_RESULTS_VERSION1 sein, und alle anderen Member sollten NULL sein. Bei der Ausgabe werden die restlichen Member als Teil des Abfragevorgangs ausgefüllt.

Hinweis Bei asynchronen Abfragen sollte eine Anwendung diese Struktur erst freigeben, wenn der DNS_QUERY_COMPLETION_ROUTINE Rückruf aufgerufen wird. Nach Abschluss der Abfrage enthält die DNS_QUERY_RESULT-Struktur einen Zeiger auf eine Liste von DNS_RECORDS , die mithilfe von DnsRecordListFree freigegeben werden sollen.

[in, out, optional] pCancelHandle

Ein Zeiger auf eine DNS_QUERY_CANCEL Struktur, mit der eine ausstehende asynchrone Abfrage abgebrochen werden kann.

Hinweis Eine Anwendung sollte diese Struktur erst freigeben, wenn der DNS_QUERY_COMPLETION_ROUTINE Rückruf aufgerufen wird.

Rückgabewert

Die DnsQueryEx-Funktion verfügt über die folgenden möglichen Rückgabewerte:

Rückgabecode	Beschreibung
ERROR_SUCCESS	Der Aufruf war erfolgreich.
ERROR_INVALID_PARAMETER	Die Parameter pQueryRequest oder pQueryRequest sind nicht initialisiert oder enthalten die falsche Version.
DNS RCODE	Der Aufruf führte zu einem RCODE-Fehler .
DNS_INFO_NO_RECORDS	Keine Datensätze in der Antwort.
DNS_REQUEST_PENDING	Die Abfrage wird asynchron abgeschlossen.

Hinweise

Wenn ein Aufruf von DnsQueryEx synchron abgeschlossen wird (d. h. der Funktionsrückgabewert ist nicht DNS_REQUEST_PENDING), enthält das pQueryRecords-Element von pQueryResults einen Zeiger auf eine Liste von DNS_RECORDS , und DnsQueryEx gibt entweder Fehler oder Erfolg zurück.

Die folgenden Bedingungen rufen einen synchronen Aufruf von DnsQueryEx auf und verwenden den DNS-Rückruf nicht:

Der DNS_QUERY_COMPLETION_ROUTINE Rückruf wird vom pQueryCompleteCallback-Member von pQueryRequest ausgelassen.
Eine Abfrage ist für den lokalen Computernamen und den Typ A oder AAAA Vom Typ Resource Records (RR) bestimmt.
Ein Aufruf von DnsQueryEx fragt eine IPv4- oder IPv6-Adresse ab.
Ein Aufruf von DnsQueryEx wird fehlerhaft zurückgegeben.

Wenn ein Aufruf von DnsQueryEx asynchron abgeschlossen wird, werden die Ergebnisse der Abfrage vom DNS_QUERY_COMPLETION_ROUTINE Rückruf in pQueryRequest zurückgegeben, das QueryStatus-Element von pQueryResults enthält DNS_REQUEST_PENDING, und DnsQueryEx gibt DNS_REQUEST_PENDING zurück. Anwendungen sollten die pQueryResults-Struktur nachverfolgen , die an DnsQueryEx übergeben wird, bis der DNS-Rückruf erfolgreich ist. Anwendungen können eine asynchrone Abfrage mit dem von DnsQueryEx zurückgegebenen pCancelHandle-Handle abbrechen.

pCancelHandle wird von einem asynchronen Aufruf von DnsQueryEx zurückgegeben, und pQueryContext ist gültig, bis der DNS_QUERY_COMPLETION_ROUTINE DNS-Rückruf aufgerufen wird.

Hinweis Anwendungen werden über die asynchrone DnsQueryEx-Vervollständigung über den DNS_QUERY_COMPLETION_ROUTINE Rückruf innerhalb desselben Prozesskontexts benachrichtigt.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 8 [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2012 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	windns.h
Bibliothek	Dnsapi.lib
DLL	Dnsapi.dll