WSAAsyncGetServByPort 函式 (winsock.h)

WSAAsyncGetServByPort函式會以非同步方式擷取對應至埠和通訊協定的服務資訊。

語法

HANDLE WSAAsyncGetServByPort(
  [in]  HWND       hWnd,
  [in]  u_int      wMsg,
  [in]  int        port,
  [in]  const char *proto,
  [out] char       *buf,
  [in]  int        buflen
);

參數

[in] hWnd

當非同步要求完成時,應該接收訊息的視窗控制碼。

[in] wMsg

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

[in] port

服務的埠,依網路位元組順序排列。

[in] proto

通訊協定名稱的指標。 這可以是Null,在此情況下,WSAAsyncGetServByPort會搜尋s_port符合指定的第一個服務專案。 否則, WSAAsyncGetServByPort 會比對 proto

[out] buf

要接收 服務 資料的資料區域指標。 資料區域必須大於 服務結構 的大小,因為 Windows 通訊端會使用資料區域來包含 服務結構 ,以及 由服務 結構成員參考的所有資料。 建議使用 MAXGETHOSTSTRUCT 位元組的緩衝區。

[in] buflen

buf參數的資料區域大小,以位元組為單位。

傳回值

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

如果沒有發生錯誤, WSAAsyncGetServByPort 會傳回 類型為 HANDLE 的非零值,這是要求非同步工作控制碼, (不要與 Windows HTASK) 混淆。 這個值可以使用兩種方式。 它可以用來使用 WSACancelAsyncRequest取消作業,也可以藉由檢查 wParam 訊息參數來比對非同步作業和完成訊息。

如果無法起始非同步作業, WSAAsyncGetServByPort 會傳回零值,而且呼叫 WSAGetLastError可以擷取特定的錯誤號碼。

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

錯誤碼 意義
WSAENETDOWN
網路子系統失敗。
WSAENOBUFS
緩衝區空間不足。
WSAEFAULT
protobuf參數不在進程位址空間的有效部分中。
WSAHOST_NOT_FOUND
找不到授權回應埠。
WSATRY_AGAIN
找不到非授權埠,或伺服器失敗。
WSANO_RECOVERY
無法復原的錯誤,無法存取服務資料庫。
WSANO_DATA
有效名稱,沒有要求類型的資料記錄。
 

下列錯誤可能會在函式呼叫時發生,並指出無法起始非同步作業。

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

備註

WSAAsyncGetServByPort函式是getservbyport的非同步版本,可用來擷取對應至埠號碼的服務資訊。 Windows Sockets 會起始作業,並立即返回呼叫端,並傳回應用程式可用來識別作業的不透明非同步工作控制碼。 當作業完成時,如果呼叫端所提供的緩衝區有任何) ,並將訊息傳送至應用程式的視窗,則結果會 (。

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

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

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

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

錯誤碼和緩衝區長度應該使用 Winsock2.h 中定義的宏WSAGETASYNCERRORWSAGETASYNCBUFLEN,從lParam擷取:

#include <windows.h>

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

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

規格需求

   
最低支援的用戶端 Windows 2000 Professional [僅限傳統型應用程式]
最低支援的伺服器 Windows 2000 Server [僅限桌面應用程式]
目標平台 Windows
標頭 winsock.h (包含 Winsock2.h)
程式庫 Ws2_32.lib
Dll Ws2_32.dll

另請參閱

WSACancelAsyncRequest

Winsock 函式

Winsock 參考

getservbyport