Поделиться через

Функция 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, содержащую сведения о запросе.

Примечание. Пропуская обратный вызов DNS_QUERY_COMPLETION_ROUTINE из элемента pQueryCompleteCallback этой структуры, DnsQueryEx называется синхронно.
 

[in, out] pQueryResults

Указатель на структуру DNS_QUERY_RESULT, содержащую результаты запроса. Во входных данных -член pQueryResult s должен быть DNS_QUERY_RESULTS_VERSION1, а все остальные элементы должны быть NULL. В выходных данных остальные члены будут заполнены в рамках запроса.

Примечание для асинхронных запросов приложение не должно освободить эту структуру до вызова обратного вызова DNS_QUERY_COMPLETION_ROUTINE. По завершении запроса структура DNS_QUERY_RESULT содержит указатель на список DNS_RECORDS, который должен быть освобожден с помощью DnsRecordListFree.
 

[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), pQueryRecords член pQueryResults содержит указатель на список DNS_RECORDS и DnsQueryEx вернет ошибку или успешное выполнение.

Следующие условия вызывают синхронный вызов DnsQueryEx и не используют обратный вызов DNS:

  • Обратный вызов DNS_QUERY_COMPLETION_ROUTINE опущен из pQueryCompleteCallback члена pQueryRequest.
  • Запрос — это имя локального компьютера и A или AAAA типа Resource Records (RR).
  • Вызов DnsQueryEx запрашивает IPv4 или IPv6-адрес.
  • Вызов DnsQueryEx возвращается в ошибке.
Если вызов DnsQueryEx завершается асинхронно, результаты запроса возвращаются обратным вызовом DNS_QUERY_COMPLETION_ROUTINE в pQueryRequest, элемент QueryStatuspQueryResults содержит DNS_REQUEST_PENDING, а DnsQueryEx возвращает DNS_REQUEST_PENDING. Приложения должны отслеживать структуру pQueryResults, передаваемую в DnsQueryEx до успешного выполнения обратного вызова DNS. Приложения могут отменить асинхронный запрос с помощью дескриптора pCancelHandle, возвращаемого DnsQueryEx.

pCancelHandle возвращается из асинхронного вызова DnsQueryEx и pQueryContext до вызова обратного вызова DNS DNS_QUERY_COMPLETION_ROUTINE.

Примечание Приложения уведомляются об асинхронном завершении DnsQueryEx через обратный вызов DNS_QUERY_COMPLETION_ROUTINE в том же контексте процесса.
 

Требования

Требование Ценность
минимальные поддерживаемые клиентские Windows 8 [только классические приложения]
минимальный поддерживаемый сервер Windows Server 2012 [только классические приложения]
целевая платформа Виндоус
заголовка windns.h
библиотеки Dnsapi.lib
DLL Dnsapi.dll

См. также