WSAAsyncGetProtoByName 函式 (winsock2.h)

  • 發行項

WSAAsyncGetProtoByName 函式會以異步方式擷取對應至通訊協定名稱的通訊協議資訊。

語法

HANDLE WSAAPI WSAAsyncGetProtoByName(
  [in]  HWND       hWnd,
  [in]  u_int      wMsg,
  [in]  const char *name,
  [out] char       *buf,
  [out] int        buflen
);

參數

[in] hWnd

當異步要求完成時，將會收到訊息的視窗句柄。

[in] wMsg

異步要求完成時要接收的訊息。

[in] name

要解析之 Null 終止通訊協定名稱的指標。

[out] buf

要接收 Protoent 資料的數據區指標。 數據區必須大於 Protoent 結構的大小，因為 Windows Sockets 會使用數據區來包含 Protoent 結構以及 Protoent 結構成員所參考的所有數據。 建議使用 MAXGETHOSTSTRUCT 位元組的緩衝區。

[out] buflen

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

傳回值

傳回值會指定異步操作是否已成功起始。 這並不表示作業本身成功或失敗。

如果沒有發生錯誤， WSAAsyncGetProtoByName 會傳回非零值，這是要求異步工作句柄， (不會與 Windows HTASK) 混淆。 這個值可以透過兩種方式使用。 它可以用來使用 WSACancelAsyncRequest 取消作業，也可以藉由檢查 wParam 訊息參數來比對異步操作和完成訊息。

如果無法起始異步操作， WSAAsyncGetProtoByName 會傳回零值，而且可以呼叫 WSAGetLastError 來擷取特定錯誤號碼。

當應用程式視窗收到訊息時，可以設定下列錯誤碼。 如上所述，您可以使用 WSAGETASYNCERROR 宏，從回復訊息中的 lParam 擷取它們。

錯誤碼 意義
WSAENETDOWN
 網路子系統失敗。
WSAENOBUFS
 緩衝區空間不足。
WSAEFAULT
 名稱或 buf 參數不在行程地址空間的有效部分。
WSAHOST_NOT_FOUND
 找不到授權回應通訊協定。
WSATRY_AGAIN
 找不到非授權通訊協定，或伺服器失敗。
WSANO_RECOVERY
 無法復原的錯誤，無法存取通訊協議資料庫。
WSANO_DATA
 有效名稱，沒有要求類型的數據記錄。
 

下列錯誤可能會在函數調用時發生，並指出無法起始異步操作。

錯誤碼 意義
WSANOTINITIALISED 使用此函式之前，必須先進行成功的 WSAStartup 呼叫。
WSAENETDOWN 網路子系統失敗。
WSAEINPROGRESS 封鎖的 Windows Sockets 1.1 呼叫正在進行中，或者服務提供者仍在處理回呼函式。
WSAEWOULDBLOCK 異步操作目前無法排程，因為 Windows Sockets 實作中的資源或其他條件約束。

備註

WSAAsyncGetProtoByName 函式是 getprotobyname 的異步版本。 它用來從對應至指定通訊協定名稱的 Windows Sockets 資料庫中擷取通訊協定名稱和號碼。 Windows Sockets 會起始作業，並立即返回呼叫端，並傳回應用程式可用來識別作業的不透明異步工作句柄。 當作業完成時，如果呼叫端提供的任何) 複製到緩衝區，並將訊息傳送至應用程式的視窗，則結果會 (。

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

成功完成時，指定給原始函式呼叫的緩衝區包含 Protoent 結構。 若要存取這個結構的成員，原始緩衝區位址應該轉換成 Protoent 結構指標，並視需要存取。

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

Windows Sockets 會使用指定給此函式的緩衝區來建構 Protoent 結構，以及相同 Protoent 結構的成員所參考的數據區域內容。 為了避免上述 WSAENOBUFS 錯誤，應用程式應該提供至少 MAXGETHOSTSTRUCT 位元組的緩衝區 (，如 Winsock2.h) 中所定義。

使用 Winsock2.h 中定義的宏 WSAGETASYNCERROR 和 WSAGETASYNCBUFLEN，應該從 lParam 擷取錯誤碼和緩衝區長度：

#include <windows.h>

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

使用這些宏將最大化應用程式的原始程式碼可移植性。

規格需求

需求 值
最低支援的用戶端 Windows 2000 專業版 [僅限傳統型應用程式]
最低支援的伺服器 Windows 2000 Server [僅限傳統型應用程式]
目標平台 Windows
標頭 winsock2.h (包括 Winsock2.h)
程式庫 Ws2_32.lib
Dll Ws2_32.dll

另請參閱

WSACancelAsyncRequest

Winsock 函式

Winsock 參考

getprotobyname