WdfUsbTargetPipeFormatRequestForWrite 関数 (wdfusb.h)

[アーティクル]
08/08/2023

[KMDF と UMDF に適用]

WdfUsbTargetPipeFormatRequestForWrite メソッドは、USB 出力パイプの書き込み要求を作成しますが、要求は送信しません。

構文

NTSTATUS WdfUsbTargetPipeFormatRequestForWrite(
  [in]           WDFUSBPIPE        Pipe,
  [in]           WDFREQUEST        Request,
  [in, optional] WDFMEMORY         WriteMemory,
  [in, optional] PWDFMEMORY_OFFSET WriteOffset
);

パラメーター

[in] Pipe

WdfUsbInterfaceGetConfiguredPipe を呼び出して取得されたフレームワークパイプオブジェクトへのハンドル。

[in] Request

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

[in, optional] WriteMemory

フレームワークメモリオブジェクトへのハンドル。このオブジェクトは、パイプに送信されるデータを含むバッファーを表します。このバッファーの詳細については、次の「備考」セクションを参照してください。

[in, optional] WriteOffset

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

戻り値

操作が成功した場合、WdfUsbTargetPipeFormatRequestForWrite はSTATUS_SUCCESSを返します。それ以外の場合、このメソッドは次のいずれかの値を返す可能性があります。

リターンコード	説明
STATUS_INVALID_PARAMETER	無効なパラメーターが検出されました。
STATUS_INSUFFICIENT_RESOURCES	メモリが不足していました。
STATUS_INVALID_DEVICE_REQUEST	無効なメモリ記述子が指定されたか、パイプの種類が無効か、転送方向が無効か、指定された I/O 要求が既に I/O ターゲットにキューに入れられました。
STATUS_INTEGER_OVERFLOW	Offset パラメーターが指定したオフセットが無効です。
STATUS_REQUEST_NOT_ACCEPTED	要求パラメーターが表す I/O 要求パケット (IRP) は、ドライバーが要求を転送できるようにするための十分なIO_STACK_LOCATION構造を提供しません。

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

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

注釈

WdfUsbTargetPipeFormatRequestForWrite の後に WdfRequestSend を使用して、書き込み要求を同期的または非同期的に送信します。または、 WdfUsbTargetPipeWriteSynchronously メソッドを使用して、書き込み要求を同期的に送信します。

指定したパイプは出力パイプである必要があり、パイプの種類は WdfUsbPipeTypeBulk または WdfUsbPipeTypeInterrupt である必要があります。

ドライバーが I/O キューで受信した I/O 要求を転送することも、新しい要求を作成して送信することもできます。どちらの場合も、フレームワークには要求オブジェクトとバッファー領域が必要です。

ドライバーが I/O キューで受信した I/O 要求を転送するには:

WdfUsbTargetPipeFormatRequestForWrite メソッドの Request パラメーターに対して、受信した要求のハンドルを指定します。
WdfUsbTargetPipeFormatRequestForWrite メソッドの WriteMemory パラメーターには、受信した要求の入力バッファーを使用します。
ドライバーは WdfRequestRetrieveInputMemory を呼び出して、要求の入力バッファーを表すフレームワークメモリオブジェクトへのハンドルを取得し、そのハンドルを WriteMemory の値として使用する必要があります。

I/O 要求の転送の詳細については、「I /O 要求の転送」を参照してください。

ドライバーは、多くの場合、受信した I/O 要求を、I/O ターゲットに送信する小さな要求に分割するため、ドライバーが新しい要求を作成する可能性があります。

新しい I/O 要求を作成するには:

