Функция WSAsyncGetHostByAddr (winsock.h)

Статья
03/15/2023

Функция WSAsyncGetHostByAddr асинхронно извлекает сведения об узле, соответствующие адресу.

Примечание Функция WSAsyncGetHostByAddr не предназначена для параллельного разрешения нескольких адресов. Таким образом, приложения, которые выдают несколько запросов, не должны ожидать, что они будут выполняться одновременно. Кроме того, приложения могут запускать другой поток и использовать функцию getnameinfo для разрешения адресов независимо от IP-версии. Разработчикам, создающих приложения Windows Sockets 2, настоятельно рекомендуется использовать функцию getnameinfo , чтобы обеспечить плавный переход к совместимости IPv6.

Синтаксис

HANDLE WSAAsyncGetHostByAddr(
  HWND       hWnd,
  u_int      wMsg,
  const char *addr,
  int        len,
  int        type,
  char       *buf,
  int        buflen
);

Параметры

hWnd

TBD

wMsg

TBD

addr

TBD

len

TBD

type

TBD

buf

TBD

buflen

TBD

Возвращаемое значение

Возвращаемое значение указывает, была ли успешно инициирована асинхронная операция. Это не означает успешность или неудачу самой операции.

Если ошибка не возникает, WSAsyncGetHostByAddr возвращает ненулевое значение типа HANDLE, которое является дескриптором асинхронной задачи (не следует путать с windows HTASK) для запроса. Это значение можно использовать двумя способами. Его можно использовать для отмены операции с помощью WSACancelAsyncRequest или для сопоставления асинхронных операций и сообщений о завершении путем проверки параметра сообщения wParam .

Если асинхронная операция не может быть инициирована, WSAsyncGetHostByAddr возвращает нулевое значение, и конкретный номер ошибки можно получить, вызвав WSAGetLastError.

При получении сообщения в окне приложения можно задать следующие коды ошибок. Как описано выше, их можно извлечь из lParam в ответном сообщении с помощью макроса WSAGETASYNCERROR .

Код ошибки	Значение
WSAENETDOWN	Произошел сбой сетевой подсистемы.
WSAENOBUFS	Недостаточно места в буфере.
WSAEFAULT	Параметр addr или buf не находится в допустимой части адресного пространства процесса.
WSAHOST_NOT_FOUND	Достоверный узел ответа не найден.
WSATRY_AGAIN	Неавторитативный узел не найден или SERVERFAIL.
WSANO_RECOVERY	Неустранимые ошибки: FORMERR, REFUSED, NOTIMP.
WSANO_DATA	Допустимое имя, нет записи данных запрошенного типа.

Во время вызова функции могут возникать следующие ошибки, которые указывают на то, что не удалось инициировать асинхронную операцию.

Код ошибки	Значение
WSANOTINITIALISED	Перед использованием этой функции должен быть выполнен успешный вызов WSAStartup .
WSAENETDOWN	Произошел сбой сетевой подсистемы.
WSAEINPROGRESS	Выполняется блокирующий вызов Windows Sockets 1.1 или поставщик услуг по-прежнему обрабатывает функцию обратного вызова.
WSAEWOULDBLOCK	В настоящее время асинхронную операцию нельзя запланировать из-за ограничений ресурсов или других ограничений в реализации сокетов Windows.

Функция WSAsyncGetHostByAddr является асинхронной версией gethostbyaddr. Он используется для получения имени узла и сведений об адресе, которые соответствуют сетевому адресу. Сокеты Windows инициируют операцию и немедленно возвращаются вызывающей стороне, передавая непрозрачный асинхронный дескриптор задачи, который приложение может использовать для идентификации операции. После завершения операции результаты (если таковые имеются) копируются в буфер, предоставленный вызывающим объектом, и сообщение отправляется в окно приложения.

После завершения асинхронной операции окно приложения, указанное параметром hWnd , получает сообщение в параметре wMsg . Параметр wParam содержит дескриптор асинхронной задачи, возвращаемый исходным вызовом функции. Высокая 16 бит lParam содержит любой код ошибки. Код ошибки может быть любой ошибкой, как определено в Winsock2.h. Нулевой код ошибки указывает на успешное завершение асинхронной операции.

При успешном завершении буфер, указанный для исходного вызова функции, содержит структуру узла . Для доступа к членам этой структуры исходный адрес буфера приводится к указателю структуры размещения и обращается соответствующим образом.

Если код ошибки — WSAENOBUFS, размер буфера, указанного buflen в исходном вызове, был слишком мал, чтобы содержать все результирующие сведения. В этом случае низкие 16 бит lParam содержат размер буфера, необходимый для предоставления всей необходимой информации. Если приложение решит, что частичные данные неадекватны, оно может повторно вывести вызов функции WSAsyncGetHostByAddr с буфером, достаточно большим для получения всей необходимой информации (то есть не меньше, чем низкие 16 бит lParam).

Буфер, указанный для этой функции, используется сокетами Windows для создания структуры вместе с содержимым областей данных, на которые ссылаются члены одной и той же структуры размещения . Чтобы избежать ошибки WSAENOBUFS , приложение должно предоставить буфер не менее байтов MAXGETHOSTSTRUCT (как определено в Winsock2.h).

Код ошибки и длина буфера должны быть извлечены из lParam с помощью макросов WSAGETASYNCERROR и WSAGETASYNCBUFLEN, определенных в Winsock2.h как:

#include <windows.h>

#define WSAGETASYNCBUFLEN(lParam)           LOWORD(lParam)
#define WSAGETASYNCERROR(lParam)            HIWORD(lParam)

Использование этих макросов обеспечит максимальную переносимость исходного кода для приложения.

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	winsock.h (включая Winsock2.h, Winsock.h)
Библиотека	Ws2_32.lib
DLL	Ws2_32.dll