WdfUsbTargetDeviceFormatRequestForUrb 関数 (wdfusb.h)

  • [アーティクル]

[KMDF にのみ適用]

WdfUsbTargetDeviceFormatRequestForUrb メソッドは、URB で記述されている要求パラメーターを使用して、指定された USB デバイスの USB 要求をビルドしますが、要求は送信しません。

構文

NTSTATUS WdfUsbTargetDeviceFormatRequestForUrb(
  [in]           WDFUSBDEVICE      UsbDevice,
  [in]           WDFREQUEST        Request,
  [in]           WDFMEMORY         UrbMemory,
  [in, optional] PWDFMEMORY_OFFSET UrbMemoryOffset
);

パラメーター

[in] UsbDevice

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

[in] Request

フレームワーク要求オブジェクトへのハンドル。 詳細については、「解説」を参照してください。

[in] UrbMemory

URB 構造体または構造体の共用体メンバーの 1 つを含むフレームワーク メモリ オブジェクトへのハンドル。 (URB 構造体のすべての共用体メンバーには 、_URB_HEADER 構造体が含まれています)。

ドライバーが以前 に WdfUsbTargetDeviceCreateWithParameters を呼び出して UsbDevice を作成する場合、ドライバーは WdfUsbTargetDeviceCreateUrb または WdfUsbTargetDeviceCreateIsochUrb を使用して、このメモリ オブジェクトに含まれる URB を作成する必要があります。 それ以外の場合は、バグ チェックが発生します。

[in, optional] UrbMemoryOffset

省略可能なバイト オフセットと長さの値を提供する呼び出し元によって割り当てられた WDFMEMORY_OFFSET 構造体へのポインター。 フレームワークでは、これらの値を使用して、 UrbMemory が指定するメモリ内の URB の開始アドレスを決定します。 このポインターが NULL の場合、URB は UrbMemory メモリの先頭にあります。

戻り値

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

リターン コード 説明
STATUS_INVALID_PARAMETER
 無効なパラメーターが検出されました。
STATUS_INSUFFICIENT_RESOURCES
 メモリが不足していました。
STATUS_INTEGER_OVERFLOW
 UsbMemoryOffset パラメーターが指定したオフセットが無効です。
 

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

ドライバーが無効なオブジェクト ハンドルを提供すると、バグ チェックが発生します。

注釈

USB コントロール転送要求を同期的または非同期的に送信するには、 WdfUsbTargetDeviceFormatRequestForUrb と WdfRequestSend を使用します。 または、 WdfUsbTargetDeviceSendUrbSynchronously メソッドを使用して、要求を同期的に送信します。

ドライバーが I/O キューで受信した I/O 要求を転送することも、新しい要求を作成して送信することもできます。

ドライバーが I/O キューで受信した I/O 要求を転送するには、 WdfUsbTargetDeviceFormatRequestForUrb メソッドの Request パラメーターに対して、受信した 要求 のハンドルを指定します。

新しい I/O 要求を作成するには、 WdfRequestCreate を呼び出して要求オブジェクトを事前割り当てします。 WdfUsbTargetDeviceFormatRequestForUrb メソッドの Request パラメーターの要求ハンドルを指定します。 要求オブジェクトは 、WdfRequestReuse を呼び出すことで再利用できます。 ドライバーの EvtDriverDeviceAdd コールバック関数は、デバイスの要求オブジェクトを事前割り当てできます。

WdfUsbTargetDeviceFormatRequestForUrb を呼び出して I/O 要求を書式設定した後、ドライバーは WdfRequestSend を呼び出して要求を (同期的または非同期的に) I/O ターゲットに送信する必要があります。 send and forget オプション を使用して要求を送信しないでください。

