WdfRequestComplete 函数 (wdfrequest.h)

项目
08/08/2023

[适用于 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

驱动程序在处理请求时遇到错误。

返回值

无

备注

如果驱动程序提供无效的对象句柄，则会发生 bug 检查。

驱动程序调用 WdfRequestComplete 后，驱动程序堆栈上的更高级别的驱动程序可以调用 WdfRequestGetStatus 以获取为 Status 参数指定的完成状态值。通常，驱动程序从 CompletionRoutine 回调函数中调用 WdfRequestGetStatus。

调用 WdfRequestComplete 返回后，请求句柄不再有效，除非驱动程序已调用 WdfObjectReference 向请求对象添加一个或多个其他引用计数。请注意， 在 WdfRequestComplete 返回后，驱动程序不得尝试访问关联的 WDM IRP 结构，即使它已调用 WdfObjectReference。此要求扩展到通过调用 WDFREQUEST 上的方法（如 WdfRequestRetrieveOutputBuffer 或 WdfRequestRetrieveInputBuffer）来访问关联的 WDM IRP 结构。

在驱动程序调用 WdfRequestComplete 后，如果驱动程序提供了一个，框架会为请求调用驱动程序的 EvtCleanupCallback 函数。

驱动程序可以调用 WdfRequestCompleteWithInformation 或 WdfRequestCompleteWithPriorityBoost，而不是调用 WdfRequestComplete。有关详细信息，请参阅 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
标头	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) 、 MdlAfterReqCompleted IoctlA (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)