次の方法で共有


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

フレームワーク USB デバイス オブジェクトの構成情報を含む WDF_USB_DEVICE_CREATE_CONFIG 構造体へのポインター。

[in, optional] Attributes

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

[out] UsbDevice

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

戻り値

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

リターン コード 形容
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 ドライバー スタックとやり取りする方法については、「ベスト プラクティス: URBの使用」を参照してください。

ドライバー WdfUsbTargetDeviceCreateWithParameters を呼び出してフレームワーク USB デバイス オブジェクトを作成する場合、ドライバーは WdfUsbTargetDeviceCreateUrb 呼び出すか、WdfUsbTargetDeviceCreateIsochUrb することによってのみ URB を作成する必要があります。

UMDF ドライバーからこのメソッドを呼び出す場合は、ドライバーの INF ファイルで UmdfDispatcher ディレクティブを指定する必要があります。 それ以外の場合、このメソッドは STATUS_INVALID_PARAMETERを返す可能性があります。 このディレクティブの詳細については、INF ファイル で WDF ディレクティブを指定するを参照してください。

次のコード例は、WdfUsbTargetDeviceCreateWithParameters を呼び出す EvtDevicePrepareHardware コールバック関数の一部です。 この例では、ドライバー定義のコンテキスト空間にフレームワーク 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