同じ要求を使用する WdfUsbTargetDeviceFormatRequestForUrb を複数回呼び出しても、追加のリソース割り当ては発生しません。 そのため、 WdfRequestCreate がSTATUS_INSUFFICIENT_RESOURCESを返す可能性を減らすために、ドライバーの EvtDriverDeviceAdd コールバック関数は WdfRequestCreate を呼び出して、デバイスの 1 つ以上の要求オブジェクトを事前割り当てできます。 ドライバーは、その後、 WdfRequestReuse の呼び出し、再フォーマット (呼び出し WdfUsbTargetDeviceFormatRequestForUrb)、および WdfRequestCreate への後の呼び出しからSTATUS_INSUFFICIENT_RESOURCES戻り値を危険にさらすことなく、各要求オブジェクトを再送信 (呼び出し WdfRequestSend) できます。 再利用された要求オブジェクトに対する WdfUsbTargetDeviceFormatRequestForUrb に対する後続のすべての呼び出しは、パラメーター値が変更されない場合、STATUS_SUCCESSを返します。 (ドライバーが毎回同じ要求形式メソッドを呼び出さない場合は、追加のリソースが割り当てられる可能性があります)。

I/O 要求の完了後に状態情報を取得する方法については、「 完了情報の取得」を参照してください。

WdfUsbTargetDeviceFormatRequestForUrb メソッドと USB I/O ターゲットの詳細については、「USB I/O ターゲット」を参照してください。

例

次のコード例では、URB 構造体を保持するメモリ オブジェクトを作成し、URB 構造体を初期化し、 WdfUsbTargetDeviceFormatRequestForUrb を呼び出して、URB 構造体の内容を使用する要求を書式設定します。 次に、 CompletionRoutine コールバック関数を登録し、I/O ターゲットに要求を送信します。

WDFMEMORY urbMemory;
URB *urbBuffer;

status = WdfMemoryCreate(
                         WDF_NO_OBJECT_ATTRIBUTES,
                         NonPagedPool,
                         0,
                         sizeof(struct _URB_CONTROL_GET_CONFIGURATION_REQUEST),
                         &urbMemory,
                         NULL
                         );

if (!NT_SUCCESS(status)){
    return status;
}
urbBuffer = (PURB) WdfMemoryGetBuffer(
                                      urbMemory,
                                      NULL
                                      );
urbBuffer->UrbHeader.Function =  URB_FUNCTION_GET_CONFIGURATION;
urbBuffer->UrbHeader.Length = sizeof(struct _URB_CONTROL_GET_CONFIGURATION_REQUEST);
urbBuffer->UrbControlGetConfigurationRequest.TransferBufferLength = 1 ;
urbBuffer->UrbControlGetConfigurationRequest.TransferBufferMDL = NULL;
urbBuffer->UrbControlGetConfigurationRequest.TransferBuffer = outBuffer;
urbBuffer->UrbControlGetConfigurationRequest.UrbLink = NULL;

status = WdfUsbTargetDeviceFormatRequestForUrb(
                                               deviceContext->WdfUsbTargetDevice,
                                               request,
                                               urbMemory,
                                               NULL
                                               );
WdfRequestSetCompletionRoutine(
                              request,
                              MyCompletionRoutine,
                              NULL);

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

要件

要件 値
対象プラットフォーム ユニバーサル
最小 KMDF バージョン 1.0
Header wdfusb.h (Wdfusb.h を含む)
Library Wdf01000.sys (「Framework ライブラリのバージョン管理」を参照)。
IRQL <=DISPATCH_LEVEL
DDI コンプライアンス規則 DriverCreate(kmdf), KmdfIrql(kmdf)、 KmdfIrql2(kmdf)、KmdfIrqlExplicit(kmdf)、 RequestFormattedValid(kmdf)、 RequestSendAndForgetNoFormatting(kmdf)、 RequestSendAndForgetNoFormatting2(kmdf)、 UsbKmdfIrql(kmdf)、 UsbKmdfIrql2(kmdf)、UsbKmdfIrqlExplicit(kmdf)

こちらもご覧ください

EvtDriverDeviceAdd

WDFMEMORY_OFFSET

WdfRequestReuse

WdfRequestSend

WdfUsbTargetDeviceCreateWithParameters

WdfUsbTargetDeviceSendUrbSynchronously