WdfRequestComplete 関数 (wdfrequest.h)

[アーティクル]
04/23/2024

[KMDF と UMDF に適用]

WdfRequestComplete メソッドは、指定された I/O 要求を完了し、完了状態を提供します。

構文

void WdfRequestComplete(
  [in] WDFREQUEST Request,
  [in] NTSTATUS   Status
);

パラメーター

[in] Request

完了している I/O 要求を表すフレームワーク要求オブジェクトへのハンドル。

[in] Status

要求の完了状態を表す NTSTATUS 値。有効な状態値には、次のものが含まれますが、これらに限定されません。

STATUS_SUCCESS

ドライバーが要求を正常に完了しています。

STATUS_CANCELLED

ドライバーが要求を取り消しています。

STATUS_UNSUCCESSFUL

要求の処理中にドライバーでエラーが発生しました。

戻り値

なし

解説

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

ドライバーが WdfRequestComplete を呼び出した後、ドライバースタック上の上位レベルのドライバーは WdfRequestGetStatus を呼び出して、 Status パラメーターに指定された完了状態値を取得できます。通常、ドライバーは CompletionRoutine コールバック関数内から WdfRequestGetStatus を呼び出します。

WdfRequestComplete の呼び出しが返された後、ドライバーが WdfObjectReference を呼び出して 1 つ以上の参照カウントを要求オブジェクトに追加しない限り、要求ハンドルは無効になります。 WdfRequestComplete が返された後、ドライバーは WdfObjectReference を呼び出した場合でも、関連付けられている WDM IRP 構造体へのアクセスを試みることはできません。この要件は、 WdfRequestRetrieveOutputBuffer や WdfRequestRetrieveInputBuffer など、WDFREQUEST でメソッドを呼び出すことによって、関連付けられた WDM IRP 構造体にアクセスする場合に拡張されます。

ドライバーが WdfRequestComplete を呼び出した後、ドライバーが要求を指定した場合、フレームワークはドライバーの EvtCleanupCallback 関数を呼び出します。

WdfRequestComplete を呼び出す代わりに、ドライバーは WdfRequestCompleteWithInformation または WdfRequestCompleteWithPriorityBoost を呼び出すことができます。詳細については、「 WdfRequestCompleteWithInformation の解説」を参照してください。

ドライバーが WdfRequestComplete を呼び出すと、フレームワークは、I/O 操作を要求したスレッドの実行時優先度を高めるためにシステムが使用する既定値を提供します。既定の優先度ブースト値の詳細については、「 I/O 要求の完了時の優先度ブーストの指定」を参照してください。ドライバーは WdfRequestCompleteWithPriorityBoost を呼び出して、既定の優先度ブースト値をオーバーライドできます。

WdfRequestComplete の呼び出しの詳細については、「I/O 要求の完了」を参照してください。

例

次のコード例は、要求ハンドラーのセクションです。要求ハンドラーは、読み取り要求と書き込み要求のみを受け入れ、要求の種類が読み取りまたは書き込みでない場合は、エラー状態で各要求を完了します。

VOID
MyEvtIoDefault(
    IN WDFQUEUE  Queue,
    IN WDFREQUEST  Request
    )
{
    WDF_REQUEST_PARAMETERS  params;
    WDF_DMA_DIRECTION  direction;

...
    WDF_REQUEST_PARAMETERS_INIT(&params);

    WdfRequestGetParameters(
                            Request,
                            &params
                            );

    //
    // Validate and gather parameters.
    //
    switch (params.Type) {
        case WdfRequestTypeRead:
            length = params.Parameters.Read.Length;
            direction = WdfDmaDirectionReadFromDevice;
            break;
        case WdfRequestTypeWrite:
            length = params.Parameters.Write.Length;
            direction = WdfDmaDirectionWriteToDevice;
            break;
        default:
            WdfRequestComplete(
                               Request,
                               STATUS_INVALID_DEVICE_REQUEST
                               );
            return;
    }
...
}

要件

要件	値
対象プラットフォーム	ユニバーサル
最小 KMDF バージョン	1.0
最小 UMDF バージョン	2.0
Header	wdfrequest.h (Wdf.h を含む)
Library	Wdf01000.sys (KMDF);WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
DDI コンプライアンス規則	BufAfterReqCompletedIntIoctl(kmdf), BufAfterReqCompletedIntIoctlA(kmdf), BufAfterReqCompletedIoctl(kmdf), BufAfterReqCompletedIoctlA(kmdf)、 BufAfterReqCompletedRead(kmdf)、 BufAfterReqCompletedReadA(kmdf)、 BufAfterReqCompletedWrite(kmdf)、 BufAfterReqCompletedWriteA(kmdf)、 CompleteCanceledReq(kmdf)、 DeferredRequestCompleted(kmdf)、 DoubleCompletion(kmdf)、 DoubleCompletionLocal(kmdf), DriverCreate(kmdf), EvtIoStopCancel(kmdf), EvtIoStopCompleteOrStopAck(kmdf), EvtSurpriseRemoveNoRequestComplete(kmdf), InvalidReqAccess(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), MarkCancOnCancReqLocal(kmdf), MdlAfterReqCompletedIntIoctl(kmdf), MdlAfterReqCompletedIntIoctlA(kmdf), MdlAfterReqCompletedIoctl(kmdf), MdlAfterReqCompletedIoctlA(kmdf), MdlAfterReqCompletedRead(kmdf), MdlAfterReqCompletedReadA(kmdf), MdlAfterReqCompletedWrite(kmdf), MdlAfterReqCompletedWriteA(kmdf), MemAfterReqCompletedIntIoctl(kmdf), MemAfterReqCompletedIntIoctlA(kmdf), MemAfterReqCompletedIoctl(kmdf), MemAfterReqCompletedIoctlA(kmdf), MemAfterReqCompletedRead(kmdf), MemAfterReqCompletedReadA(kmdf), MemAfterReqCompletedWrite(kmdf), MemAfterReqCompletedWriteA(kmdf)、 NoCancelFromEvtSurpriseRemove(kmdf)、 ReqDelete(kmdf)、 ReqIsCancOnCancReq(kmdf)、 ReqNotCanceledLocal(kmdf)、 ReqSendFail(kmdf)、 RequestCompleted(kmdf)、 RequestCompletedLocal(kmdf)