WdfIoQueueReadyNotify 関数 (wdfio.h)

[KMDF と UMDF に適用]

WdfIoQueueReadyNotify メソッドは、以前に空だった指定された I/O キューが 1 つ以上の I/O 要求を受信するたびにフレームワークが呼び出すイベント コールバック関数を登録 (または登録解除) します。

構文

NTSTATUS WdfIoQueueReadyNotify(
  [in]           WDFQUEUE               Queue,
  [in, optional] PFN_WDF_IO_QUEUE_STATE QueueReady,
  [in, optional] WDFCONTEXT             Context
);

パラメーター

[in] Queue

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

[in, optional] QueueReady

ドライバーが準備完了通知を登録している場合は、ドライバーが提供する EvtIoQueueState コールバック関数へのポインター。ドライバーが登録解除されている場合は NULL

[in, optional] Context

ドライバーが準備完了通知を登録している場合は、フレームワークが EvtIoQueueState コールバック関数に渡すドライバー指定のコンテキスト情報への型指定されていないポインター。ドライバーが登録解除されている場合は NULL

戻り値

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

リターン コード 説明
STATUS_INVALID_PARAMETER
ドライバーが無効なハンドルを指定しました。
STATUS_INVALID_DEVICE_REQUEST
この値は、次のいずれかが発生した場合に返されます。
  • 指定した I/O キューのWDF_IO_QUEUE_CONFIG構造体の DispatchType メンバーが WdfIoQueueDispatchManual ではありません。
  • ドライバーは以前 WdfIoQueueReadyNotify を呼び出し、 EvtIoQueueState コールバック関数を登録していました。
  • ドライバーは通知コールバック関数を登録解除しようとしていますが、コールバック関数が登録されていないか、ドライバーが WdfIoQueueStop または WdfIoQueueStopSynchronously を呼び出していません。
 

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

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

注釈

ドライバーが WdfIoQueueReadyNotify を呼び出して EvtIoQueueState コールバック関数を登録した後、フレームワークは、指定されたキューの状態が空から空でない状態に変わるたびにコールバック関数を呼び出します。 具体的には、ドライバーがまだ完了していないキューから以前に配信された要求をドライバーが所有している場合でも、空のキューに要求が到着したときに、フレームワークは EvtIoQueueState を呼び出します。 コールバックが実行される IRQL を変更するには、キュー作成時に WDF_OBJECT_ATTRIBUTESExecutionLevel を指定します。 詳細については、EVT_WDF_IO_QUEUE_STATEの「解説」セクションを参照してください。

指定されたキューが停止している間、フレームワークは EvtIoQueueState を呼び出しません。 キューが開始されると、キューが空でない場合、フレームワークは EvtIoQueueState を呼び出します。

ドライバーは、手動ディスパッチ メソッドを使用する I/O キューに対してのみ WdfIoQueueReadyNotify を呼び出すことができます。

EvtIoQueueState コールバック関数は、通常、ループ内で WdfIoQueueRetrieveNextRequest または WdfIoQueueRetrieveRequestByFileObject を呼び出して、コールバック関数が最後に実行されてから到着したすべての要求を取得します。

フレームワークが EvtIoQueueState コールバック関数を呼び出すのを停止するには、ドライバーは QueueReady パラメーターを NULL に設定して WdfIoQueueReadyNotify をもう一度呼び出す必要があります。 ただし、ドライバーは最初に WdfIoQueueStop または WdfIoQueueStopSynchronously を呼び出して I/O キューを停止する必要があります。 ドライバーは、後で WdfIoQueueStart を呼び出してキューを再起動できます。

ドライバーが WdfIoQueueReadyNotify を呼び出して EvtIoQueueState コールバック関数を登録すると、 WdfIoQueueReadyNotify が返される前にフレームワークがコールバック関数を呼び出す可能性があります。

WdfIoQueueReadyNotify メソッドの詳細については、「I/O 要求のディスパッチ メソッド」を参照してください。

次のコード例では、指定した I/O キューが I/O 要求を受信したときにこの関数が呼び出されるように、ドライバーの EvtIoQueueReady 関数を登録します。

Status = WdfIoQueueReadyNotify(
                               ReadQueue,
                               EvtIoQueueReady,
                               myQueueContext
                               );

要件

   
対象プラットフォーム ユニバーサル
最小 KMDF バージョン 1.0
最小 UMDF バージョン 2.0
Header wdfio.h (Wdf.h を含む)
Library Wdf01000.sys (KMDF);WUDFx02000.dll (UMDF)
IRQL <= DISPATCH_LEVEL
DDI コンプライアンス規則 DriverCreate(kmdf)KmdfIrql(kmdf)KmdfIrql2(kmdf)、KmdfIrqlExplicit(kmdf)

関連項目

EvtIoQueueState

WDF_IO_QUEUE_CONFIG

WdfIoQueueRetrieveNextRequest

WdfIoQueueRetrieveRequestByFileObject