LPWSPGETOVERLAPPEDRESULT 回呼函式 (ws2spi.h)

發行項
03/13/2024

LPWSPGetOverlappedResult 函式會傳回指定套接字上重迭作業的結果。

語法

LPWSPGETOVERLAPPEDRESULT Lpwspgetoverlappedresult;

BOOL Lpwspgetoverlappedresult(
  [in]  SOCKET s,
  [in]  LPWSAOVERLAPPED lpOverlapped,
  [out] LPDWORD lpcbTransfer,
  [in]  BOOL fWait,
  [out] LPDWORD lpdwFlags,
  [out] LPINT lpErrno
)
{...}

參數

[in] s

識別套接字。這是由 呼叫 LPWSPRecv、 LPWSPRecvFrom、LPWSPRecvFrom、 LPWSPSend、 LPWSPSendTo 或 LPWSPIoctl 啟動重迭作業時所指定的相同套接字。

[in] lpOverlapped

啟動重迭作業時所指定 之 WSAOverlapped 結構的指標。

[out] lpcbTransfer

32 位變數的指標，可接收傳送或接收作業或 LPWSPIoctl 實際傳輸的位元元數目。

[in] fWait

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

[out] lpdwFlags

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

[out] lpErrno

錯誤碼的指標。

傳回值

如果 LPWSPGetOverlappedResult 成功，則傳回值為 TRUE。這表示重疊的作業已順利完成，且 lxmlTransfer 所指向的值已更新。如果 LPWSPGetOverlappedResult 傳回 FALSE，這表示重疊的作業尚未完成或重疊的作業已完成，但發生錯誤或完成狀態無法判斷，因為 LPWSPGetOverlappedResult 有一或多個參數中的錯誤。失敗時， 不會更新 lspaTransfer 所指向的值。 lpErrno 參數表示 (LPWSPGetOverlappedResult 或相關聯重迭作業) 失敗的原因。

錯誤碼	意義
WSAENETDOWN	網路子系統失敗。
WSAENOTSOCK	描述項不是套接字。
WSA_INVALID_HANDLE	WSAOverlapped 結構的 hEvent 成員不包含有效的事件物件句柄。
WSAEINVAL	無法接受其中一個參數。
WSA_IO_INCOMPLETE	fWait 參數為 FALSE，且 I/O 作業尚未完成。

備註

LPWSPGetOverlappedResult 函式所報告的結果，是指定的套接字最後一個重迭作業，其中提供指定的 WSAOverlapped 結構，以及作業的結果擱置中。當啟動作業的函式傳回SOCKET_ERROR，且 lpErrno WSA_IO_PENDING時，就會指出暫止作業。當 I/O 作業擱置時，啟動作業的函式會將 WSAOVERLAPPED 結構的 hEvent 成員重設為非簽署狀態。然後，當擱置作業完成時，系統會將事件物件設定為已發出訊號的狀態。

如果 fWait 參數為 TRUE，LPWSPGetOverlappedResult 會藉由封鎖並等候事件物件處於訊號狀態來判斷擱置作業是否已完成。只有在要求 I/O 作業時選取事件型完成通知時，用戶端才能將 fWait 參數設定為 TRUE 。如果選取另一種形式的通知，WSAOverlapped 結構的 hEvent 成員使用方式不同，並將 fWait 設定為 TRUE 會導致無法預期的結果。

注意

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

與 WPUCompleteOverlappedRequest 互動

WPUCompleteOverlappedRequest 的行為會將一些條件約束放在服務提供者實作 LPWSPGetOverlappedResult 的方式，因為只有 WSAOverlapped 結構的 Offset 和 OffsetHigh 成員是由服務提供者獨佔控制，即使服務提供者 (位元組計數、旗標和錯誤) 必須由 LPWSPGetOverlappedResult 從結構擷取。只要服務提供者與 WPUCompleteOverlappedRequest 的行為正確互動，服務提供者就可以以任何方式達成此目的。下列描述呈現一般實作：

在重疊處理開始時，服務提供者會將 [內部 ] 設定為 [WSS_OPERATION_IN_PROGRESS]。

當 I/O 作業完成時，提供者會將 OffsetHigh 設定為作業所產生的 Windows Sockets 2 錯誤碼、將 Offset 設定為 I/O 作業所產生的旗標，並呼叫 WPUCompleteOverlappedRequest，將傳輸位元組計數傳遞為其中一個參數。 WPUCompleteOverlappedRequest 最終會將 InternalHigh 設定為傳送位元組計數，然後將 Internal 設定為WSS_OPERATION_IN_PROGRESS以外的值。

呼叫 LPWSPGetOverlappedResult 時 ，服務提供者會檢查內部。如果WSS_OPERATION_IN_PROGRESS，提供者會等候 hEvent 成員中的事件句柄，或根據 LPWSPGetOverlappedResult 的 fWait 旗標設定傳回錯誤。如果未進行中，或在等候完成之後，提供者會分別從InternalHigh、OffsetHigh 和 Offset 傳回值做為傳輸計數、作業結果錯誤碼和旗標。

規格需求

需求	值
最低支援的用戶端	Windows 2000 Professional [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限桌面應用程式]
標頭	ws2spi.h