共用方式為

WdfUsbTargetDeviceCreateWithParameters 函式 （wdfusb.h）

  • 發行項

[適用於 KMDF 和 UMDF]

WdfUsbTargetDeviceCreateWithParameters 方法會為指定的架構裝置物件建立架構 USB 裝置物件，並開啟 I/O 作業的 USB 裝置。 方法也會指定架構 USB 裝置物件的組態資訊。

語法

NTSTATUS WdfUsbTargetDeviceCreateWithParameters(
  [in]           WDFDEVICE                     Device,
  [in]           PWDF_USB_DEVICE_CREATE_CONFIG Config,
  [in, optional] PWDF_OBJECT_ATTRIBUTES        Attributes,
  [out]          WDFUSBDEVICE                  *UsbDevice
);

參數

[in] Device

架構裝置物件的句柄。

[in] Config

WDF_USB_DEVICE_CREATE_CONFIG 結構的指標，其中包含架構 USB 裝置物件的組態資訊。

[in, optional] Attributes

呼叫端提供的 WDF_OBJECT_ATTRIBUTES 結構的指標，其中包含新架構 USB 裝置物件的屬性。 （結構的 ParentObject 成員必須是 NULL。這個參數是選擇性的，而且可以WDF_NO_OBJECT_ATTRIBUTES。

[out] UsbDevice

接收新架構 USB 裝置物件句柄之位置的指標。

傳回值

WdfUsbTargetDeviceCreateWithParameters 如果作業成功，就會傳回STATUS_SUCCESS。 否則，這個方法可以傳回下列其中一個值：

傳回碼 描述
STATUS_INFO_LENGTH_MISMATCH
 Config 參數不是正確的大小。
STATUS_INSUFFICIENT_RESOURCES
 記憶體不足，無法建立新的架構 USB 裝置物件。
STATUS_INVALID_PARAMETER
 偵測到無效的參數。 如需詳細資訊，請參閱一節。
STATUS_UNSUCCESSFUL
 嘗試取得 USB 設定信息失敗。
 

如需 WdfUsbTargetDeviceCreateWithParameters 方法可能會傳回的其他傳回值清單，請參閱 Framework 物件建立錯誤。

此方法也可能 傳回其他NTSTATUS 值。

如果驅動程式提供無效的物件句柄，就會發生錯誤檢查。

言論

Windows 8 包含新的 USB 驅動程式堆疊，可支援 USB 3.0 裝置。

在架構型用戶端驅動程式可以使用適用於 Windows 8 的 USB 驅動程式堆疊新功能之前，驅動程式必須先向 Windows 針對裝置載入的基礎 USB 驅動程式堆疊註冊自己。 若要註冊客戶端驅動程式，請在 WDF_USB_DEVICE_CREATE_CONFIG 結構中呼叫 WdfUsbTargetDeviceCreateWithParameters 並指定合約版本。

如果客戶端驅動程式的目的是要建置、執行及使用 Windows 8 上的改進功能和新功能，則用戶端合約版本會USBD_CLIENT_CONTRACT_VERSION_602。

一般而言，驅動程式會從 EvtDevicePrepareHardware 回呼函式內呼叫 WdfUsbTargetDeviceCreateWithParameters。 驅動程式也可以從 EvtDriverDeviceAdd 回呼函式內呼叫 WdfUsbTargetDeviceCreateWithParameters。

如需 WDM USB 用戶端驅動程式如何與 USB 3.0 驅動程式堆疊互動的資訊，請參閱 最佳做法：使用 URL。

如果驅動程式呼叫 WdfUsbTargetDeviceCreateWithParameters 來建立架構 USB 裝置對象，驅動程式必須呼叫 WdfUsbTargetDeviceCreateUrb 或 WdfUsbTargetDeviceCreateIsochUrb來建立 URB。

如果您從 UMDF 驅動程式呼叫此方法，則必須在驅動程式的 INF 檔案中指定 UmdfDispatcher 指示詞。 否則，此方法可能會傳回 STATUS_INVALID_PARAMETER。 如需此指示詞的詳細資訊，請參閱 在 INF 檔案中指定 WDF 指示詞。

例子

下列程式代碼範例是呼叫 WdfUsbTargetDeviceDeviceCreateWithParameters回呼函式 EvtDevicePrepareHardware 的一部分。 此範例會將句柄儲存在驅動程式定義的內容空間中架構 USB 裝置物件。

NTSTATUS
MyEvtDevicePrepareHardware(
    IN WDFDEVICE  Device,
    IN WDFCMRESLIST  ResourceList,
    IN WDFCMRESLIST  ResourceListTranslated
    )
{
    NTSTATUS  status;
    PMY_DEVICE_CONTEXT  pMyDeviceContext;
    WDF_USB_DEVICE_CREATE_CONFIG  Config;

    pMyDeviceContext = GetDeviceContext(Device);

    // If object handle is not NULL, MyEvtDevicePrepareHardware
    // was called previously and the handle is still valid.
    if (pMyDeviceContext->UsbDevice != NULL) {
        return STATUS_SUCCESS;
    }

    WDF_USB_DEVICE_CREATE_CONFIG_INIT(
                                      &Config,
                                      USBD_CLIENT_CONTRACT_VERSION_602
                                      );

    status = WdfUsbTargetDeviceCreateWithParameters(
                                      Device,
                                      &Config,
                                      WDF_NO_OBJECT_ATTRIBUTES,
                                      &pMyDeviceContext->UsbDevice
                                      );
    if (!NT_SUCCESS(status)) {
        return status;
    }
...
}

要求

要求 價值
目標平臺 普遍
最低 KMDF 版本 1.11
最低 UMDF 版本 2.0
標頭 wdfusb.h （包括 Wdfusb.h）
連結庫 Wdf01000.sys （KMDF）：WUDFx02000.dll （UMDF）
IRQL PASSIVE_LEVEL
DDI 合規性規則 DriverCreate（kmdf），RequestForUrbXrb（kmdf），UsbDeviceCreate（kmdf），UsbDeviceCreateFail（kmdf），UsbDeviceCreateTarget（kmdf）

另請參閱

USBD_CreateHandle

WDF_USB_DEVICE_CREATE_CONFIG

WDF_USB_DEVICE_CREATE_CONFIG_INIT

WdfUsbTargetDeviceCreate