DnsQueryEx function (windns.h)

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.


  [in]                PDNS_QUERY_REQUEST pQueryRequest,
  [in, out]           PDNS_QUERY_RESULT  pQueryResults,
  [in, out, optional] PDNS_QUERY_CANCEL  pCancelHandle


[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
The call was successful.
Either the pQueryRequest or pQueryRequest parameters are uninitialized or contain the wrong version.
The call resulted in an RCODE error.
No records in the response.
The query will be completed asynchronously.


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.


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

See also