WinUsb_ReadPipe函式 (winusb.h)

發行項
03/04/2024

WinUsb_ReadPipe函式會從指定的管道讀取數據。

語法

BOOL WinUsb_ReadPipe(
  [in]            WINUSB_INTERFACE_HANDLE InterfaceHandle,
  [in]            UCHAR                   PipeID,
  [out]           PUCHAR                  Buffer,
  [in]            ULONG                   BufferLength,
  [out, optional] PULONG                  LengthTransferred,
  [in, optional]  LPOVERLAPPED            Overlapped
);

參數

[in] InterfaceHandle

介面的不透明句柄，其中包含與管道相關聯的端點。

若要從第一個介面中與端點相關聯的管道讀取數據，請使用 WinUsb_Initialize傳回的句柄。對於所有其他介面，請使用目標介面的句柄，WinUsb_GetAssociatedInterface擷取。

[in] PipeID

PipeID 會對應至端點描述元中的 bEndpointAddress 字段。 For information about the layout of this field, see Table 9-13 in "Universal Serial Bus Specification Revision 2.0" at USB Technology. 在 [bEndpointAddress ] 欄位中，Bit 7 表示端點的方向：0 代表 OUT;1 用於 IN。

[out] Buffer

呼叫端配置的緩衝區，接收讀取的數據。

[in] BufferLength

要讀取的最大位元組數。這個數字必須小於或等於 Buffer 的大小，以位元組為單位。

[out, optional] LengthTransferred

ULONG 變數的指標，接收已複製到 Buffer 的實際位元元組數目。如需詳細資訊，請參閱＜備註＞。

[in, optional] Overlapped

用於異步操作之重疊結構的選擇性指標。如果指定此參數， WinUsb_ReadPipe 會立即傳回，而不是在傳回之前同步等候作業完成。作業完成時會發出事件訊號。

傳回值

如果作業成功，WinUsb_ReadPipe傳回 TRUE。否則，此函式會傳回 FALSE，而且呼叫端可以呼叫 GetLastError 來擷取記錄的錯誤。

GetLastError 可以傳回下列錯誤碼。

傳回碼	Description
ERROR_INVALID_HANDLE	呼叫端在 InterfaceHandle 參數中傳遞 NULL。
ERROR_IO_PENDING	重疊的 I/O 作業正在進行中，但尚未完成。如果無法立即完成重疊的作業，則函式會傳回 FALSE ，而 GetLastError 函式會傳回ERROR_IO_PENDING，表示作業是在背景中執行。呼叫 WinUsb_GetOverlappedResult 來檢查作業的成功或失敗。
ERROR_NOT_ENOUGH_MEMORY	記憶體不足，無法執行作業。
ERROR_SEM_TIMEOUT	在作業完成之前，由USB堆疊中 WinUsb_ReadPipe 起始的讀取作業逾時。

備註

如果裝置傳回的數據大於傳輸長度上限，WinUSB 會將要求分割成最大傳輸長度的較小要求，並依序提交。如果傳輸長度不是端點封包大小上限的倍數， (可透過 WINUSB_PIPE_INFORMATION 結構的 MaximumPacketSize 成員) 擷取，WinUSB 會將傳輸的大小增加到下一個 MaximumPacketSize 的倍數。

USB 封包大小不會納入讀取要求的傳輸。如果裝置以對客戶端緩衝區太大的封包回應，讀取要求的行為會對應至管道上設定的原則類型。如果管道的原則類型ALLOW_PARTIAL_READS，WinUSB 會將其餘數據新增至下一次傳輸的開頭。如果未設定ALLOW_PARTIAL_READS，讀取要求就會失敗。如需原則類型的詳細資訊，請參閱適用於管道原則修改的 WinUSB 函式。

如果應用程式在重迭參數中傳遞 NULL (同步作業) ，則應用程式必須確定 LengthTransferred 不是 NULL，即使讀取作業不會產生輸出數據也一樣。

如果重疊不是 NULL (異步操作) ， 則 LengthTransferred 可以設定為 NULL。對於重疊的作業 (，而且如果 LengthTransferred 是非 NULL 值) ，則在WinUsb_ReadPipe傳回之後的 LengthTransferred 中收到的值是無意義的，直到重疊的作業完成為止。若要擷取從管道讀取的實際位元元組數目，請呼叫 WinUsb_GetOverlappedResult。

當端點 (管道中沒有可用的數據) 時， WinUsb_ReadPipe 不會傳回，直到管道中有數據為止。如果發生錯誤狀況或應用程式指定的逾時過期， WinUsb_ReadPipe 一律會傳回 FALSE。若要判斷該傳回值的實際原因，請一律呼叫 GetLastError。例如，在這些情況下， GetLastError 錯誤值會指出實際的原因：

如果應用程式在管道原則中指定逾時值且逾時到期， WinUsb_ReadPipe 傳回 FALSE，而 GetLastError 會傳回ERROR_SEM_TIMEOUT。
如果從管道讀取數據時發生錯誤狀況， WinUsb_ReadPipe 會傳回 FALSE，而 GetLastError 會傳回ERROR_GEN_FAILURE。