DnsQueryEx function

The DnsQueryEx function is the asynchronous generic query interface to the DNS namespace, and 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 WINAPI DnsQueryEx(
  _In_        PDNS_QUERY_REQUEST pQueryRequest,
  _Inout_     PDNS_QUERY_RESULT  pQueryResults,
  _Inout_opt_ PDNS_QUERY_CANCEL  pCancelHandle
);

Parameters

pQueryRequest [in]

A pointer to a DNS_QUERY_REQUEST 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.

 

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_REQUEST_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.

 

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.

 

Return value

The DnsQueryEx function has the following possible return values:

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.

Requirements

See also

DnsCancelQuery

DnsQuery

DNS_QUERY_COMPLETION_ROUTINE