WdfRequestCompleteWithInformation 函数 (wdfrequest.h)

[适用于 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
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) MdlAfterReqCompleted IoctlA (kmdf) MdlAfterReqCompletedRead (kmdf) MdlAfterReqCompletedReadA (kmdf ) , MdlAfterReqCompletedWrite) (, 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) RequestComplet (ed) 、RequestCompletedLocal (kmdf)

另请参阅

CompletionRoutine

WDF_REQUEST_COMPLETION_PARAMS

WDF_USB_REQUEST_COMPLETION_PARAMS

WdfObjectReference

WdfRequestComplete

WdfRequestCompleteWithPriorityBoost

WdfRequestSetInformation