共用方式為

DnsQueryEx 函式 （windns.h）

  • 發行項

DnsQueryEx 函式是 DNS 命名空間的異步泛型查詢介面。 它為應用程式開發人員提供 DNS 查詢解析介面。

如同 DnsQuery，DnsQueryEx 也可以用來對 DNS 命名空間進行同步查詢。

語法

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

參數

[in] pQueryRequest

包含查詢要求資訊的 DNS_QUERY_REQUEST 或 DNS_QUERY_REQUEST3 結構的指標。

注意 省略此結構的 pQueryCompleteCallback 成員的 DNS_QUERY_COMPLETION_ROUTINE 回呼，DnsQueryEx 會同步呼叫。
 

[in, out] pQueryResults

包含查詢結果之 DNS_QUERY_RESULT 結構的指標。 在輸入時，pQueryResults 的 版本 成員必須 DNS_QUERY_RESULTS_VERSION1，而且所有其他成員都應該 NULL。 在輸出中，其餘成員會在查詢完成時填入。

注意 針對異步查詢，應用程式在叫用 DNS_QUERY_COMPLETION_ROUTINE 回呼之前，不應該釋放這個結構。 當查詢完成時，DNS_QUERY_RESULT 結構會包含應該使用 dnsRecordListFree釋放之 DNS_RECORDS 清單的指標。
 

[in, out, optional] pCancelHandle

可用來取消暫止異步查詢之 DNS_QUERY_CANCEL 結構的指標。

注意 應用程式在叫用 DNS_QUERY_COMPLETION_ROUTINE 回呼之前，不應該釋放此結構。
 

傳回值

DnsQueryEx 函式具有下列可能的傳回值：

傳回碼 描述
ERROR_SUCCESS
 呼叫成功。
ERROR_INVALID_PARAMETER
 pQueryRequest 或 pQueryResults 參數未初始化或包含錯誤的版本。
DNS RCODE
 呼叫導致 RCODE 錯誤。
DNS_INFO_NO_RECORDS
 回應中沒有記錄。
DNS_REQUEST_PENDING
 查詢將會以異步方式完成。

言論

如果呼叫 DnsQueryEx 以同步方式完成（亦即函式傳回值不是 DNS_REQUEST_PENDING），pQueryRecordspQueryResults 的成員 包含 DNS_RECORDS 列表的指標，而 DnsQueryEx 會傳回錯誤或成功。

下列條件會叫用同步呼叫 DnsQueryEx，而且不會使用 DNS 回呼：

  • DNS_QUERY_COMPLETION_ROUTINE 回呼會從 pQueryCompleteCallback pQueryCompleteCall back pQueryRequest的成員中省略。
  • 查詢適用於本機計算機名稱和 A 或 AAAA 類型資源記錄 （RR）。
  • 呼叫 DnsQueryEx 會查詢 IPv4 或 IPv6 位址。
  • DnsQueryEx 的呼叫 傳回錯誤。
如果呼叫 DnsQueryEx 以異步方式完成，則查詢的結果會由 pQueryRequest中的 DNS_QUERY_COMPLETION_ROUTINE 回呼傳回，QueryStatus pQueryResults 成員 包含 DNS_REQUEST_PENDING，而 DnsQueryEx 會傳回 DNS_REQUEST_PENDING。 應用程式應該追蹤 pQueryResults 結構，該結構會傳遞至 DnsQueryEx，直到 DNS 回呼成功為止。 應用程式可以使用 DnsQueryEx所傳回的 pCancelHandle 句柄來取消異步查詢。

pCancelHandle 從異步呼叫傳回至 DnsQueryEx，且 pQueryContext 有效，直到叫用 DNS_QUERY_COMPLETION_ROUTINE DNS 回呼為止。

注意 應用程式會透過相同進程內容內的 DNS_QUERY_COMPLETION_ROUTINE 回呼，收到異步 DnsQueryEx 完成的通知。
 

要求

要求 價值
最低支援的用戶端 Windows 8 [僅限傳統型應用程式]
支援的最低伺服器 Windows Server 2012 [僅限傳統型應用程式]
目標平臺 窗戶
標頭 windns.h
連結庫 Dnsapi.lib
DLL Dnsapi.dll

另請參閱