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 或 pQueryRequest 参数未初始化或包含错误的版本。
DNS RCODE
 调用导致 RCODE 错误。
DNS_INFO_NO_RECORDS
 响应中没有记录。
DNS_REQUEST_PENDING
 查询将以异步方式完成。

注解

如果对 DnsQueryEx 的调用同步完成 (即函数返回值未DNS_REQUEST_PENDING) ，则 pQueryResults 的 pQueryRecords 成员包含指向DNS_RECORDS列表的指针，而 DnsQueryEx 将返回错误或成功。

以下条件调用 DnsQueryEx 的同步调用，并且不使用 DNS 回调：

  • DNS_QUERY_COMPLETION_ROUTINE回调从 pQueryRequest 的 pQueryCompleteCallback 成员中省略。
  • 查询针对本地计算机名称和 A 或 AAAA 类型资源记录 (RR) 。
  • 调用 DnsQueryEx 会查询 IPv4 或 IPv6 地址。
  • 对 DnsQueryEx 的 调用返回错误。
如果异步完成对 DnsQueryEx 的调用，则查询结果由 pQueryRequest 中的DNS_QUERY_COMPLETION_ROUTINE回调返回，pQueryResults 的 QueryStatus 成员包含DNS_REQUEST_PENDING，DnsQueryEx 返回DNS_REQUEST_PENDING。 应用程序应跟踪传递到 DnsQueryEx 的 pQueryResults 结构，直到 DNS 回调成功。 应用程序可以使用 DnsQueryEx 返回的 pCancelHandle 句柄取消异步查询。

从对 DnsQueryEx 和 pQueryContext 的异步调用返回的 pCancelHandle 在调用DNS_QUERY_COMPLETION_ROUTINE DNS 回调之前有效。

注意通过同一进程上下文中的DNS_QUERY_COMPLETION_ROUTINE回调通知应用程序异步 DnsQueryEx 完成。
 

要求

要求 值
最低受支持的客户端 Windows 8 [仅限桌面应用]
最低受支持的服务器 Windows Server 2012 [仅限桌面应用]
目标平台 Windows
标头 windns.h
Library Dnsapi.lib
DLL Dnsapi.dll

另请参阅