WdfIoQueueAssignForwardProgressPolicy 関数 (wdfio.h)

  • [アーティクル]

[KMDF にのみ適用]

WdfIoQueueAssignForwardProgressPolicy メソッドを使用すると、フレームワークは、指定された I/O キューの進行を保証できます。

構文

NTSTATUS WdfIoQueueAssignForwardProgressPolicy(
  [in] WDFQUEUE                              Queue,
  [in] PWDF_IO_QUEUE_FORWARD_PROGRESS_POLICY ForwardProgressPolicy
);

パラメーター

[in] Queue

フレームワーク キュー オブジェクトへのハンドル。

[in] ForwardProgressPolicy

ドライバーによって割り当てられた WDF_IO_QUEUE_FORWARD_PROGRESS_POLICY 構造体へのポインター。

戻り値

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

リターン コード 説明
STATUS_INVALID_PARAMETER
 入力パラメーターが無効です。
STATUS_INFO_LENGTH_MISMATCH
 WDF_IO_QUEUE_FORWARD_PROGRESS_POLICY構造体のサイズが正しくありません。
STATUS_INSUFFICIENT_RESOURCES
 使用可能なメモリの量が少なすぎます。
 

このメソッドは、他の NTSTATUS 値を返す場合もあります。 さらに、ドライバーの EvtIoAllocateResourcesForReservedRequest コールバック関数がエラー状態値を返す場合、 WdfIoQueueAssignForwardProgressPolicy はその値を返します。

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

注釈

WdfIoQueueAssignForwardProgressPolicy メソッドは、メモリ不足の状況に備えてフレームワークが予約する要求オブジェクトを作成し、メモリ不足の状況を処理するためにフレームワークが呼び出すコールバック関数を登録します。

KMDF バージョン 1.9 では、 Queue パラメーターが表す I/O キューは、デバイスの既定の I/O キュー、またはドライバーが WdfDeviceConfigureRequestDispatching を呼び出したキューである必要があります。 ドライバーは、WdfDeviceConfigureRequestDispatching を呼び出した後、いつでも WdfIoQueueAssignForwardProgressPolicy を呼び出すことができます。

KMDF バージョン 1.11 以降では、 Queue パラメーターが表す I/O キューは、フレームワークから直接要求を受信する任意のキューにすることができます。 たとえば、ドライバーでは、IRP を 動的に転送するキューを指定できます。

WdfIoQueueAssignForwardProgressPolicy が返される前に、フレームワークは次の処理を行います。

  • WDF_IO_QUEUE_FORWARD_PROGRESS_POLICY構造体の TotalForwardProgressRequests メンバーに対してドライバーが指定した要求オブジェクトの数を作成して格納します。
  • ドライバーが以前 に WdfDeviceInitSetRequestAttributes と呼んだ場合、各割り当てには 、WdfDeviceInitSetRequestAttributes が指定したコンテキスト領域が含まれます。
  • フレームワークが作成する要求オブジェクトごとに、ドライバーの EvtIoAllocateResourcesForReservedRequest コールバック関数を呼び出します。
ドライバーが WdfIoQueueAssignForwardProgressPolicy を呼び出して予約済み要求オブジェクトを作成した後、フレームワークは、新しい要求オブジェクトの作成が失敗するたびに、これらの予約済みオブジェクトを使用します。 (通常、このようなエラーはメモリ不足の状況によって発生します)。

フレームワークは、自分が属しているフレームワーク キュー オブジェクトを削除した場合にのみ、予約済み要求オブジェクトを削除します。 ドライバーが WdfDeviceInitSetRequestAttributes を呼び出し、その要求オブジェクトに 対して EvtCleanupCallback または EvtDestroyCallback コールバック関数を指定する場合、フレームワークはオブジェクトを削除するときに予約済み要求オブジェクトに対してこれらのコールバック関数を呼び出します。

WdfIoQueueAssignForwardProgressPolicy メソッドの詳細と、フレームワークの保証された転送進行状況機能の使用方法については、「I/O 操作の前方進行状況の保証」を参照してください。

例

このコード例では、書き込み要求を受信するように以前に作成した I/O キューを構成し、キューの転送の確実な進行状況を有効にします。

#define MAX_RESERVED_REQUESTS 10

WDF_IO_QUEUE_FORWARD_PROGRESS_POLICY queueForwardProgressPolicy;
WDFQUEUE writeQueue;
NTSTATUS status = STATUS_SUCCESS;
...
status = WdfDeviceConfigureRequestDispatching(
             device,
             writeQueue,
             WdfRequestTypeWrite
             );
if(!NT_SUCCESS(status)) {
    return status;
}
WDF_IO_QUEUE_FORWARD_PROGRESS_POLICY_DEFAULT_INIT(
    &queueForwardProgressPolicy,
    MAX_RESERVED_REQUESTS
    );
status = WdfIoQueueAssignForwardProgressPolicy(
             writeQueue,
             &queueForwardProgressPolicy
             );
if(!NT_SUCCESS(status)) {
    return status;
}

要件

要件 値
対象プラットフォーム ユニバーサル
最小 KMDF バージョン 1.9
Header wdfio.h (Wdf.h を含む)
Library Wdf01000.sys (「Framework ライブラリのバージョン管理」を参照)。
IRQL PASSIVE_LEVEL
DDI コンプライアンス規則 DriverCreate(kmdf)

こちらもご覧ください

EvtIoAllocateResourcesForReservedRequest

WDF_IO_QUEUE_FORWARD_PROGRESS_POLICY

WdfDeviceConfigureRequestDispatching