WSAAsyncGetHostByName 函数 (winsock2.h)

项目
03/13/2024

WSAAsyncGetHostByName 函数异步检索与主机名对应的主机信息。

注意WSAAsyncGetHostByName 函数并非旨在提供多个名称的并行解析。因此，发出多个请求的应用程序不应期望它们同时执行。或者，应用程序可以启动另一个线程，并使用 getaddrinfo 函数以与 IP 版本无关的方式解析名称。建议创建 Windows 套接字 2 应用程序的开发人员使用 getaddrinfo 函数，以便顺利过渡到 IPv6 兼容性。

语法

HANDLE WSAAPI WSAAsyncGetHostByName(
  HWND       hWnd,
  u_int      wMsg,
  const char *name,
  char       *buf,
  int        buflen
);

参数

hWnd

TBD

wMsg

TBD

name

TBD

buf

TBD

buflen

TBD

返回值

返回值指定异步操作是否已成功启动。它并不意味着操作本身是成功还是失败。

如果未发生错误， WSAAsyncGetHostByName 将返回 HANDLE 类型的非零值，该值是异步任务句柄， (不会与请求的 Windows HTASK) 混淆。可以通过两种方式使用此值。它可用于使用 WSACancelAsyncRequest 取消操作，也可以通过检查 wParam 消息参数来匹配异步操作和完成消息。

如果无法启动异步操作， WSAAsyncGetHostByName 将返回零值，并且可以通过调用 WSAGetLastError 来检索特定的错误号。

当应用程序窗口收到消息时，可以设置以下错误代码。如上所述，可以使用 WSAGETASYNCERROR 宏从回复消息中的 lParam 中提取它们。

错误代码	含义
WSAENETDOWN	网络子系统失败。
WSAENOBUFS	可用缓冲区空间不足。
WSAEFAULT	name 或 buf 参数不在进程地址空间的有效部分。
WSAHOST_NOT_FOUND	找不到权威应答主机。
WSATRY_AGAIN	找不到非授权主机，或 SERVERFAIL。
WSANO_RECOVERY	不可恢复的错误：FORMERR、REFUSED、NOTIMP。
WSANO_DATA	有效名称，没有请求类型的数据记录。

以下错误可能在函数调用时发生，并指示无法启动异步操作。

错误代码	含义
WSANOTINITIALISED	在使用此函数之前，必须成功调用 WSAStartup 。
WSAENETDOWN	网络子系统失败。
WSAEINPROGRESS	阻止 Windows Sockets 1.1 调用正在进行，或者服务提供程序仍在处理回调函数。
WSAEWOULDBLOCK	由于 Windows 套接字实现中的资源或其他约束，目前无法计划异步操作。

注解

WSAAsyncGetHostByName 函数是 gethostbyname 的异步版本，用于检索与主机名对应的主机名和地址信息。 Windows 套接字启动操作并立即返回调用方，传递回应用程序可用于标识操作的不透明异步任务句柄。操作完成后，如果任何) 复制到调用方提供的缓冲区中，结果 (，并将消息发送到应用程序的窗口。

异步操作完成后， hWnd 参数指示的应用程序窗口在 wMsg 参数中接收消息。 wParam 参数包含原始函数调用返回的异步任务句柄。 lParam 的高 16 位包含任何错误代码。错误代码可以是 Winsock2.h 中定义的任何错误。错误代码为零表示异步操作成功完成。

成功完成后，对原始函数调用指定的缓冲区将包含 hostent 结构。若要访问此结构的元素，应将原始缓冲区地址强制转换为 hostent 结构指针，并根据需要对其进行访问。

如果错误代码为 WSAENOBUFS，则原始调用中 buflen 指定的缓冲区大小太小，无法包含所有生成的信息。在这种情况下， lParam 的低 16 位包含提供所有必要信息所需的缓冲区大小。如果应用程序确定部分数据不足，它可以重新发出 WSAAsyncGetHostByName 函数调用，其缓冲区足够大，可以接收所有所需信息 (，即不小于 lParam) 的低 16 位。

Windows 套接字使用此函数指定的缓冲区来构造主机结构，以及同一 hostent 结构的成员引用的数据区域的内容。若要避免 WSAENOBUFS 错误，应用程序应提供至少包含 MAXGETHOSTSTRUCT 字节 (的缓冲区，如 Winsock2.h) 中定义。

应使用宏 WSAGETASYNCERROR 和 WSAGETASYNCBUFLEN 从 lParam 中提取错误代码和缓冲区长度，这些宏在 Winsock2.h 中定义为：

#include <windows.h>

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

使用这些宏将最大程度地提高应用程序的源代码的可移植性。

WSAAsyncGetHostByName 保证解析成功调用 gethostname 返回的字符串。

要求

要求	值
最低受支持的客户端	Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
目标平台	Windows
标头	winsock2.h (包括 Winsock2.h、Winsock.h)
Library	Ws2_32.lib
DLL	Ws2_32.dll