EVT_WDF_IO_QUEUE_IO_STOP コールバック関数 (wdfio.h)

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

[KMDF と UMDF に適用]

ドライバーの EvtIoStop イベントコールバック関数は、要求の I/O キューが停止されているため、指定された要求の処理を完了、再キュー、または中断します。

構文

EVT_WDF_IO_QUEUE_IO_STOP EvtWdfIoQueueIoStop;

void EvtWdfIoQueueIoStop(
  [in] WDFQUEUE Queue,
  [in] WDFREQUEST Request,
  [in] ULONG ActionFlags
)
{...}

パラメーター

[in] Queue

I/O 要求に関連付けられているフレームワークキューオブジェクトへのハンドル。

[in] Request

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

[in] ActionFlags

コールバック関数が呼び出される理由と要求が取り消し可能かどうかを識別する 1 つ以上の WDF_REQUEST_STOP_ACTION_FLAGS型指定フラグのビットごとの OR。

戻り値

なし

解説

ドライバーは、WdfIoQueueCreate を呼び出すときに EvtIoStop コールバック関数を登録します。 WdfIoQueueCreate の呼び出しの詳細については、「I/O キューの作成」を参照してください。

ドライバーが I/O キューの EvtIoStop コールバック関数を登録する場合、フレームワークは、キューの基になるデバイスが動作 (D0) 状態を離れると、それを呼び出します。フレームワークは、ドライバーが所有する要求や I/O ターゲットに転送された要求など、ドライバーが完了していないすべての I/O 要求に対して EvtIoStop コールバック関数を呼び出します。

ほとんどの場合、 EvtIoStop コールバック関数は、I/O 要求の処理をさらに完了、取り消し、または延期します。

通常、ドライバーは次のいずれかを実行します。

ドライバーが I/O 要求を所有している場合は、WdfRequestUnmarkCancelable (要求が取り消し可能な場合) を呼び出し、Requeue 値が TRUE の WdfRequestStopAcknowledge を呼び出すか、完了状態値が STATUS_SUCCESS または STATUS_CANCELLED の WdfRequestComplete を呼び出します。
WdfRequestXxx メソッドを安全に呼び出す前に、ドライバーは EvtIoStop の実装が要求への排他的アクセス権を持っていることを確認する必要があります。

そのためには、ドライバーが要求へのアクセスを同期して、他のスレッドが要求を同時に操作できないようにする必要があります。選択する同期方法は、ドライバーの設計によって異なります。

たとえば、要求が共有コンテキスト領域に保持されている場合、 EvtIoStop コールバックは内部ドライバーロックを取得し、共有コンテキストから要求を削除して、ロックを解除する場合があります。この時点で、 EvtIoStop コールバックは要求を所有し、要求を安全に完了または再要求できます。

または、ドライバーは要求の処理をさらに延期し、Requeue 値が FALSE の WdfRequestStopAcknowledge を呼び出します。
ドライバーが I/O 要求を I/O ターゲットに転送した場合は、 WdfRequestCancelSentRequest を呼び出して要求を取り消すことができます。
または、ドライバーが独自のドライバースタック内の下位レベルのドライバーに I/O 要求を転送し、フレームワークがドライバーの EvtIoStop コールバックを呼び出し、ActionFlags 値が WdfRequestStopActionSuspend の場合、ドライバーは Requeue 値を FALSE で WdfRequestStopAcknowledge を呼び出すことができます。その前に、ドライバーは次の条件が満たされていることを確認する必要があります。
- 下位ドライバーは、デバイスセット電源 IRP (Dx) の受信に応じて、未処理のすべての I/O 要求の処理を停止します。
- ドライバーの CompletionRoutine コールバック関数は、デバイスが低電力状態の間に要求を完了できます。

ドライバーは、少量の時間で完了することが保証されている要求に対して 、EvtIoStop でアクションを実行しないように選択する場合があります。

この場合、フレームワークは、指定された要求が完了するまで待機してから、デバイス (またはシステム) を低電力状態に移動するか、デバイスを削除します。この操作によって、システムが休止状態または別の低電力状態になるのを防ぐことができます。極端なケースでは、バグチェックコード 9F でシステムがクラッシュする可能性があります。

ActionFlags パラメーターに WdfRequestStopRequestCancelable フラグが設定されている場合、ドライバーは WdfRequestUnmarkCancelable を呼び出してから WdfRequestComplete を呼び出して要求を完了 (またはキャンセル) するか、WdfRequestStopAcknowledge を呼び出して要求を再キューする必要があります。

ドライバーが要求ハンドラーの 1 つから I/O 要求を転送し、要求の WDF_REQUEST_SEND_OPTIONS 構造で WDF_REQUEST_SEND_OPTION_SEND_AND_FORGET フラグを指定した場合、フレームワークはこの要求に対してドライバーの EvtIoStop コールバック関数を呼び出しません。ただし、ドライバーが別のスレッドから同じ I/O 要求を転送する場合、フレームワークはこの要求に対して EvtIoStop を呼び出す可能性があります。

EvtIoStop コールバック関数の詳細については、「Power-Managed I/O キューの使用」を参照してください。

このコールバック関数は、デバイスまたはドライバーのWDF_OBJECT_ATTRIBUTES構造体の ExecutionLevel メンバーが WdfExecutionLevelPassive に設定されていない限り、IRQL <= DISPATCH_LEVELで呼び出すことができます。

要件

要件	値
対象プラットフォーム	ユニバーサル
最小 KMDF バージョン	1.0
最小 UMDF バージョン	2.0
Header	wdfio.h (Wdf.h を含む)
IRQL	<= DISPATCH_LEVEL (「解説」セクションを参照)