Макрос WSAAsyncGetHostByName (wsipv6ok.h)

Статья
08/28/2023

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

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

Синтаксис

void WSAAsyncGetHostByName(
  [in]   a,
  [in]   b,
  [in]   c,
  [out]  d,
  [in]   e
);

Параметры

[in] a

Дескриптор окна, которое получит сообщение по завершении асинхронного запроса.

[in] b

Сообщение, которое будет получено по завершении асинхронного запроса.

[in] c

Указатель на имя узла, завершаемого null.

[out] d

Указатель на область данных для получения данных узла . Область данных должна быть больше, чем размер структуры узла , так как указанная область данных используется сокетами Windows для размещения структуры и всех данных, на которые ссылаются члены структуры узла . Рекомендуется использовать буфер в байтах MAXGETHOSTSTRUCT.

[in] e

Размер области данных для параметра buf в байтах.

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

None

Remarks

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

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

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

Если код ошибки — WSAENOBUFS, размер буфера, указанного buflen в исходном вызове, был слишком мал, чтобы содержать все полученные сведения. В этом случае низкие 16 бит lParam содержат размер буфера, необходимый для предоставления всей необходимой информации. Если приложение решит, что частичные данные неадекватны, оно может повторно вывести вызов функции WSAsyncGetHostByName с буфером, достаточно большим для получения всех нужных сведений (т. е. не меньше, чем низкие 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)

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

WSAsyncGetHostByName гарантированно разрешает строку, возвращенную при успешном вызове gethostname.

Требования

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