新しい要求オブジェクトを作成し、 WdfUsbTargetPipeFormatRequestForWrite メソッドの Request パラメーターのハンドルを指定します。
WdfRequestCreate を呼び出して、1 つ以上の要求オブジェクトを事前割り当てします。これらの要求オブジェクトを再利用するには、 WdfRequestReuse を呼び出します。ドライバーの EvtDriverDeviceAdd コールバック関数は、デバイスの要求オブジェクトを事前割り当てできます。
バッファー領域を指定し、 WdfUsbTargetPipeFormatRequestForWrite メソッドの WriteMemory パラメーターのバッファーのハンドルを指定します。
ドライバーでは、フレームワークマネージドメモリへの WDFMEMORY ハンドルとしてこのバッファー領域を指定する必要があります。ドライバーは、次のいずれかを実行できます。
- ドライバーが新しいバッファーを I/O ターゲットに渡す場合は、 WdfMemoryCreate または WdfMemoryCreatePreallocated を呼び出して新しいメモリバッファーを作成します。
- WdfRequestRetrieveInputMemory を呼び出して、受信した I/O 要求のバッファーを表すメモリオブジェクトへのハンドルを取得します (ドライバーがそのバッファーの内容を I/O ターゲットに渡す場合)。
ドライバーが WdfRequestRetrieveInputMemory を呼び出し、メモリハンドルを WdfUsbTargetPipeFormatRequestForWrite に渡す場合、ドライバーは、ドライバーが新しいドライバー作成の要求オブジェクトを削除、再利用、または再フォーマットするまで、受信した I/O 要求を完了しないようにする必要があることに注意してください。 (WdfUsbTargetPipeFormatRequestForWrite は、メモリオブジェクトの参照カウントをインクリメントします。要求オブジェクトを削除、再利用、または再フォーマットすると、メモリオブジェクトの参照カウントがデクリメントされます)。

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

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

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

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

例

次のコード例は、 kmdf_fx2 サンプルドライバーのコード例です。この例は、書き込み要求を USB パイプに転送する EvtIoWrite コールバック関数です。この例では、WdfRequestRetrieveInputMemory を呼び出して要求の入力バッファーを取得し、USB パイプに要求を送信できるように書き込み要求を書式設定します。次に、 CompletionRoutine コールバック関数を登録します。最後に、USB パイプに要求を送信します。

VOID 
OsrFxEvtIoWrite(
    IN WDFQUEUE  Queue,
    IN WDFREQUEST  Request,
    IN size_t  Length
    )
{
    NTSTATUS  status;
    WDFUSBPIPE  pipe;
    WDFMEMORY  reqMemory;
    PDEVICE_CONTEXT  pDeviceContext;
 
    if (Length > TEST_BOARD_TRANSFER_BUFFER_SIZE) {
        status = STATUS_INVALID_PARAMETER;
        goto Exit;
    }

    pDeviceContext = GetDeviceContext(WdfIoQueueGetDevice(Queue));
 
    pipe = pDeviceContext->BulkWritePipe;

    status = WdfRequestRetrieveInputMemory(
                                           Request,
                                           &reqMemory
                                           );
    if (!NT_SUCCESS(status)){
        goto Exit;
    }

    status = WdfUsbTargetPipeFormatRequestForWrite(
                                                   pipe,
                                                   Request,
                                                   reqMemory,
                                                   NULL
                                                   );
    if (!NT_SUCCESS(status)) {
        goto Exit;
    }

    WdfRequestSetCompletionRoutine(
                                   Request,
                                   EvtRequestWriteCompletionRoutine,
                                   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
最小 UMDF バージョン	2.0
Header	wdfusb.h (Wdfusb.h を含む)
Library	Wdf01000.sys (KMDF);WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
DDI コンプライアンス規則	DriverCreate(kmdf), KmdfIrql(kmdf)、KmdfIrql2(kmdf)、KmdfIrqlExplicit(kmdf)、RequestFormattedValid(kmdf)、RequestSendAndForgetNoFormatting(kmdf)、RequestSendAndForgetNoFormatting2(kmdf)、UsbKmdfIrql(kmdf)、UsbKmdfIrql2 (kmdf)、UsbKmdfIrqlExplicit(kmdf)

こちらもご覧ください

WdfUsbTargetPipeFormatRequestForRead

WdfUsbTargetPipeFormatRequestForWrite 関数 (wdfusb.h)

構文

パラメーター

戻り値

注釈

例

要件

こちらもご覧ください

フィードバック

フィードバック

その他のリソース