WinUsb_Initialize函式 (winusb.h)

發行項
03/04/2024

WinUsb_Initialize函式會為檔案句柄所指定的裝置建立 WinUSB 句柄。

語法

BOOL WinUsb_Initialize(
  [in]  HANDLE                   DeviceHandle,
  [out] PWINUSB_INTERFACE_HANDLE InterfaceHandle
);

參數

[in] DeviceHandle

CreateFile 傳回之裝置的句柄。 WinUSB 使用重疊的 I/O，因此FILE_FLAG_OVERLAPPED必須在 DeviceHandle 呼叫 CreateFile 的 dwFlagsAndAttributes 參數中指定，才能讓WinUsb_Initialize正常運作所需的特性。

[out] InterfaceHandle

接收裝置上第一個 (預設) 介面的不透明句柄。其他在預設介面上執行作業的 WinUSB 例程需要此句柄。若要釋放句柄，請呼叫 WinUSB_Free 函式。

傳回值

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

GetLastError 可以傳回下列錯誤碼。

傳回碼	Description
ERROR_INVALID_HANDLE	呼叫端在 DeviceHandle 參數中傳遞 NULL 或無效句柄;檔案句柄中未設定FILE_FLAG_OVERLAPPED。
ERROR_NOT_ENOUGH_MEMORY	表示記憶體不足，無法執行作業。
ERROR_BAD_DEVICE	表示找不到裝置的預設介面描述元。

備註

呼叫 WinUsb_Initialize 時，介面的原則設定會重設為預設值。

WinUsb_Initialize呼叫會查詢各種描述元的基礎 USB 堆棧，並配置足夠的記憶體來儲存擷取的描述元數據。

WinUsb_Initialize 會先擷取裝置描述項，然後取得相關聯的組態描述元。從組態描述元，呼叫會衍生相關聯的介面描述元，並將其儲存在陣列中。陣列中的介面是由以零起始的索引來識別。索引值為 0 表示第一個介面 (預設介面) 、1 值表示第二個相關聯的介面等等。 WinUsb_Initialize 剖析端點描述元的預設介面描述元，並快取相關管道或狀態特定數據等資訊。 InterfaceHandle 參數中收到的句柄是配置給陣列中第一個介面的記憶體區塊指標。

如果應用程式想要在裝置上使用另一個介面，它必須呼叫 WinUsb_GetAssociatedInterface、指定介面的索引，以及擷取配置給指定介面的記憶體區塊句柄。