共用方式為

WdfUsbTargetDeviceCreate 函式 (wdfusb.h)

  • 發行項

[適用於 KMDF 和 UMDF]

WdfUsbTargetDeviceCreate 方法會為指定的架構裝置物件建立架構 USB 裝置物件，並開啟用於 I/O 作業的 USB 裝置。

注意 如果您要使用 KMDF 1.11 或 UMDF 2.0 或更新版本來建置驅動程式，建議您呼叫 WdfUsbTargetDeviceCreateWithParameters ，而不是 WdfUsbTargetDeviceCreate。
 

語法

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

參數

[in] Device

架構裝置物件的句柄。

[in, optional] Attributes

呼叫端提供的 WDF_OBJECT_ATTRIBUTES 結構的指標，其中包含新USB裝置對象的屬性。 (結構的 ParentObject 成員必須是 NULL。) 此參數是選擇性的，而且可以WDF_NO_OBJECT_ATTRIBUTES。

[out] UsbDevice

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

傳回值

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

傳回碼 Description
STATUS_INVALID_PARAMETER
 偵測到無效的參數。
STATUS_INSUFFICIENT_RESOURCES
 記憶體不足，無法建立新的 USB 裝置物件。
STATUS_UNSUCCESSFUL
 嘗試取得 USB 設定信息失敗。
 

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

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

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

備註

使用 USB I/O 目標的驅動程式必須在裝置進入運作 (D0) 狀態之後呼叫 WdfUsbTargetDeviceCreate 。 一般而言，驅動程式會從其 EvtDevicePrepareHardware 回呼函式內呼叫 WdfUsbTargetDeviceCreate。 (驅動程式無法從其 EvtDriverDeviceAdd 回調函式內呼叫 WdfUsbTargetDeviceCreate。)

WdfUsbTargetDeviceCreate 會從裝置取得 USB 裝置描述元和第一個 USB 設定描述元，並加以儲存。 它也會為裝置第一個設定中的每個介面建立架構 USB 介面物件。 若要判斷組態支援的介面數目，驅動程式可以呼叫 WdfUsbTargetDeviceGetNumInterfaces。

呼叫 WdfUsbTargetDeviceCreate 之後，您的驅動程式可以呼叫其他 架構 USB 裝置物件方法。

每個 USB 裝置物件的父系是驅動程式的架構驅動程序物件。 驅動程式無法變更此父代， 而且 ParentObject 成員或 WDF_OBJECT_ATTRIBUTES 結構必須是 NULL。

如需 WdfUsbTargetDeviceCreate 方法和 USB I/O 目標的詳細資訊，請參閱 USB I/O 目標。

範例

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

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

    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;
    }
 status = WdfUsbTargetDeviceCreate(
                                      Device,
                                      WDF_NO_OBJECT_ATTRIBUTES,
                                      &pMyDeviceContext->UsbDevice
                                      );
    if (!NT_SUCCESS(status)) {
        return status;
    }
...
}

規格需求

需求 值
目標平台 Universal
最低 KMDF 版本 1.0
最低UMDF版本 2.0
標頭 wdfusb.h (包含 Wdfusb.h)
程式庫 Wdf01000.sys (KMDF) ;WUDFx02000.dll (UMDF)
IRQL PASSIVE_LEVEL
DDI 合規性規則 DriverCreate (kmdf) ， KmdfIrql (kmdf) ， KmdfIrql2 (kmdf) ， KmdfIrqlExplicit (kmdf ) ， UsbDeviceCreate (kmdf) 、 UsbDeviceCreateFail (kmdf) 、 UsbDeviceCreateTarget (kmdf) 、 UsbKmdfIrql (kmdf ) 、 UsbKmdfIrql2 (kmdf) 、UsbKmdfIrqlExplicit (kmdf)

另請參閱

EvtDevicePrepareHardware

WDF_OBJECT_ATTRIBUTES

WdfUsbTargetDeviceGetNumInterfaces