DnsQueryEx function (windns.h)

Article
07/27/2022

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.

Syntax

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

Parameters

[in] pQueryRequest

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.

[in, out] pQueryResults

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.

[in, out, optional] pCancelHandle

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.

Return value

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.

Requirements

Requirement	Value
Minimum supported client	Windows 8 [desktop apps only]
Minimum supported server	Windows Server 2012 [desktop apps only]
Target Platform	Windows
Header	windns.h
Library	Dnsapi.lib
DLL	Dnsapi.dll