WinUsb_GetOverlappedResult函式 (winusb.h)

發行項
03/04/2024

WinUsb_GetOverlappedResult函式會擷取指定檔案上重迭作業的結果。

語法

BOOL WinUsb_GetOverlappedResult(
  [in]  WINUSB_INTERFACE_HANDLE InterfaceHandle,
  [in]  LPOVERLAPPED            lpOverlapped,
  [out] LPDWORD                 lpNumberOfBytesTransferred,
  [in]  BOOL                    bWait
);

參數

[in] InterfaceHandle

裝置上第一個介面的不透明句柄，由 WinUsb_Initialize傳回。

[in] lpOverlapped

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

[out] lpNumberOfBytesTransferred

變數的指標，接收讀取或寫入作業實際傳輸的位元元組數目。

[in] bWait

如果此參數為 TRUE，則函式不會在作業完成之前傳回。如果此參數為 FALSE 且作業仍然擱置中，則函式會傳回 FALSE ，而 GetLastError 函式會傳回ERROR_IO_INCOMPLETE。

傳回值

如果函式成功，則傳回值是零以外的任何數位。如果此函式失敗，則傳回值為零。若要取得擴充的錯誤資訊，請呼叫 GetLastError。

備註

此函式就像 Win32 API 例程 GetOverlappedResult 一樣，有一個差異，而不是傳遞從 CreateFile 傳回的檔案句柄，呼叫端會傳遞從 WinUsb_Initialize傳回的介面句柄。如果傳遞適當的句柄，呼叫端可以使用任一 API 例程。 WinUsb_GetOverlappedResult函式會從介面句柄擷取檔句柄，然後呼叫 GetOverlappedResult。

WinUsb_GetOverlappedResult函式所報告的結果，是從指定句柄的最後一個重迭作業中提供的重疊作業，以及作業的結果擱置中。當啟動作業的函式傳回 FALSE，而 GetLastError 例程傳回ERROR_IO_PENDING時，就會指出暫止作業。當 I/O 作業擱置時，啟動作業的函式會將重疊結構的 hEvent 成員重設為非簽署狀態。然後，當擱置作業完成時，系統會將事件物件設定為已發出訊號的狀態。

呼叫端可以指定在 RESETED 結構中手動重設事件物件。如果使用自動重設事件物件，則啟動重疊作業和呼叫 WinUsb_GetOverlappedResult之間的間隔，不得在任何其他等候作業中指定事件句柄。例如，事件物件有時會在其中一個等候例程中指定，以等候作業完成。當等候例程傳回時，系統會將自動重設事件的狀態設定為非ignaled，而將 bWait 參數設定為 TRUE 的連續 WinUsb_GetOverlappedResult呼叫會無限期地封鎖函式。

如果 bWait 參數為 TRUE，WinUsb_GetOverlappedResult會等待事件對象處於訊號狀態，判斷是否已完成擱置的作業。

如果 OVERLAPPED 結構的 hEvent 成員為 NULL，系統會使用檔案句柄的狀態，在作業完成時發出訊號。請勿針對此目的使用檔句柄。最好使用事件對象，因為在同一個檔案上執行多個並行重疊作業時可能發生的混淆。在此情況下，您無法知道哪個作業導致物件的狀態收到訊號。