WdfRequestCompleteWithInformation function (wdfrequest.h)

Article
04/18/2022

[Applies to KMDF and UMDF]

The WdfRequestCompleteWithInformation method stores completion information and then completes a specified I/O request with a supplied completion status.

Syntax

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

Parameters

[in] Request

A handle to the request object.

[in] Status

An NTSTATUS value that represents the completion status of the request. Valid status values include, but are not limited to, the following:

STATUS_SUCCESS

The driver successfully completed the request.

STATUS_CANCELLED

The driver canceled the request.

STATUS_UNSUCCESSFUL

The driver encountered an error while processing the request.

[in] Information

A ULONG_PTR that is set to a request-dependent value. For example, on successful completion of a transfer request, this is set to the number of bytes transferred. This field is not extensible by the driver.

Return value

None

Remarks

A bug check occurs if the driver supplies an invalid object handle.

For read, write and IOCTL requests, it is necessary for the driver to call WdfRequestCompleteWithInformation

For a non-data transfer request, calling WdfRequestComplete instead is an option.

Calling WdfRequestCompleteWithInformation is equivalent to calling WdfRequestSetInformation and then calling WdfRequestComplete.

After a call to WdfRequestCompleteWithInformation returns, the request handle is no longer valid unless the driver has called WdfObjectReference to add one or more additional reference counts to the request object. Note that after WdfRequestCompleteWithInformation returns, the driver must not attempt to access the associated WDM IRP structure, even if it has called WdfObjectReference.

When your driver calls WdfRequestCompleteWithInformation, the framework supplies a default value that the system uses to boost the run-time priority of the thread that requested the I/O operation. For information about default priority boost values, see Specifying Priority Boosts When Completing I/O Requests. Your driver can call WdfRequestCompleteWithPriorityBoost to override the default priority boost value.

For more information about calling WdfRequestCompleteWithInformation, see Completing I/O Requests.

For a code example that shows how to use WdfRequestCompleteWithInformation to retrieve the number of bytes copied, see the VirtualSerial2 driver sample.

Examples

The following code example shows how a driver for a USB device might call WdfRequestCompleteWithInformation in a CompletionRoutine callback function .

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;
}

Requirements

Requirement	Value
Target Platform	Universal
Minimum KMDF version	1.0
Minimum UMDF version	2.0
Header	wdfrequest.h (include Wdf.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
DDI compliance rules	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)