WSARecvEx 函式 (winsock.h)

發行項
03/15/2023

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
標頭	winsock.h (包括 Mswsock.h)
程式庫	Mswsock.lib
Dll	Mswsock.dll