WdfRequestCompleteWithInformation 函数 (wdfrequest.h)

2023-08-08

[适用于 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。例如，成功完成传输请求后，此值设置为传输的字节数。驱动程序无法扩展此字段。

返回值

无

备注

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

对于读取、写入和 IOCTL 请求，驱动程序必须调用 WdfRequestCompleteWithInformation

对于非数据传输请求，调用 WdfRequestComplete 是一个选项。

调用 WdfRequestCompleteWithInformation 等效于调用 WdfRequestSetInformation ，然后调用 WdfRequestComplete。

调用 WdfRequestCompleteWithInformation 后返回，请求句柄不再有效，除非驱动程序已调用 WdfObjectReference 向请求对象添加一个或多个其他引用计数。请注意， 在 WdfRequestCompleteWithInformation 返回后，驱动程序不得尝试访问关联的 WDM IRP 结构，即使它已调用 WdfObjectReference。

当驱动程序调用 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
标头	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)