WSAGetOverlappedResult 函式 (winsock2.h)

發行項
03/04/2024

WSAGetOverlappedResult 函式會擷取指定套接字上重迭作業的結果。

語法

BOOL WSAAPI WSAGetOverlappedResult(
  [in]  SOCKET          s,
  [in]  LPWSAOVERLAPPED lpOverlapped,
  [out] LPDWORD         lpcbTransfer,
  [in]  BOOL            fWait,
  [out] LPDWORD         lpdwFlags
);

參數

[in] s

識別套接字的描述項。

這是呼叫任何支援重迭作業的 Winsock 函式時所指定的套接字。這些函式包括 AcceptEx、ConnectEx、DisconnectEx、TransmitFile、TransmitPackets、WSARecv、WSARecvFrom、LPFN_WSARECVMSG (WSARecvMsg) 、WSASend、WSASendMsg、WSASendTo 和 WSAIoctl。

[in] lpOverlapped

WSAOVERLAPPED 結構的指標，在啟動重迭作業時指定。此參數不得為 NULL 指標。

[out] lpcbTransfer

32 位變數的指標，可接收傳送或接收作業或 WSAIoctl 函式實際傳輸的位元元組數目。此參數不得為 NULL 指標。

[in] fWait

旗標，指定函式是否應該等候擱置重疊的作業完成。如果 為 TRUE，則函式在作業完成之前不會傳回。如果 FALSE 和作業仍然擱置中，函式會傳回 FALSE ，而 WSAGetLastError 函式會傳回WSA_IO_INCOMPLETE。只有在重疊的作業選取事件型完成通知時， fWait 參數才能設定為 TRUE 。

[out] lpdwFlags

32 位變數的指標，將會收到一或多個補充完成狀態的旗標。如果重疊的作業是透過 WSARecv 或 WSARecvFrom 起始，此參數將會包含 lpFlags 參數的結果值。此參數不得為 NULL 指標。

傳回值

如果 WSAGetOverlappedResult 成功，則傳回值為 TRUE。這表示重疊的作業已順利完成，而且 lspaTransfer 所指向的值已更新。

如果 WSAGetOverlappedResult 傳回 FALSE，這表示重疊的作業尚未完成、重疊的作業已完成但發生錯誤，或重疊作業的完成狀態無法判斷，因為 WSAGetOverlappedResult 有一或多個參數中的錯誤。失敗時， 不會更新 lspaTransfer 所指向的值。使用 WSAGetLastError 判斷 WSAGetOverlappedResult 函式或相關聯重疊作業 () 失敗的原因。

錯誤碼	意義
WSANOTINITIALISED	使用這個函式之前，必須先進行成功的 WSAStartup 呼叫。
WSAENETDOWN	網路子系統失敗。
WSAENOTSOCK	描述項不是套接字。
WSA_INVALID_HANDLE	WSAOVERLAPPED 結構的 hEvent 參數不包含有效的事件物件句柄。
WSA_INVALID_PARAMETER	無法接受其中一個參數。
WSA_IO_INCOMPLETE	fWait 參數為 FALSE，且 I/O 作業尚未完成。
WSAEFAULT	一或多個 lpOverlapped、 lTransfer 或 lpdwFlags 參數不在使用者位址空間的有效部分。如果 lpOverlapped、 lwindowsTransfer 或 lpdwFlags 參數是 Windows Server 2003 和更早版本上的 NULL 指標，就會傳回此錯誤。

備註

WSAGetOverlappedResult 函式會報告 s 參數所指定套接字之 lpOverlapped 參數中指定的重疊作業結果。 WSAGetOverlappedResult 函式會傳遞套接字描述元和呼叫重疊函式時所指定的 WSAOVERLAPPED 結構。當啟動作業的函式傳回 FALSE 且 WSAGetLastError 函式傳回 WSA_IO_PENDING時，就會指出暫止作業。當 WSARecv 之類的 I/O 作業擱置時，啟動作業的函式會將 WSAOVERLAPPED 結構的 hEvent 成員重設為非簽署狀態。然後，當擱置作業完成時，系統會將事件物件設定為已發出訊號的狀態。

如果 fWait 參數為 TRUE，WSAGetOverlappedResult 會等候事件對象處於訊號狀態，判斷擱置作業是否已完成。用戶端可能會將 fWait 參數設定為 TRUE，但只有在要求 I/O 作業時選取事件型完成通知時。如果選取了另一種形式的通知，WSAOVERLAPPED 結構的 hEvent 參數用法會不同，並將 fWait 設定為 TRUE 會導致無法預期的結果。

如果 呼叫 WSAGetOverlappedResult 函式，並將 lpOverlapped、 lspaTransfer 或 lpdwFlags 參數設定為 Windows Vista 上的 NULL 指標，這會導致存取違規。如果 呼叫 WSAGetOverlappedResult 函式，並將 lpOverlapped、 lspaTransfer 或 lpdwFlags 參數設定為 Windows Server 2003 和更早版本上的 NULL 指標，這會導致傳回 WSAEFAULT 錯誤碼。

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

Windows Phone 8：Windows Phone 8 和更新版本上 Windows Phone 市集應用程式支援此函式。

Windows 8.1 和 Windows Server 2012 R2：Windows 8.1、Windows Server 2012 R2 及更新版本上的 Windows 市集應用程式支援此函式。

規格需求

需求	值
最低支援的用戶端	Windows 8.1、Windows Vista [傳統型應用程式 \|UWP 應用程式]
最低支援的伺服器	Windows Server 2003 [傳統型應用程式 \|UWP 應用程式]
目標平台	Windows
標頭	winsock2.h
程式庫	Ws2_32.lib
Dll	Ws2_32.dll