WdfRequestComplete function (wdfrequest.h)

Article
09/12/2022

[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

[in] Request

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

[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 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

Remarks

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

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. This requirement extends to accessing the associated WDM IRP structure by calling methods on the WDFREQUEST, like WdfRequestRetrieveOutputBuffer or WdfRequestRetrieveInputBuffer.

After a driver calls WdfRequestComplete, the framework calls the driver's EvtCleanupCallback function for the request, if the driver has supplied one.

Instead of calling WdfRequestComplete, the driver can call WdfRequestCompleteWithInformation or WdfRequestCompleteWithPriorityBoost. See the Remarks of WdfRequestCompleteWithInformation for more information.

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

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)

Share via