本函式是gethostbyname()的異步版本，是用來獲取對應於一個主機名的主機名稱和地址信息。Windows Sockets的實現啟動該操作後立刻返回調用方，並傳回一個異步任務句柄，應用程式可以用它來標識該操作。當操作完成時，結果（若有的話）將會拷貝到調用方提供的緩衝區，同時向應用程式的視窗發一條訊息。
基本介紹
- 外文名：WSAAsyncGetHostByName()
- 版本：gethostbyname()的異步版本
- 作用：獲取對應於一個主機名的
- 錯誤代碼：為WSAENOBUFS
- 運行系統：Windows Sockets
簡介,錯誤代碼,
簡介
簡述：
#include <winsock.h>
HANDLE PASCAL FAR WSAAsyncGetHostByName (HWND hWnd,
unsigned int wMsg,const char FAR * name,char FAR * buf,
int buflen);
hWnd 當異步請求完成時，應該接收訊息的視窗句柄.
wMsg 當異步請求完成時，將要接收的訊息.
name 指向主機名的指針.
buf 接收hostent數據的數據區指針.注意該數據區必須大於hostent結構的大小.這是因為不僅Windows Sockets實現要用該數據區域容納hostent結構，hostent結構的成員引用的所有數據也要在該區域內.建議用戶提供一個MAXGETHOSTSTRUCT位元組大小的緩衝區.
buflen上述數據區的大小.
注釋：
本函式是gethostbyname()的異步版本，是用來獲取對應於一個主機名的主機名稱和地址信息.Windows Sockets的實現啟動該操作後立刻返回調用方，並傳回一個異步任務句柄，應用程式可以用它來標識該操作.當操作完成時，結果（若有的話）將會拷貝到調用方提供的緩衝區，同時向應用程式的視窗發一條訊息.
當異步操作完成時，應用程式的視窗hWnd接收到訊息wMsg. wParam參數包含了初次函式調用時返回的異步任務句柄.lParam的高16位包含著錯誤代碼.該代碼可以是winsock.h中定義的任何錯誤.錯誤代碼為0說明異步操作成功.在成功完成的情況下，提供給初始函式調用的緩衝區中包含了一個hostent結構.為存取該結構中的元素，初始的緩衝區指針應置為hostent結構的指針，並一如平常地存取.
注意若錯誤代碼為WSAENOBUFS，它說明在初始調用時由buflen指出的緩衝區大小對於容納所有的結果信息來說太小了.在這種情況下，lParam的低16位含有提供所有信息所需的緩衝區大小數值.如果應用程式認為獲取的數據不夠，它就可以在設定了足夠容納所需信息的緩衝區後，重新調用WSAAsyncGetHostByName().（也就是大於lParam低16位提供的大小.)
錯誤代碼和緩衝區大小應使用WSAGETASYNCERROR和WSAGETASYNCBUFLEN宏從lParam中取出.兩個宏定義如下：
#define WSAGETASYNCERROR(lParam) HIWORD(lParam)
#define WSAGETASYNCBUFLEN(lParam) LOWORD(lParam)
使用這些宏可最大地提高應用程式原始碼的可移植性.
返回值：
返回值指出異步操作是否成功地初啟.注意它並不隱含操作本身的成功或失敗.
若操作成功地初啟，WSAAsyncGetHostByName（）返回一個HANDLE類型的非0值，作為請求需要的異步任務句柄.該值可在兩種方式下使用.它可通過WSACancelAsyncRequest()用來取消該操作.也可通過檢查wParam訊息參數，以匹配異步操作和完成訊息.
如果異步操作不能初啟，WSAAsyncGetHostByName（）返回一個0值，並且可使用WSAGetLastError（）來獲取錯誤號.
評價：
Windows Sockets的實現使用提供給該函式的緩衝區來構造hostent結構以及該結構成員引用的數據區內容.為避免上述的WSAENOBUFS錯誤，應用程式應提供一個至少MAXGETHOSTSTRUCT位元組大小的緩衝區.
關於Windows Sockets提供者的說明：
Windows Sockets的實現應保證訊息能成功地傳給應用程式.如果PostMessage（）操作失敗，Windows Sockets的實現必須重發該訊息－只要視窗存在.
Windows Sockets的提供者在訊息中組織lParam時應使用WSAMAKEASYNCREPLY宏.
錯誤代碼
在應用程式的視窗收到訊息時可能會設定下列的錯誤代碼.如上所述，它們可以通過WSAGETASYNCERROR宏從應答的訊息lParam中取出.
WSAENETDOWN WINDOWS SOCKETS實現已檢測到網路子系統故障.
WSAENOBUFS 可用的緩衝區空間不足或沒有.
WSAHOST_NOT_FOUND 未找到授權應答主機.
WSATRY_AGAIN 未找到非授權應答主機，或SERVERFAIL.
WSANO_RECOVERY 不可恢復性錯誤，FORMERR,REFUSED,NOTIMP.
WSANO_DATA 合法名，無請求類型的數據記錄.
下列的錯誤可能在函式調用時發生，指出異步操作不能初啟.
WSANOTINITIALISED 在使用本API前必須進行一次成功的WSAStartup（）調用.
WSAENETDOWN WINDOWS SOCKETS實現已檢測到網路子系統故障.
WSAEINPROGRESS 一個阻塞的Windows Sockets操作正在進行.
WSAEWOULDBLOCK 本異步操作此時由於Windows Sockets實現的資源或其它限制的制約而無法調度.
參見：
gethostbyname(),WSACancelAsyncRequest()
