WSARecvEx 函式 (mswsock.h)

發行項
03/05/2024

WSARecvEx 函式會從連接的套接字或系結的無連線套接字接收數據。 WSARecvEx 函式類似於 recv 函式，不同之處在於 flags 參數只會用來傳回資訊。在使用數據報通訊協定時收到部分訊息時，會在函式傳回時，在 flags 參數中設定MSG_PARTIAL位。

注意WSARecvEx 函式是 Windows Sockets 規格的 Microsoft 特定延伸模組。

語法

int WSARecvEx(
  [in]      SOCKET s,
  [out]     char   *buf,
  [in]      int    len,
  [in, out] int    *flags
);

參數

[in] s

識別已連線套接字的描述項。

[out] buf

要接收傳入數據的緩衝區指標。

[in] len

buf 參數所指向之緩衝區的長度，以位元組為單位。

[in, out] flags

指出數據報套接字是否完全或部分接收訊息的指標。

傳回值

如果沒有發生錯誤， WSARecvEx 會傳回收到的位元元組數目。如果連線已關閉，則會傳回零。此外，如果收到部分訊息，則會在 flags 參數中設定MSG_PARTIAL位。如果收到完整的訊息，則不會在旗標中設定MSG_PARTIAL

否則，會傳回SOCKET_ERROR的值，而且可以呼叫 WSAGetLastError 來擷取特定的錯誤碼。

重要對於數據流導向傳輸通訊協議，永遠不會在 WSARecvEx 傳回時設定MSG_PARTIAL。此函式的行為與數據流傳輸通訊協定的 recv 函式相同。

錯誤碼	意義
WSAECONNABORTED	此虛擬電路由於逾時或其他錯誤而終止。此通訊端無法再使用，應用程式應予以關閉。
WSAECONNRESET	執行硬式或失敗關閉的遠端部分已重設此虛擬電路。此通訊端無法再使用，應用程式應予以關閉。在 UPD 資料包通訊端上，此錯誤表示先前的傳送作業造成了 ICMP「連接埠無法存取」訊息。
WSAEFAULT	buf 參數並未完全包含在用戶位址空間的有效部分。
WSAEINPROGRESS	封鎖的 Windows Sockets 1.1 呼叫正在進行中，或者服務提供者仍在處理回呼函式。
WSAEINTR	WSACancelBlockingCall 呼叫已取消封鎖) 呼叫 (。
WSAEINVAL	套接字尚未系結系結，或指定未知旗標，或已針對已啟用SO_OOBINLINE的套接字指定MSG_OOB，或只針對位元組數據流套接字指定 (，) len 為零或負數。
WSAENETDOWN	網路子系統失敗。
WSAENETRESET	針對連線導向套接字，此錯誤表示連線已因在作業進行時偵測到失敗的保持運作活動而中斷。如果是資料包通訊端，此錯誤表示已超過存留時間。
WSAENOTCONN	未連接此通訊端。
WSAENOTSOCK	描述項不是套接字。
WSAEOPNOTSUPP	已指定MSG_OOB，但套接字不是數據流樣式，例如類型SOCK_STREAM、與此套接字相關聯的通訊網域不支援 OOB 數據，或套接字是單向的，而且只支援傳送作業。
WSAESHUTDOWN	套接字已關閉;在叫用關閉后，無法在套接字上使用 WSARecvEx，以及如何設定為 SD_RECEIVE 或 SD_BOTH。
WSAETIMEDOUT	因為網路錯誤或因為對等系統無法回應，所以此連接已中斷。
WSAEWOULDBLOCK	套接字標示為非封鎖，而接收作業會封鎖。
WSANOTINITIALISED	使用此函式之前，必須先進行成功的 WSAStartup 呼叫。

備註

屬於 Windows Sockets 2 Microsoft 實作一部分的 WSARecvEx 函式類似於較常見的 recv 函式，不同之處在於 flags 參數用於單一特定用途。 flags 參數是用來指出使用訊息導向通訊協定時是否收到部分或完整訊息。

在輸入時會忽略 flags 參數所指向的值。因此，無法將旗標傳遞至 WSARecvEx 函式以修改其行為。 flags 參數所指向的值是在輸出上設定。這與 recv 和 WSARecv 函式不同，其中輸入上的 flags 參數所指向的值可以修改函式的行為。

WSARecvEx 和 recv 函式對於數據流導向通訊協議的行為相同。

flags 參數會容納兩種常見的情況，其中會接收部分訊息：

當應用程式的數據緩衝區大小小於訊息大小，且訊息會以兩個片段方式抵達時。
當訊息相當大且必須抵達數個片段時。

MSG_PARTIAL位是在收到部分訊息時，從 WSARecvEx 傳回的 flags 參數所指向的值中設定。如果收到完整的訊息，則不會在 flags 參數所指向的值中設定MSG_PARTIAL。

recv 函式與不同
WSARecvEx 和 WSARecv 函式中， recv 函式一律會針對訊息導向傳輸通訊協定的每個呼叫接收單一訊息。 recv 函式也沒有任何方法可向應用程式指出所接收的數據只是部分訊息。應用程式必須在每次呼叫后檢查錯誤碼 WSAEMSGSIZE，以建置自己的通訊協定，以檢查訊息是否部分或完整。當應用程式緩衝區小於所傳送的數據時，會將符合的訊息數量複製到使用者的緩衝區，並傳回錯誤碼 WSAEMSGSIZE。後續呼叫 recv 將會取得訊息的下一個部分。

針對訊息導向傳輸通訊協定所撰寫的應用程式，如果應用程式數據傳輸通訊協定不保證訊息重設大小，就應該撰寫此可能性。應用程式可以使用 recv 和管理通訊協定本身。或者，應用程式可以使用 WSARecvEx ，並檢查 已在 flags 參數中設定MSG_PARTIAL位。

WSARecvEx 函式可讓開發人員以更有效率的方式檢查收到的訊息是否為部分或完成，當非常大型的訊息以累加方式送達時。例如，如果應用程式傳送一 MB 訊息，傳輸通訊協議必須中斷訊息，才能透過實體網路傳送訊息。理論上，接收端的傳輸通訊協定可以緩衝訊息中的所有數據，但這在資源方面相當昂貴。相反地，可以使用 WSARecvEx ，將額外負荷降至最低，並消除應用程式型通訊協定的需求。

注意當該線程結束時，由指定線程起始的所有 I/O 都會取消。對於重疊的套接字，如果線程在作業完成之前關閉線程，擱置的異步操作可能會失敗。如需詳細資訊，請參閱 ExitThread 函式。

規格需求

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