WSAAsyncGetHostByAddr 巨集 (wsipv6ok.h)

發行項
03/04/2024

WSAAsyncGetHostByAddr 函式會以異步方式擷取對應至位址的主機資訊。

注意WSAAsyncGetHostByAddr 函式並非設計來提供數個位址的平行解析。因此，發出數個要求的應用程式不應預期會同時執行。或者，應用程式可以啟動另一個線程，並使用 getnameinfo 函式以 IP 版本無關的方式解析位址。建立 Windows Sockets 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 結構的大小，因為 Windows 套接字會使用數據區域來包含 hostent 結構，以及 hostent 結構成員所參考的所有數據。建議使用 MAXGETHOSTSTRUCT 位元組的緩衝區。

[in] g

buf 參數的數據區域大小，以位元組為單位。

傳回值

無

備註

WSAAsyncGetHostByAddr 函式是 gethostbyaddr 的異步版本。它用來擷取對應至網路位址的主機名和地址資訊。 Windows Sockets 會起始作業，並立即返回呼叫端，並傳回應用程式可用來識別作業的不透明異步工作句柄。當作業完成時，如果呼叫端所提供的緩衝區有任何) ，並將訊息傳送至應用程式的視窗，則結果會 (。

當異步操作完成時， hWnd 參數所指示的應用程式視窗會在 wMsg 參數中接收訊息。 wParam 參數包含原始函數調用所傳回的異步工作句柄。 lParam 的高 16 位包含任何錯誤碼。錯誤碼可以是 Winsock2.h 中所定義的任何錯誤。錯誤碼為零表示異步操作成功完成。

成功完成時，指定給原始函數調用的緩衝區會包含 hostent 結構。若要存取此結構的成員，原始緩衝區位址會轉換成 主機實體 結構指標，並視需要存取。

如果錯誤碼是 WSAENOBUFS，則原始呼叫中 buflen 所指定的緩衝區大小太小，無法包含所有產生的資訊。在此情況下， lParam 的低 16 位包含提供所有必要資訊所需的緩衝區大小。如果應用程式決定部分數據不足，它可以重新發出 WSAAsyncGetHostByAddr 函式呼叫，且緩衝區夠大，足以接收所有所需資訊 (，也就是不小於低 16 位的 lParam) 。

Windows Sockets 會使用指定給此函式的緩衝區來建構結構，以及相同主機實體結構成員所參考之數據區域的內容。為了避免 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)
程式庫	Ws2_32.lib
Dll	Ws2_32.dll