共用方式為

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

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

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

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

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

言論

使用 USB I/O 目標的驅動程式必須在裝置進入工作狀態之後呼叫 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 目標。

例子

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

要求

要求 價值
目標平臺 普遍
最低 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