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 メソッドが返す可能性があるその他の戻り値の一覧については、「フレームワーク オブジェクト作成エラー」を参照してください。
このメソッドは、他の 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 |
| Header | wdfusb.h (Wdfusb.h を含む) |
| Library | Wdf01000.sys (KMDF);WUDFx02000.dll (UMDF) |
| IRQL | PASSIVE_LEVEL |
| DDI コンプライアンス規則 | DriverCreate(kmdf)、 RequestForUrbXrb(kmdf)、 UsbDeviceCreate(kmdf)、 UsbDeviceCreateFail(kmdf)、 UsbDeviceCreateTarget(kmdf) |