WdfUsbTargetDeviceCreateUrb 関数 (wdfusb.h)

  • [アーティクル]

[KMDF にのみ適用]

WdfUsbTargetDeviceCreateUrb メソッドは、USB 要求ブロック (URB) を割り当てます。

構文

NTSTATUS WdfUsbTargetDeviceCreateUrb(
  [in]            WDFUSBDEVICE           UsbDevice,
  [in, optional]  PWDF_OBJECT_ATTRIBUTES Attributes,
  [out]           WDFMEMORY              *UrbMemory,
  [out, optional] PURB                   *Urb
);

パラメーター

[in] UsbDevice

WdfUsbTargetDeviceCreateWithParameters の以前の呼び出しから取得された USB デバイス オブジェクトへのハンドル。

[in, optional] Attributes

新しいメモリ オブジェクトの属性を含む呼び出し元が指定した WDF_OBJECT_ATTRIBUTES 構造体へのポインター。 ドライバーがこのパラメーターを提供する場合、構造体の ParentObject メンバーは、USB デバイス オブジェクト (WDFUSBDEVICE) またはフレームワークによって作成された要求オブジェクト (WDFREQUEST) または親のチェーンがこれらの型のいずれかに至る任意のオブジェクトである必要があります。 このパラメーターは省略可能であり、WDF_NO_OBJECT_ATTRIBUTESできます。

[out] UrbMemory

フレームワーク メモリ オブジェクトへのハンドルを受け取る WDFMEMORY 型の場所へのポインター。

[out, optional] Urb

新しく割り当てられた URB のアドレスを受け取る URB 構造体へのポインター。 このパラメーターは省略可能であり、NULL にすることができます。

戻り値

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

リターン コード 説明
STATUS_INVALID_PARAMETER
 無効なパラメーターが検出されました。
STATUS_INVALID_DEVICE_STATE
 ドライバーは、 WDF_USB_DEVICE_CREATE_CONFIG_INITを呼び出したときにクライアント コントラクトのバージョンを指定しませんでした。
STATUS_INSUFFICIENT_RESOURCES
 新しい URB を作成するためのメモリが不足していました。
 

このメソッドは、他の NTSTATUS 値を返す場合もあります。

注釈

WdfUsbTargetDeviceCreateUrb を呼び出す前に、ドライバーは WdfUsbTargetDeviceCreateWithParameters を呼び出す必要があります。 成功した場合、 WdfUsbTargetDeviceCreateUrb は、新しく割り当てられた URB を記述するフレームワーク メモリ オブジェクトにハンドルを返します。 通常、ドライバーは要求ハンドラー内から WdfUsbTargetDeviceCreateUrb を呼び出します。

ドライバーは WdfUsbTargetDeviceCreateUrb を呼び出して、 WdfUsbTargetDeviceFormatRequestForUrb を呼び出す前に URB 構造体を割り当てることができます。

WdfUsbTargetDeviceCreateUrb は、操作中の WdfMemoryCreate と似ています。 どちらのメソッドもフレームワーク メモリ オブジェクトを割り当てます。また、両方のメソッドは、メモリ オブジェクトに関連付けられているバッファー (この場合は URB) を受け取るオプションも提供します。 どちらの場合も、呼び出し元は WdfMemoryGetBuffer を呼び出すことによって、後でバッファーを取得することもできます。

ドライバーが WdfUsbTargetDeviceCreateUrb を呼び出すときに Urb パラメーターを提供する場合は、手動で、または UsbBuildXxx ルーチンを呼び出すことによって、URB の書式を設定できます。

親オブジェクトが削除されると、メモリ オブジェクトとそのバッファーが削除されます。 ドライバーは、 WdfObjectDelete を呼び出すことによって、メモリ オブジェクトとそのバッファーを削除することもできます。

例

次のコード例では、フレームワーク メモリ オブジェクトを宣言します。 この例では 、WdfUsbTargetDeviceCreateUrb を呼び出して USB 要求ブロックを割り当て、 次に WdfUsbTargetDeviceFormatRequestForUrb を呼び出して、URB 構造体の内容を使用する要求を書式設定します。 最後に、 CompletionRoutine コールバック関数を登録し、要求を I/O ターゲットに送信します。

WDFMEMORY memory;
PURB urb = NULL;

WDF_OBJECT_ATTRIBUTES_INIT(&objectAttribs);
objectAttribs.ParentObject = UsbDevice;

status = WdfUsbTargetDeviceCreateUrb(
    pDevContext->WdfUsbTargetDevice,
    &objectAttribs,
    &memory,
    &urb);

status = WdfUsbTargetDeviceFormatRequestForUrb(
    deviceContext->WdfUsbTargetDevice,
    request,
    memory,
    NULL);

WdfRequestSetCompletionRoutine(
    request,
    MyCompletionRoutine,
    NULL);

if (!WdfRequestSend(
        request,
        WdfUsbTargetDeviceGetIoTarget(UsbDevice),
        NULL)) {
    status = WdfRequestGetStatus(request);
}

要件

要件 値
サポートされている最小のクライアント Windows Vista
対象プラットフォーム ユニバーサル
最小 KMDF バージョン 1.11
Header wdfusb.h (Wdfusb.h を含む)
Library Wdf01000.sys (「Framework ライブラリのバージョン管理」を参照)。
IRQL <=DISPATCH_LEVEL
DDI コンプライアンス規則 DriverCreate(kmdf)

こちらもご覧ください

WDF_USB_DEVICE_CREATE_CONFIG_INIT

WdfUsbTargetDeviceCreateIsochUrb

WdfUsbTargetDeviceCreateWithParameters

WdfUsbTargetDeviceFormatRequestForUrb