WdfRequestComplete method

[Applies to KMDF and UMDF]

The WdfRequestComplete method completes a specified I/O request and supplies a completion status.

Syntax


VOID WdfRequestComplete(
  [in]  WDFREQUEST Request,
  [in]  NTSTATUS Status
);

Parameters

Request [in]

A handle to the framework request object that represents the I/O request that is being completed.

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 is successfully completing the request.
STATUS_CANCELLED: The driver is canceling the request.
STATUS_UNSUCCESSFUL: The driver has encountered an error while processing the request.

Return value

None.

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

Remarks

After a driver calls WdfRequestComplete, higher-level drivers on the driver stack can call WdfRequestGetStatus to obtain the completion status value that was specified for the Status parameter. Typically, drivers call WdfRequestGetStatus from within a CompletionRoutine callback function.

After a call to WdfRequestComplete 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 WdfRequestComplete returns, the driver must not attempt to access the associated WDM IRP structure, even if it has called WdfObjectReference.

Instead of calling WdfRequestComplete, the driver can call WdfRequestCompleteWithInformation or WdfRequestCompleteWithPriorityBoost.

When your driver calls WdfRequestComplete, 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 WdfRequestComplete, see Completing I/O Requests.

Examples

The following code example is a section of a request handler. The request handler accepts only read and write requests, and it completes a each request with an error status if the request type is not read or write.


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

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