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を返します。 それ以外の場合、このメソッドは次のいずれかの値を返すことができます。

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

このメソッドは、他の 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;
    }
...
}

要件

こちらもご覧ください

USBD_CreateHandle

WDF_USB_DEVICE_CREATE_CONFIG

WDF_USB_DEVICE_CREATE_CONFIG_INIT

WdfUsbTargetDeviceCreate