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 驅動程式堆疊。

在架構型用戶端驅動程式可以使用 USB 驅動程式堆疊的新功能進行Windows 8之前,驅動程式必須先向 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;
    }
...
}

規格需求

   
目標平臺 環球
最小 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