Funzione DnsQueryEx (windns.h)

Articolo
07/14/2023

La funzione DnsQueryEx è l'interfaccia di query generica asincrona nello spazio dei nomi DNS. Fornisce agli sviluppatori di applicazioni un'interfaccia di risoluzione delle query DNS.

Come DnsQuery, DnsQueryEx può essere usato anche per eseguire query sincrone allo spazio dei nomi DNS.

Sintassi

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

Parametri

[in] pQueryRequest

Puntatore a una struttura DNS_QUERY_REQUEST o DNS_QUERY_REQUEST3 contenente le informazioni sulla richiesta di query.

Nota Omettendo il callback DNS_QUERY_COMPLETION_ROUTINE dal membro pQueryCompleteCallback di questa struttura, DnsQueryEx viene chiamato in modo sincrono.

[in, out] pQueryResults

Puntatore a una struttura DNS_QUERY_RESULT contenente i risultati della query. In input, il membro della versione di pQueryResults deve essere DNS_QUERY_RESULTS_VERSION1 e tutti gli altri membri devono essere NULL. Nell'output, i membri rimanenti verranno compilati come parte della query completata.

Nota Per le query asincrone, un'applicazione non deve liberare questa struttura finché non viene richiamato il callback DNS_QUERY_COMPLETION_ROUTINE . Al termine della query, la struttura DNS_QUERY_RESULT contiene un puntatore a un elenco di DNS_RECORDS che deve essere liberato usando DnsRecordListFree.

[in, out, optional] pCancelHandle

Puntatore a una struttura DNS_QUERY_CANCEL che può essere usata per annullare una query asincrona in sospeso.

Nota Un'applicazione non deve liberare questa struttura finché non viene richiamato il callback DNS_QUERY_COMPLETION_ROUTINE .

Valore restituito

La funzione DnsQueryEx include i valori restituiti seguenti:

Codice restituito	Descrizione
ERROR_SUCCESS	La chiamata è stata completata correttamente.
ERROR_INVALID_PARAMETER	I parametri pQueryRequest o pQueryRequest non sono inizializzati o contengono la versione errata.
DNS RCODE	La chiamata ha generato un errore RCODE .
DNS_INFO_NO_RECORDS	Nessun record nella risposta.
DNS_REQUEST_PENDING	La query verrà completata in modo asincrono.

Commenti

Se una chiamata a DnsQueryEx completa in modo sincrono (ad esempio, il valore restituito della funzione non è DNS_REQUEST_PENDING), il membro pQueryRecords di pQueryResults contiene un puntatore a un elenco di DNS_RECORDS e DnsQueryEx restituirà l'errore o l'esito positivo.

Le condizioni seguenti richiamano una chiamata sincrona a DnsQueryEx e non usano il callback DNS:

Il callback DNS_QUERY_COMPLETION_ROUTINE viene omesso dal membro pQueryCompleteCallback di pQueryRequest.
Una query è per il nome del computer locale e A o AAAA tipo Record risorse (RR).
Una chiamata a DnsQueryEx esegue query su un indirizzo IPv4 o IPv6.
Una chiamata a DnsQueryEx restituisce un errore.

Se una chiamata a DnsQueryEx viene completata in modo asincrono, i risultati della query vengono restituiti dal callback DNS_QUERY_COMPLETION_ROUTINE in pQueryRequest, il membro QueryStatus di pQueryResults contiene DNS_REQUEST_PENDING e DnsQueryEx restituisce DNS_REQUEST_PENDING. Le applicazioni devono tenere traccia della struttura pQueryResults passata a DnsQueryEx finché il callback DNS non riesce. Le applicazioni possono annullare una query asincrona usando l'handle pCancelHandle restituito da DnsQueryEx.

pCancelHandle restituito da una chiamata asincrona a DnsQueryEx e pQueryContext è valido fino a quando non viene richiamato il callback DNS DNS_QUERY_COMPLETION_ROUTINE .

Nota Le applicazioni ricevono una notifica al completamento di DnsQueryEx asincrona tramite il callback DNS_QUERY_COMPLETION_ROUTINE all'interno dello stesso contesto del processo.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 8 [solo app desktop]
Server minimo supportato	Windows Server 2012 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	windns.h
Libreria	Dnsapi.lib
DLL	Dnsapi.dll

Condividi tramite