WSAAsyncGetHostByAddr 宏 (wsipv6ok.h)

项目
03/13/2024

WSAAsyncGetHostByAddr 函数以异步方式检索与地址对应的主机信息。

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

语法

void WSAAsyncGetHostByAddr(
  [in]   a,
  [in]   b,
  [in]   c,
  [in]   d,
  [in]   e,
  [out]  f,
  [in]   g
);

参数

[in] a

异步请求完成时接收消息的窗口的句柄。

[in] b

异步请求完成时要接收的消息。

[in] c

指向主机的网络地址的指针。主机地址按网络字节顺序存储。

[in] d

地址的长度（以字节为单位）。

[in] e

地址的类型。

[out] f

指向用于接收 hostent 数据的数据区域的指针。数据区域必须大于 hostent 结构的大小，因为 Windows 套接字使用数据区域来包含 hostent 结构和 hostent 结构的成员引用的所有数据。建议使用 MAXGETHOSTSTRUCT 字节的缓冲区。

[in] g

buf 参数的数据区域的大小（以字节为单位）。

返回值

无

备注

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

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

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

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

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

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

#include <windows.h>

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

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

要求

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