共用方式為

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。 否則，此方法可以傳回下列其中一個值：

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

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

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

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

備註

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

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

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

驅動程式通常會從 EvtDevicePrepareHardware 回呼函式內呼叫 WdfUsbTargetDeviceCreateWithParameters。 驅動程式也可以從 EvtDriverDeviceAdd 回呼函式內呼叫 WdfUsbTargetDeviceCreateWithParameters。

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

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

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

範例

下列程式代碼範例是 EvtDevicePrepareHardware 回呼函式的一部分，可呼叫 WdfUsbTargetDeviceCreateWithParameters。 此範例會將架構 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;
    }
...
}

規格需求

需求 值
目標平台 Universal
最小 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