WdfIoTargetFormatRequestForRead 関数 (wdfiotarget.h)

[KMDF と UMDF に適用]

WdfIoTargetFormatRequestForRead メソッドは、I/O ターゲットの読み取り要求を作成しますが、要求は送信しません。

構文

NTSTATUS WdfIoTargetFormatRequestForRead(
  [in]           WDFIOTARGET       IoTarget,
  [in]           WDFREQUEST        Request,
  [in, optional] WDFMEMORY         OutputBuffer,
  [in, optional] PWDFMEMORY_OFFSET OutputBufferOffset,
  [in, optional] PLONGLONG         DeviceOffset
);

パラメーター

[in] IoTarget

WdfDeviceGetIoTarget または WdfIoTargetCreate の以前の呼び出し、または特殊化された I/O ターゲットが提供するメソッドから取得されたローカルまたはリモートの I/O ターゲット オブジェクトへのハンドル。

[in] Request

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

[in, optional] OutputBuffer

フレームワーク メモリ オブジェクトへのハンドル。 このオブジェクトは、I/O ターゲットからデータを受信するバッファーを表します。 このパラメーターは省略可能であり、 NULL にすることができます。 このパラメーターの詳細については、次の「解説」セクションを参照してください。

[in, optional] OutputBufferOffset

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

[in, optional] DeviceOffset

転送の開始オフセットを指定する変数へのポインター。 I/O ターゲット (つまり、次の下位ドライバー) は、この値の使用方法を定義します。 たとえば、ディスクのドライバー スタック内のドライバーは、ディスクの先頭からのオフセットを指定する場合があります。 I/O ターゲットは、要求のWDF_REQUEST_PARAMETERS構造体の Parameters.Read.DeviceOffset メンバーでこの情報 取得します。 このポインターは省略可能です。 ほとんどのドライバーは、このポインターを NULL に設定 します

戻り値

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

リターン コード 説明
STATUS_INVALID_PARAMETER
無効なパラメーターが検出されました。
STATUS_INVALID_DEVICE_REQUEST
転送長がバッファー長を超えているか、I/O 要求が既に I/O ターゲットにキューに入れられました。
STATUS_INSUFFICIENT_RESOURCES
フレームワークはシステム リソース (通常はメモリ) を割り当てませんでした。
STATUS_REQUEST_NOT_ACCEPTED
要求パラメーターが表す I/O 要求パケット (IRP) は、ドライバーが 要求 を転送できるようにするため の十 分なIO_STACK_LOCATION構造を提供しません。
 

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

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

注釈

読み取り要求を同期的または非同期的に送信するには、 WdfIoTargetFormatRequestForRead メソッドと WdfRequestSend メソッドを使用します。 または、 WdfIoTargetSendReadSynchronously メソッドを使用して、読み取り要求を同期的に送信します。

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

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

  1. WdfIoTargetFormatRequestForRead メソッドの Request パラメーターに対して、受信した要求のハンドルを指定します。
  2. WdfIoTargetFormatRequestForRead メソッドの OutputBuffer パラメーターには、受信した要求の出力バッファーを使用します。

    ドライバーは WdfRequestRetrieveOutputMemory を呼び出して、要求の出力バッファーを表すフレームワーク メモリ オブジェクトへのハンドルを取得し、そのハンドルを OutputBuffer の値として使用する必要があります。

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

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

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

  1. 新しい要求オブジェクトを作成し、 WdfIoTargetFormatRequestForRead メソッドの Request パラメーターのハンドルを 指定 します。

    WdfRequestCreate を呼び出して、1 つ以上の要求オブジェクトを事前割り当てします。 これらの要求オブジェクトを再利用するには、 WdfRequestReuse を呼び出します。 ドライバーの EvtDriverDeviceAdd コールバック関数は、デバイスの要求オブジェクトを事前割り当てできます。

  2. バッファー領域を指定し、 WdfIoTargetFormatRequestForRead メソッドの OutputBuffer パラメーターのバッファーのハンドルを指定します。

    ドライバーでは、フレームワークマネージド メモリへの WDFMEMORY ハンドルとしてこのバッファー領域を指定する必要があります。 ドライバーは、次のいずれかを実行できます。

    • ドライバーが新しいバッファーを I/O ターゲットに渡す場合は、 WdfMemoryCreate または WdfMemoryCreatePreallocated を呼び出して新しいメモリ バッファーを作成します。
    • WdfRequestRetrieveOutputMemory を呼び出して、受信した I/O 要求のバッファーを表すメモリ オブジェクトへのハンドルを取得します (ドライバーがそのバッファーの内容を I/O ターゲットに渡す場合)。
    ドライバーが WdfRequestRetrieveOutputMemory を呼び出し、メモリ ハンドルを WdfIoTargetFormatRequestForRead に渡す場合、ドライバーは、ドライバーが新しいドライバー作成の要求オブジェクトを削除、再利用、または再フォーマットするまで、受信した I/O 要求を完了してはなりません。 (WdfIoTargetFormatRequestForRead は、メモリ オブジェクトの参照カウントをインクリメントします。要求オブジェクトを削除、再利用、または再フォーマットすると、メモリ オブジェクトの参照カウントがデクリメントされます)。
一部の I/O ターゲットは、長さ 0 のバッファーを持つ読み取り要求を受け入れます。 このような I/O ターゲットの場合、ドライバーは OutputBuffer パラメーターに NULL を指定できます。

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

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

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

WdfIoTargetFormatRequestForRead の詳細については、「一般的な I/O ターゲットへの I/O 要求の送信」を参照してください。

I/O ターゲットの詳細については、「I /O ターゲットの使用」を参照してください。

次のコード例では、読み取り要求の出力バッファー用のフレームワーク メモリ オブジェクトを作成し、読み取り要求の書式設定を行い、 CompletionRoutine コールバック関数を登録して、読み取り要求を I/O ターゲットに送信します。

WDFREQUEST  request;
NTSTATUS  status;
WDFMEMORY  memory;
WDF_OBJECT_ATTRIBUTES  attributes;

WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
status = WdfMemoryCreate(
                         &attributes,
                         NonPagedPool,
                         DRIVER_TAG,
                         READ_BUF_SIZE,
                         &memory,
                         NULL
                         );

if (!NT_SUCCESS(status)) {
    return status;
}

status = WdfIoTargetFormatRequestForRead(
                                         IoTarget,
                                         request,
                                         memory,
                                         NULL,
                                         NULL
                                         );
if (!NT_SUCCESS(status)) {
        return status;
}
WdfRequestSetCompletionRoutine(
                               request,
                               MyReadRequestCompletionRoutine,
                               targetInfo
                               );
if (WdfRequestSend(
                   request,
                   IoTarget,
                   WDF_NO_SEND_OPTIONS
                   ) == FALSE) {
        status = WdfRequestGetStatus(request);
}

要件

要件
対象プラットフォーム ユニバーサル
最小 KMDF バージョン 1.0
最小 UMDF バージョン 2.0
Header wdfiotarget.h (Wdf.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)

こちらもご覧ください

EvtDriverDeviceAdd

WDFMEMORY_OFFSET

WDF_REQUEST_PARAMETERS

WdfDeviceGetIoTarget

WdfIoTargetCreate

WdfIoTargetFormatRequestForWrite

WdfIoTargetSendReadSynchronously

WdfMemoryCreate

WdfMemoryCreatePreallocated

WdfRequestCreate

WdfRequestRetrieveOutputMemory

WdfRequestReuse

WdfRequestSend