WSAAsyncGetHostByName()

本函式是主機名的主機名稱和地址信息。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()