WdfRequestCompleteWithInformation 関数 (wdfrequest.h)

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

[KMDF と UMDF に適用]

WdfRequestCompleteWithInformation メソッドは、完了情報を格納し、指定された完了状態で指定された I/O 要求を完了します。

構文

void WdfRequestCompleteWithInformation(
  [in] WDFREQUEST Request,
  [in] NTSTATUS   Status,
  [in] ULONG_PTR  Information
);

パラメーター

[in] Request

要求オブジェクトへのハンドル。

[in] Status

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

STATUS_SUCCESS

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

STATUS_CANCELLED

ドライバーが要求を取り消しました。

STATUS_UNSUCCESSFUL

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

[in] Information

要求に依存する値に設定されるULONG_PTR。たとえば、転送要求が正常に完了すると、これは転送されたバイト数に設定されます。このフィールドは、ドライバーでは拡張できません。

戻り値

なし

解説

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

読み取り、書き込み、および IOCTL 要求の場合、ドライバーが WdfRequestCompleteWithInformation を呼び出す必要があります

データ転送以外の要求の場合は、代わりに WdfRequestComplete を呼び出すオプションがあります。

WdfRequestCompleteWithInformation の呼び出しは、WdfRequestSetInformation を呼び出してから WdfRequestComplete を呼び出すことと同じです。

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

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

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

WdfRequestCompleteWithInformation を使用してコピーされたバイト数を取得する方法を示すコード例については、VirtualSerial2 ドライバーのサンプルを参照してください。

例

次のコード例は、USB デバイスのドライバーが CompletionRoutine コールバック関数で WdfRequestCompleteWithInformation を呼び出す方法を示しています。

VOID
EvtRequestReadCompletionRoutine(
    IN WDFREQUEST  Request,
    IN WDFIOTARGET  Target,
    PWDF_REQUEST_COMPLETION_PARAMS  CompletionParams,
    IN WDFCONTEXT  Context
    )
{    
    NTSTATUS  status;
    size_t  bytesRead = 0;
    PWDF_USB_REQUEST_COMPLETION_PARAMS  usbCompletionParams;

    UNREFERENCED_PARAMETER(Target);
    UNREFERENCED_PARAMETER(Context);

    status = CompletionParams->IoStatus.Status;
    usbCompletionParams = CompletionParams->Parameters.Usb.Completion;
    bytesRead =  usbCompletionParams->Parameters.PipeRead.Length;
 
    if (NT_SUCCESS(status)){
        TraceEvents(
                    TRACE_LEVEL_INFORMATION,
                    DBG_READ,
                    "Number of bytes read: %I64d\n",
                    (INT64)bytesRead
                    );
    } else {
        TraceEvents(
                    TRACE_LEVEL_ERROR,
                    DBG_READ,
                    "Read failed - request status 0x%x UsbdStatus 0x%x\n",
                    status,
                    usbCompletionParams->UsbdStatus
                    );
    }
    WdfRequestCompleteWithInformation(
                                      Request,
                                      status,
                                      bytesRead
                                      );
    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)