WdfUsbTargetDeviceCreate 関数 (wdfusb.h)

  • [アーティクル]

[KMDF と UMDF に適用]

WdfUsbTargetDeviceCreate メソッドは、指定されたフレームワーク デバイス オブジェクトのフレームワーク USB デバイス オブジェクトを作成し、I/O 操作用に USB デバイスを開きます。

メモKMDF 1.11 または UMDF 2.0 以降を使用してドライバーをビルドする場合は、WdfUsbTargetDeviceCreate の代わりに WdfUsbTargetDeviceCreateWithParameters を呼び出することをお勧めします。
 

構文

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

パラメーター

[in] Device

フレームワーク デバイス オブジェクトへのハンドル。

[in, optional] Attributes

新しい USB デバイス オブジェクトの属性を含む、呼び出し元から提供された WDF_OBJECT_ATTRIBUTES 構造体へのポインター。 (構造体の ParentObject メンバーは NULL である必要があります)。このパラメーターは省略可能であり、WDF_NO_OBJECT_ATTRIBUTESできます。

[out] UsbDevice

新しいフレームワーク USB デバイス オブジェクトへのハンドルを受け取る場所へのポインター。

戻り値

操作が成功した場合、WdfUsbTargetDeviceCreate はSTATUS_SUCCESSを返します。 それ以外の場合、このメソッドは次のいずれかの値を返すことができます。

リターン コード 説明
STATUS_INVALID_PARAMETER
 無効なパラメーターが検出されました。
STATUS_INSUFFICIENT_RESOURCES
 新しい USB デバイス オブジェクトを作成するためのメモリが不足していました。
STATUS_UNSUCCESSFUL
 USB 構成情報を取得できませんでした。
 

WdfUsbTargetDeviceCreate メソッドが返す可能性があるその他の戻り値の一覧については、「フレームワーク オブジェクト作成エラー」を参照してください。

このメソッドは、他の 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 ターゲット」を参照してください。

例

次のコード例は、WdfUsbTargetDeviceCreate を呼び出す EvtDevicePrepareHardware コールバック関数の一部です。 この例では、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
Header wdfusb.h (Wdfusb.h を含む)
Library 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