WdfRequestCompleteWithInformation method

[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

C++


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

Parameters

Request [in]

A handle to the request object.

Status [in]

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.

Information [in]

Driver-defined completion status information for the request, such as the number of bytes that were transferred.

Return value

None.

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

Remarks

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.

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

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, BufAfterReqCompletedIntIoctlA, BufAfterReqCompletedIoctl, BufAfterReqCompletedIoctlA, BufAfterReqCompletedRead, BufAfterReqCompletedReadA, BufAfterReqCompletedWrite, BufAfterReqCompletedWriteA, CompleteCanceledReq, DeferredRequestCompleted, DoubleCompletion, DoubleCompletionLocal, DriverCreate, EvtIoStopCancel, EvtIoStopCompleteOrStopAck, EvtSurpriseRemoveNoRequestComplete, InvalidReqAccess, KmdfIrql, KmdfIrql2, MarkCancOnCancReqLocal, MdlAfterReqCompletedIntIoctl, MdlAfterReqCompletedIntIoctlA, MdlAfterReqCompletedIoctl, MdlAfterReqCompletedIoctlA, MdlAfterReqCompletedRead, MdlAfterReqCompletedReadA, MdlAfterReqCompletedWrite, MdlAfterReqCompletedWriteA, MemAfterReqCompletedIntIoctl, MemAfterReqCompletedIntIoctlA, MemAfterReqCompletedIoctl, MemAfterReqCompletedIoctlA, MemAfterReqCompletedRead, MemAfterReqCompletedReadA, MemAfterReqCompletedWrite, MemAfterReqCompletedWriteA, NoCancelFromEvtSurpriseRemove, ReqDelete, ReqIsCancOnCancReq, ReqNotCanceledLocal, ReqSendFail, RequestCompleted, RequestCompletedLocal