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、ドライバーが登録解除されている場合は NULL 。

戻り値

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

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

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

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

注釈

ドライバーが WdfIoQueueReadyNotify を呼び出して EvtIoQueueState コールバック関数を登録した後、フレームワークは、指定されたキューの状態が空から空でない状態に変わるたびにコールバック関数を呼び出します。 具体的には、ドライバーがまだ完了していないキューから以前に配信された要求をドライバーが所有している場合でも、空のキューに要求が到着したときに、フレームワークは EvtIoQueueState を呼び出します。 キュー作成時に WDF_OBJECT_ATTRIBUTES でExecutionLevel を指定することで、コールバックが実行される IRQL を変更できます。 詳細については、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 要求のメソッドのディスパッチ」を参照してください。

例

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

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