WdfRequestStopAcknowledge 関数 (wdfrequest.h)
[KMDF と UMDF に適用]
WdfRequestStopAcknowledge メソッドは、ドライバーが指定された I/O 要求の処理を停止したことをフレームワークに通知します。
構文
void WdfRequestStopAcknowledge(
[in] WDFREQUEST Request,
[in] BOOLEAN Requeue
);
パラメーター
[in] Request
フレームワーク要求オブジェクトへのハンドル。
[in] Requeue
TRUE の場合、フレームワークが要求をキューに再キューに入れ直して、フレームワークがドライバーに再度配信するようにするブール値。 FALSE の場合、フレームワークは要求を再要求しません。 詳細については、「解説」を参照してください。
戻り値
なし
解説
ドライバーが無効なオブジェクト ハンドルを提供すると、バグ チェックが発生します。
ドライバーが I/O キューの EvtIoStop コールバック関数を登録する場合、フレームワークは、キューの基になるデバイスが動作 (D0) 状態を離れると、それを呼び出します。 フレームワークは、ドライバーが所有する要求や I/O ターゲットに転送された要求など、ドライバーが完了していないすべての I/O 要求に対して EvtIoStop コールバック関数を呼び出します。 ドライバーは、次のいずれかの操作を行って、各要求の処理を完了、取り消し、または延期する必要があります。
- ドライバーが要求を所有している場合は、 WdfRequestComplete を呼び出して要求を完了または取り消すことができます。
- ドライバーが要求を I/O ターゲットに転送した場合は、 WdfRequestCancelSentRequest を呼び出して要求を取り消すことができます。
- ドライバーが要求の処理を延期する場合は、 WdfRequestStopAcknowledge を呼び出す必要があります。
ドライバーが完了、取り消し、または EvtIoStop コールバック関数が受け取るすべての要求を延期するまで、フレームワークはデバイスが動作 (D0) 状態を残すことを許可しません。 この操作によって、システムが休止状態または別の低電力状態になるのを防ぐことができます。
ドライバーの EvtIoStop コールバック関数が WdfRequestStopAcknowledge を呼び出すと、 Requeue パラメーターを TRUE または FALSE に設定できます。
-
Requeue を TRUE に設定すると、フレームワークは要求を I/O キューに戻します。
基になるデバイスが動作 (D0) 状態に戻ると、フレームワークはドライバーに要求を再配信します。
-
Requeue を FALSE に設定すると、フレームワークは要求を再要求しません。 ドライバーが要求 を所有している 場合、所有権はドライバーに残ります。 ドライバーが要求を転送した場合、ドライバーは要求の完了時に処理を担当します。 ドライバーは、ハードウェア アクセスを必要とする I/O 処理の実行を停止する必要があります。
基になるデバイスが動作 (D0) 状態に戻ると、フレームワークはドライバーの EvtIoResume コールバック関数を呼び出して、ドライバーが要求の処理を続行できるようにします。
WdfRequestStopAcknowledge を呼び出す前に、ドライバーの EvtIoStop コールバック関数は、デバイスが低電力状態になるため、基になるデバイスへのアクセスを必要とする I/O 要求のすべての処理を停止する必要があります。
WdfRequestStopAcknowledge メソッドの詳細については、「Power-Managed I/O キューの使用」を参照してください。
例
ドライバーが Requeue を TRUE に設定して WdfRequestStopAcknowledge を呼び出す場合は、以前に WdfRequestUnmarkCancelable を呼び出す必要があります。
次のコード例は、受信した要求が取り消し可能かどうかを確認し、その場合は WdfRequestUnmarkCancelable を呼び出す EvtIoStop コールバック関数です。 WdfRequestUnmarkCancelable が STATUS_CANCELLEDを返す場合、この例では、ドライバーの EvtRequestCancel コールバック関数が要求を処理するため、単に が返されます。 それ以外の場合、この例では WdfRequestStopAcknowledge を呼び出し、基になるデバイスが動作 (D0) 状態に戻ったときにフレームワークが要求を再要求するように TRUE を 指定します。
VOID
MyEvtIoStop(
IN WDFQUEUE Queue,
IN WDFREQUEST Request,
IN ULONG ActionFlags
)
{
NTSTATUS status;
// TODO: Take steps here to suspend and, if necessary, roll back any processing that has already occurred on this request
if (ActionFlags & WdfRequestStopRequestCancelable) {
status = WdfRequestUnmarkCancelable(Request);
if (status == STATUS_CANCELLED) {
return;
}
}
// Inform framework that driver is postponing processing, cause framework to redeliver request when device returns to D0
WdfRequestStopAcknowledge(Request, TRUE);
}
通常、ドライバーが Requeueを FALSE に設定して WdfRequestStopAcknowledge を呼び出すと、要求は取り消し可能な状態になります。
次のコード例は、WdfRequestStopAcknowledge を呼び出し、FALSE を指定して、フレームワークが最終的にドライバーの EvtIoResume コールバック関数を呼び出して、ドライバーが要求の処理を再開するようにする EvtIoStop コールバック関数です。
要求を再配信して最初から処理を再開するのではなく、特定の要求の処理を停止して後で続行することが許容される場合は、このようなコードを使用できます。
VOID
MyEvtIoStop(
IN WDFQUEUE Queue,
IN WDFREQUEST Request,
IN ULONG ActionFlags
)
{
//TODO: Take steps here to suspend processing of the request so it can be resumed when power returns
// Acknowledge the stop, but leave the request under driver's ownership.
// Provide a corresponding EvtIoResume handler to resume processing when power returns
WdfRequestStopAcknowledge(Request, FALSE);
}
要件
| 要件 | 値 |
|---|---|
| 対象プラットフォーム | ユニバーサル |
| 最小 KMDF バージョン | 1.0 |
| 最小 UMDF バージョン | 2.0 |
| Header | wdfrequest.h (Wdf.h を含む) |
| Library | Wdf01000.sys (KMDF);WUDFx02000.dll (UMDF) |
| IRQL | <=DISPATCH_LEVEL |
| DDI コンプライアンス規則 | DeferredRequestCompleted(kmdf)、DriverCreate(kmdf)、 EvtIoStopCancel(kmdf)、EvtIoStopCompleteOrStopAck(kmdf)、EvtIoStopResume(kmdf)、KmdfIrql(kmdf)、KmdfIrql2(kmdf)、KmdfIrqlExplicit(kmdf)、RequestCompleted(kmdf)、RequestCompletedLocal(kmdf)、StopAckWithinEvtIoStop(kmdf) |