WdfUsbTargetPipeFormatRequestForUrb 関数 (wdfusb.h)

2025-02-07

[KMDF にのみ適用]

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

構文

NTSTATUS WdfUsbTargetPipeFormatRequestForUrb(
                 WDFUSBPIPE        PIPE,
  [in]           WDFREQUEST        Request,
  [in]           WDFMEMORY         UrbMemory,
  [in, optional] PWDFMEMORY_OFFSET UrbMemoryOffset
);

パラメーター

PIPE

WdfUsbInterfaceGetConfiguredPipe呼び出すことによって取得されたフレームワークパイプオブジェクトへのハンドル。

[in] Request

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

[in] UrbMemory

URB 構造体を含むフレームワークメモリオブジェクトへのハンドル。

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

[in, optional] UrbMemoryOffset

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

戻り値

WdfUsbTargetPipeFormatRequestForUrb 、操作が成功した場合に I/O ターゲットの完了状態値を返します。それ以外の場合、このメソッドは次のいずれかの値を返すことができます。

リターンコード	形容
STATUS_INVALID_PARAMETER	無効なパラメーターが検出されました。
STATUS_INSUFFICIENT_RESOURCES	メモリが不足していました。
STATUS_INTEGER_OVERFLOW	UsbMemoryOffset パラメーターが指定したオフセットが無効でした。
STATUS_REQUEST_NOT_ACCEPTED	要求パラメーターが表す I/O 要求パケット (IRP) は、ドライバーが要求を転送するのに十分な IO_STACK_LOCATION 構造体を提供しません。

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

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

備考

WdfUsbTargetPipeFormatRequestForUrbを使用し、その後に WdfRequestSendを使用して、USB 要求を同期的または非同期的に送信します。または、WdfUsbTargetPipeSendUrbSynchronously メソッドを使用して、要求を同期的に送信します。

フレームワークは USB 要求を調べません。要求によって USB パイプの状態が変更された場合、フレームワークは変更を認識しません。

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

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

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

WdfUsbTargetPipeFormatRequestForUrb を呼び出して I/O 要求を書式設定した後、ドライバーは WdfRequestSend を呼び出して、要求を (同期的または非同期的に) I/O ターゲットに送信する必要があります。

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

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

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

例

次のコード例では、URB を表すメモリオブジェクトを作成します。次に、この例では URB を初期化し、URB を含む USB 要求を書式設定し、CompletionRoutine コールバック関数を登録して、要求を送信します。

URB  urb;
PURB  pUrb = NULL;
WDFMEMORY  urbMemory
NTSTATUS status;

status = WdfMemoryCreate(
                         WDF_NO_OBJECT_ATTRIBUTES,
                         NonPagedPool,
                         0,
                         sizeof(struct _URB_GET_CURRENT_FRAME_NUMBER),
                         &urbMemory,
                         NULL
                         );
if (!NT_SUCCESS(status)){
    return status;
}

pUrb = WdfMemoryGetBuffer(
                          urbMemory,
                          NULL
                          );

pUrb->UrbHeader.Length = (USHORT) sizeof(struct _URB_GET_CURRENT_FRAME_NUMBER);
pUrb->UrbHeader.Function = URB_FUNCTION_GET_CURRENT_FRAME_NUMBER;
pUrb->UrbGetCurrentFrameNumber.FrameNumber = 0; 

status = WdfUsbTargetPipeFormatRequestForUrb(
                                             pipe,
                                             Request,
                                             urbMemory,
                                             NULL
                                             );
if (!NT_SUCCESS(status)) {
    goto Exit;
}
WdfRequestSetCompletionRoutine(
                               Request,
                               UrbCompletionRoutine,
                               pipe
                               );
if (WdfRequestSend(
                   Request,
                   WdfUsbTargetPipeGetIoTarget(pipe),
                   WDF_NO_SEND_OPTIONS
                   ) == FALSE) {
    status = WdfRequestGetStatus(Request);
    goto Exit;
}
Exit:
if (!NT_SUCCESS(status)) {
    WdfRequestCompleteWithInformation(
                                      Request,
                                      status,
                                      0
                                      );
}
return;

必要条件

要件	価値
ターゲットプラットフォームの	万国
最小 KMDF バージョン	1.0
ヘッダー	wdfusb.h (Wdfusb.h を含む)
ライブラリ	Wdf01000.sys (フレームワークライブラリのバージョン管理を参照)。
IRQL	<=DISPATCH_LEVEL
DDI コンプライアンス規則をする	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestFormattedValid(kmdf), RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)

次の方法で共有

WdfUsbTargetPipeFormatRequestForUrb 関数 (wdfusb.h)

構文

パラメーター

戻り値

備考

例

必要条件

関連項目

フィードバック

その他のリソース