Skip to content

Latest commit

 

History

History
171 lines (142 loc) · 6.96 KB

nf-windns-dnsqueryex.md

File metadata and controls

171 lines (142 loc) · 6.96 KB
Raw
UID title description helpviewer_keywords old-location tech.root ms.assetid ms.date ms.keywords req.header req.include-header req.target-type req.target-min-winverclnt req.target-min-winversvr req.kmdf-ver req.umdf-ver req.ddi-compliance req.unicode-ansi req.idl req.max-support req.namespace req.assembly req.type-library req.lib req.dll req.irql targetos req.typenames req.redist ms.custom f1_keywords dev_langs topic_type api_type api_location api_name
NF:windns.DnsQueryEx
DnsQueryEx function (windns.h)
The asynchronous generic query interface to the DNS namespace, and provides application developers with a DNS query resolution interface.
DnsQueryEx
DnsQueryEx function [DNS]
dns.dnsqueryex
windns/DnsQueryEx
dns\dnsqueryex.htm
DNS
22664B9A-5010-42E7-880B-8D5B16A9F2DC
12/05/2018
DnsQueryEx, DnsQueryEx function [DNS], dns.dnsqueryex, windns/DnsQueryEx
windns.h
Windows
Windows 8 [desktop apps only]
Windows Server 2012 [desktop apps only]
Dnsapi.lib
Dnsapi.dll
Windows
19H1
DnsQueryEx
windns/DnsQueryEx
c++
APIRef
kbSyntax
DllExport
Dnsapi.dll
DnsQueryEx

-description

The DnsQueryEx function is the asynchronous generic query interface to the DNS namespace. It provides application developers with a DNS query resolution interface.

Like DnsQuery, DnsQueryEx can be used to make synchronous queries to the DNS namespace as well.

-parameters

-param pQueryRequest [in]

A pointer to a DNS_QUERY_REQUEST or DNS_QUERY_REQUEST3 structure that contains the query request information.

Note  By omitting the DNS_QUERY_COMPLETION_ROUTINE callback from the pQueryCompleteCallback member of this structure, DnsQueryEx is called synchronously.
 

-param pQueryResults [in, out]

A pointer to a DNS_QUERY_RESULT structure that contains the results of the query. On input, the version member of pQueryResults must be DNS_QUERY_RESULTS_VERSION1 and all other members should be NULL. On output, the remaining members will be filled as part of the query complete.

Note  For asynchronous queries, an application should not free this structure until the DNS_QUERY_COMPLETION_ROUTINE callback is invoked. When the query completes, the DNS_QUERY_RESULT structure contains a pointer to a list of DNS_RECORDS that should be freed using DnsRecordListFree.
 

-param pCancelHandle [in, out, optional]

A pointer to a DNS_QUERY_CANCEL structure that can be used to cancel a pending asynchronous query.

Note  An application should not free this structure until the DNS_QUERY_COMPLETION_ROUTINE callback is invoked.
 

-returns

The DnsQueryEx function has the following possible return values:

Return code Description
ERROR_SUCCESS
 The call was successful.
ERROR_INVALID_PARAMETER
 Either the pQueryRequest or pQueryRequest parameters are uninitialized or contain the wrong version.
DNS RCODE
 The call resulted in an RCODE error.
DNS_INFO_NO_RECORDS
 No records in the response.
DNS_REQUEST_PENDING
 The query will be completed asynchronously.

-remarks

If a call to DnsQueryEx completes synchronously (i.e., the function return value is not DNS_REQUEST_PENDING), the pQueryRecords member of pQueryResults contains a pointer to a list of DNS_RECORDS and DnsQueryEx will return either error or success.

The following conditions invoke a synchronous call to DnsQueryEx and do not utilize the DNS callback:

  • The DNS_QUERY_COMPLETION_ROUTINE callback is omitted from the pQueryCompleteCallback member of pQueryRequest.
  • A query is for the local machine name and A or AAAA type Resource Records (RR).
  • A call to DnsQueryEx queries an IPv4 or IPv6 address.
  • A call to DnsQueryEx returns in error.
If a call to DnsQueryEx completes asynchronously, the results of the query are returned by the DNS_QUERY_COMPLETION_ROUTINE callback in pQueryRequest, the QueryStatus member of pQueryResults contains DNS_REQUEST_PENDING, and DnsQueryEx returns DNS_REQUEST_PENDING. Applications should track the pQueryResults structure that is passed into DnsQueryEx until the DNS callback succeeds. Applications can cancel an asynchronous query using the pCancelHandle handle returned by DnsQueryEx.

pCancelHandle returned from an asynchronous call to DnsQueryEx and pQueryContext is valid until the DNS_QUERY_COMPLETION_ROUTINE DNS callback is invoked.

Note  Applications are notified of asynchronous DnsQueryEx completion through the DNS_QUERY_COMPLETION_ROUTINE callback within the same process context.
 

-see-also