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 を呼び出す必要があります。
ドライバーが WdfRequestStopAcknowledge を呼び出す場合は、 EvtIoStop コールバック関数内からこのメソッドを呼び出す必要があります。

ドライバーが完了、取り消し、または EvtIoStop コールバック関数が受け取るすべての要求を延期するまで、フレームワークはデバイスが動作 (D0) 状態を残すことを許可しません。 この操作によって、システムが休止状態または別の低電力状態になるのを防ぐことができます。

ドライバーの EvtIoStop コールバック関数が WdfRequestStopAcknowledge を呼び出すと、 Requeue パラメーターを TRUE または FALSE に設定できます。

  • Requeue を TRUE に設定すると、フレームワークは要求を I/O キューに戻します。

    基になるデバイスが動作 (D0) 状態に戻ると、フレームワークはドライバーに要求を再配信します。

  • Requeue を FALSE に設定すると、フレームワークは要求を再要求しません。 ドライバーが要求 を所有している 場合、所有権はドライバーに残ります。 ドライバーが要求を転送した場合、ドライバーは要求の完了時に処理を担当します。 ドライバーは、ハードウェア アクセスを必要とする I/O 処理の実行を停止する必要があります。

    基になるデバイスが動作 (D0) 状態に戻ると、フレームワークはドライバーの EvtIoResume コールバック関数を呼び出して、ドライバーが要求の処理を続行できるようにします。

ドライバーが以前に WdfRequestMarkCancelable または WdfRequestMarkCancelableEx を呼び出していた場合は、Requeue が TRUE に設定された WdfRequestStopAcknowledge を呼び出す前に WdfRequestUnmarkCancelable を呼び出す必要があります。

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)

こちらもご覧ください

EvtIoStop

EvtRequestCancel

WdfRequestComplete