WinUsb_ControlTransfer函式 (winusb.h)

發行項
03/04/2024

WinUsb_ControlTransfer函式會透過預設控制端點傳輸控制數據。

語法

BOOL WinUsb_ControlTransfer(
  [in]            WINUSB_INTERFACE_HANDLE InterfaceHandle,
  [in]            WINUSB_SETUP_PACKET     SetupPacket,
  [out]           PUCHAR                  Buffer,
  [in]            ULONG                   BufferLength,
  [out, optional] PULONG                  LengthTransferred,
  [in, optional]  LPOVERLAPPED            Overlapped
);

參數

[in] InterfaceHandle

所選組態中介面的不透明句柄。

若要將控制要求的收件者指定為整個裝置或第一個介面，請使用 WinUsb_Initialize傳回的句柄。針對所有其他介面，呼叫 WinUsb_GetAssociatedInterface來取得目標介面的句柄，然後藉由指定取得的介面句柄來呼叫 WinUsb_ControlTransfer 。

[in] SetupPacket

類型為 WINUSB_SETUP_PACKET的8位元組設定封包。

[out] Buffer

呼叫端配置的緩衝區，其中包含要傳輸的數據。此緩衝區的長度不得超過 4 KB。

[in] BufferLength

要傳輸的位元組數目，不包括安裝封包。這個數字必須小於或等於 Buffer 的大小，以位元組為單位。

[out, optional] LengthTransferred

ULONG 變數的指標，可接收已傳送之位元組的實際數目。如果應用程式未預期在數據階段傳輸任何數據， (BufferLength 為零 ) ，LengthTransferred 可以是 NULL。

[in, optional] Overlapped

重疊結構的選擇性指標，用於異步操作。如果指定此參數， WinUsb_ControlTransfer 會立即傳回，並在作業完成時發出事件訊號。如果未提供重疊， WinUsb_ControlTransfer 函式會同步傳輸數據。

傳回值

如果作業成功，WinUsb_ControlTransfer傳回 TRUE。否則，這個例程會傳回 FALSE，而呼叫端可以呼叫 GetLastError 來擷取記錄的錯誤。

GetLastError 可以傳回下列其中一個錯誤碼。

傳回碼	Description
ERROR_INVALID_HANDLE	呼叫端在 InterfaceHandle 參數中傳遞 NULL。
ERROR_NOT_ENOUGH_MEMORY	表示記憶體不足，無法執行作業。

備註

控件要求一律由主機傳送至 USB 裝置的預設端點，但要求的收件者可以是所選替代設定中的整個裝置、介面或端點。在 WinUsb_ControlTransfer 呼叫中，應用程式必須透過兩個參數來指出收件者： InterfaceHandle 和 SetupPacket。

如果控制要求的收件者是整個裝置、第一個介面或任何該介面中的連接點，應用程式必須使用 WinUsb_Initialize所傳回的句柄。如果收件者是任何其他介面或其端點，則應用程式必須藉由呼叫 WinUsb_GetAssociatedInterface 來取得與目標介面相關聯的 WinUSB 句柄，然後藉由指定取得的介面句柄來呼叫 WinUsb_ControlTransfer 。

根據官方 USB 規格的第 9.3 節，控件傳輸的設定令牌包含要求的相關信息。針對WinUSB 應用程式，會使用 WINUSB_SETUP_PACKET 結構來描述該設定令牌。

在安裝令牌中， bmRequestType 和 wIndex 字段是用來指出要求的收件者。這些字段分別對應至 WINUSB_SETUP_PACKET 的 RequestType 和 Index 成員。

RequestType 的最低兩個位表示要求的收件者。收件者可以是裝置、介面、連接點或其他廠商要求) 的其他 (。根據收件者而定， Index 的下層位元組表示收件者的裝置定義索引。 Index 的值取決於要求的類型。例如，針對標準控制要求，此值為0，或表示介面或端點編號。對於特定類型的標準要求，例如取得字串描述元的GET_DESCRIPTOR要求， Index 值會指出語言標識符。

如果收件者是裝置，應用程式必須設定 RequestType 和 Index 值。 RequestType 值的最低兩個位必須是 0。 Index 值的較低位元組取決於要求的類型。 InterfaceHandle 必須是由 WinUsb_Initialize 傳回的 WinUSB 句柄。

如果要求的收件者是介面，應用程式必須將 RequestType 的最低兩個位設定為0x01。應用程式不需要為任何類型的要求設定 Index 的較低位元組。針對標準、類別和廠商要求，Winusb.sys 將值設定為目標介面的介面編號。 InterfaceHandle 必須與目標介面相關聯。應用程式可以藉由呼叫 WinUsb_GetAssociatedInterface 來取得該句柄。

如果收件者是端點，應用程式必須將 RequestType 的最低兩個位設定為 0x02，並將 Index 的位元組下限設定為端點位址。在此情況下， InterfaceHandle 會與包含端點的介面相關聯。應用程式可以藉由呼叫 WinUsb_GetAssociatedInterface 來取得該句柄。