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

Функция 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 , содержащую результаты запроса. На входных данных элемент версииpQueryResults должен быть 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), элемент pQueryRecordspQueryResults содержит указатель на список DNS_RECORDS и DnsQueryEx вернет ошибку или успех.

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

  • Обратный вызов DNS_QUERY_COMPLETION_ROUTINE опущен в элементе pQueryCompleteCallbackpQueryRequest.
  • Запрос предназначен для имени локального компьютера и записей ресурсов типа A или AAAA (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 [только классические приложения]
Целевая платформа Windows
Header windns.h
Библиотека Dnsapi.lib
DLL Dnsapi.dll

См. также раздел