基本介紹
- 外文名：WSAAsyncGetProtoByNumber()
- 用途：獲取對應於一個協定號的協定名稱和代號
簡述,注釋,評價,錯誤代碼,
簡述
獲得對應於一個協定號的協定信息.－異步版本.
#include <winsock.h>
HANDLE PASCAL FAR WSAAsyncGetProtoByNumber (
HWND hWnd,
unsigned int wMsg,
int number,
char FAR * buf,
int buflen
）；
hWnd 當異步請求完成時，應該接收訊息的視窗句柄.
wMsg 當異步請求完成時，將要接收的訊息.
number 要獲得的協定號，以主機位元組序.
buf 接收protoent數據的數據區指針.注意該數據區必須大於protoent結構的大小.這是因為不僅Windows Sockets實現要用該數據區域容納protoent結構，protoent結構的成員引用的所有數據也要在該區域內. 建議用戶提供一個MAXGETHOSTSTRUCT位元組大小的緩衝區.
buflen 上述數據區的大小.
注釋
當異步操作完成時，應用程式的視窗hWnd接收到訊息wMsg. wParam參數包含了初次函式調用時返回的異步任務句柄.lParam的高16位包含著錯誤代碼.該代碼可以是winsock.h中定義的任何錯誤.錯誤代碼為0說明異步操作成功.在成功完成的情況下，提供給初始函式調用的緩衝區中包含了一個protoent結構.為存取該結構中的元素，初始的緩衝區指針應置為protoent結構的指針，並一如平常地存取.
注意若錯誤代碼為WSAENOBUFS，它說明在初始調用時由buflen指出的緩衝區大小對於容納所有的結果信息來說太小了.在這種情況下，lParam的低16位含有提供所有信息所需的緩衝區大小數值.如果應用程式認為獲取的數據不夠，它就可以在設定了足夠容納所需信息的緩衝區後，重新調用WSAAsyncGetProtoByNumber().（也就是大於lParam低16位提供的大小.)
錯誤代碼和緩衝區大小應使用WSAGETASYNCERROR和WSAGETASYNCBUFLEN宏從lParam中取出.兩個宏定義如下：
#define WSAGETASYNCERROR(lParam) HIWORD(lParam)
#define WSAGETASYNCBUFLEN(lParam) LOWORD(lParam)
使用這些宏可最大地提高應用程式原始碼的可移植性.
返回值：
返回值指出異步操作是否成功地初啟.注意它並不隱含操作本身的成功或失敗.
若操作成功地初啟，WSAAsyncGetProtoByNumber（）返回一個HANDLE類型的非0值，作為請求需要的異步任務句柄.該值可在兩種方式下使用.它可通過WSACancelAsyncRequest()用來取消該操作.也可通過檢查wParam訊息參數，以匹配異步操作和完成訊息.
如果異步操作不能初啟，WSAAsyncGetProtoByNumber（）返回一個0值，並且可使用WSAGetLastError（）來獲取錯誤號.
評價
Windows Sockets的實現使用提供給該函式的緩衝區來構造protoent結構以及該結構成員引用的數據區內容.為避免上述的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實現的資源或其它限制的制約而無法調度.
參見：
getprotobynumber(),WSACancelAsyncRequest()
