Export (0) Print
Expand All

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:

Return codeDescription
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

Minimum supported client

Windows 8 [desktop apps only]

Minimum supported server

Windows Server 2012 [desktop apps only]

Header

Windns.h

Library

Dnsapi.lib

DLL

Dnsapi.dll

See also

DnsCancelQuery
DnsQuery
DNS_QUERY_COMPLETION_ROUTINE

 

 

Community Additions

ADD
Show:
© 2014 Microsoft