WPUCompleteOverlappedRequest 函式 (ws2spi.h)

  • 發行項

WPUCompleteOverlappedRequest 函式會針對重疊的 I/O 作業執行重疊的 I/O 完成通知。

語法

int WPUCompleteOverlappedRequest(
  [in]  SOCKET          s,
  [in]  LPWSAOVERLAPPED lpOverlapped,
  [in]  DWORD           dwError,
  [in]  DWORD           cbTransferred,
  [out] LPINT           lpErrno
);

參數

[in] s

WPUCreateSocketHandle 所建立的服務提供者套接字。

[in] lpOverlapped

與要通知完成之重疊 I/O 作業相關聯的 WSAOVERLAPPED 結構的指標。

[in] dwError

要通知完成的重疊 I/O 作業完成狀態。

[in] cbTransferred

傳輸至用戶端緩衝區或從用戶端緩衝區傳輸的位元組數目 (取決於重疊 I/O 作業的傳送或接收本質，其完成時間是通知) 。

[out] lpErrno

執行此函式所產生的錯誤碼指標。

傳回值

如果沒有發生錯誤，WPUCompleteOverlappedRequest 會傳回零，並根據用戶端所選取的機制通知完成重疊的 I/O 作業， (訊號表示在 lpOverlapped 所參考的 WSAOVERLAPPED 結構中找到的事件，以及/或將完成狀態報告排入與套接字相關聯的完成埠，前提是完成埠與套接字相關聯) 。 否則， WPUCompleteOverlappedRequest 會傳回SOCKET_ERROR，而且 lpErrno 中提供特定的錯誤碼。

錯誤碼 意義
WSAEINVAL
 傳入 s 參數的套接字不是 WPUCreateSocketHandle 所建立的套接字。

備註

WPUCompleteOverlappedRequest 函式會針對重疊的 I/O 作業執行重疊的 I/O 完成通知，其中用戶端指定的完成機制不是使用者模式-異步過程調用 (APC) 。 此函式只能用於 WPUCreateSocketHandle 所建立的套接字句柄。

**注意** 此函式與其他函式不同，其中具有 “WPU” 前置詞，因為它無法透過 azureall 數據表進行存取。 相反地，它會直接透過 Ws2_32.dll 導出。 需要呼叫此函式的服務提供者應該與 WS2_32.lib 連結，或使用適當的操作系統函式，例如 LoadLibrary 和 GetProcAddress 來擷取函式指標。
 
服務提供者會使用函式 **WPUCompleteOverlappedRequest**，這些服務提供者不會直接針對它們公開的套接字句柄實作可安裝文件系統 (IFS) 功能。 它會針對指定完成通知不是使用者模式 APC 的任何重疊 I/O 要求執行完成通知。 **WPUCompleteOverlappedRequest** 僅支援 WPUCreateSocketHandle 所建立的套接字句柄，而不是直接由服務提供者建立的套接字。

如果客戶端選取使用者模式 APC 作為通知方法，服務提供者應該使用 WPUQueueApc 或其他適當的作業系統函式來執行完成通知。 如果用戶端未選取使用者模式 APC，則未直接實作 IFS 功能的服務提供者無法判斷用戶端是否與套接字句柄建立關聯完成埠。 因此，它無法判斷完成通知方法是否應該將完成狀態記錄排入完成埠，或發出 WSAOVERLAPPED 結構中所找到事件的訊號。 Windows Socket 2 架構會追蹤與 WPUCreateSocketHandle 所建立套接字的任何完成埠關聯，而且可以在完成埠型通知或事件型通知之間做出正確的決策。

當 WPUCompleteOverlappedRequest 排入完成指示時，它會將 WSAOVERLAPPED 結構的 InternalHigh 成員設定為傳輸的位元組計數。 然後，它會將 內部 成員設定為特殊值以外的某些 OS 相依值WSS_OPERATION_IN_PROGRESS。 WPUCompleteOverlappedRequest 傳回這些值之前可能會稍有延遲，因為處理可能會以異步方式發生。 不過， InternalHigh 值 (位元組計數) 一定是在設定 Internal 時設定 。

WPUCompleteOverlappedRequest 的運作方式如所述， (用戶端要求執行完成通知，) 套接字句柄是否已與完成埠相關聯。

與 WSPGetOverlappedResult 互動

WPUCompleteOverlappedRequest 的行為會將一些條件約束放在服務提供者實作 WSPGetOverlappedResult 的方式上，因為只有 WSAOVERLAPPED 結構的 Offset 和 OffsetHigh 成員是由服務提供者獨佔控制，但必須透過 WSPGetOverlappedResult 從結構擷取三個值 (位元組計數、旗標和錯誤) 。 只要服務提供者與 WPUCompleteOverlappedRequest 的行為正確互動，服務提供者就可以選擇這種方式。 不過，典型的實作如下所示：

  • 在重疊處理開始時，服務提供者會將 [內部 ] 設定為 WSS_OPERATION_IN_PROGRESS。
  • 當 I/O 作業完成時，提供者會將 OffsetHigh 設定為作業所產生的 Windows Socket 2 錯誤碼、將 Offset 設定為 I/O 作業所產生的旗標，並呼叫 WPUCompleteOverlappedRequest，傳遞傳輸位元組計數做為其中一個參數。 WPUCompleteOverlappedRequest 最終會將 InternalHigh 設定為傳輸位元組計數，然後將 Internal 設定為WSS_OPERATION_IN_PROGRESS以外的值。
  • 呼叫 WSPGetOverlappedResult 時，服務提供者會檢查 內部。 如果WSS_OPERATION_IN_PROGRESS，提供者會等候 hEvent 成員中的事件句柄，或根據 WSPGetOverlappedResult 的 FWAIT 旗標設定傳回錯誤。 如果未進行中，或在等候完成之後，提供者會分別從 InternalHigh、 OffsetHigh 和 Offset 傳回值，做為傳輸計數、作業結果錯誤碼和旗標。

規格需求

需求 值
最低支援的用戶端 Windows 2000 專業版 [僅限傳統型應用程式]
最低支援的伺服器 Windows 2000 Server [僅限傳統型應用程式]
目標平台 Windows
標頭 ws2spi.h

另請參閱

WPUCreateSocketHandle

WPUQueueApc

WSAOVERLAPPED

WSPGetOverlappedResult