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を返します。 それ以外の場合、このメソッドは次のいずれかの値を返すことができます。
| リターン コード | 形容 |
|---|---|
|
Config パラメーターが正しいサイズではありません。 |
|
新しいフレームワーク USB デバイス オブジェクトを作成するためのメモリが不足していました。 |
|
無効なパラメーターが検出されました。 詳細については、「解説」セクションを参照してください。 |
|
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) |