EVT_WDF_REQUEST_COMPLETION_ROUTINE callback function (wdfrequest.h)

Article
10/21/2021

[Applies to KMDF and UMDF]

A driver's CompletionRoutine event callback function executes when another driver completes a specified I/O request.

Syntax

EVT_WDF_REQUEST_COMPLETION_ROUTINE EvtWdfRequestCompletionRoutine;

void EvtWdfRequestCompletionRoutine(
  [in] WDFREQUEST Request,
  [in] WDFIOTARGET Target,
  [in] PWDF_REQUEST_COMPLETION_PARAMS Params,
  [in] WDFCONTEXT Context
)
{...}

Parameters

[in] Request

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

[in] Target

A handle to an I/O target object that represents the I/O target that completed the request.

[in] Params

A pointer to a WDF_REQUEST_COMPLETION_PARAMS structure that contains information about the completed request. See note below regarding validity of the completion parameters.

[in] Context

Driver-supplied context information, which the driver specified in a previous call to WdfRequestSetCompletionRoutine.

Return value

None

Remarks

To register a CompletionRoutine callback function for an I/O request, a driver must call WdfRequestSetCompletionRoutine. For more information about this callback function, see Completing I/O Requests.

The completion parameters structure is fully populated with valid information only if the driver formatted the request by calling one of the following:

WdfIoTargetFormatXxx methods, for example WdfIoTargetFormatRequestForRead
WdfUsbTargetDeviceFormatRequestForXxx methods, for example WdfUsbTargetDeviceFormatRequestForString
WdfUsbTargetPipeFormatRequestForXxx methods, for example WdfUsbTargetPipeFormatRequestForWrite

If the driver formatted the request using either WdfRequestFormatRequestUsingCurrentType or WdfRequestWdmFormatUsingStackLocation, only the IoStatus field in the completion parameters structure is valid.

A KMDF driver's CompletionRoutine can run at IRQL <= DISPATCH_LEVEL regardless of the ExecutionLevel specified in the WDF_OBJECT_ATTRIBUTES structure for the I/O request object.

Examples

The function type is declared in Wdfrequest.h, as follows.

typedef VOID
  (EVT_WDF_REQUEST_COMPLETION_ROUTINE)(
    IN WDFREQUEST  Request,
    IN WDFIOTARGET  Target,
    IN PWDF_REQUEST_COMPLETION_PARAMS  Params,
    IN WDFCONTEXT  Context
    );

To define a CompletionRoutine callback function that is named MyCompletionRoutine, you must first provide a function declaration that SDV and other verification tools require, as follows:

EVT_WDF_REQUEST_COMPLETION_ROUTINE  MyCompletionRoutine;

Then, implement your callback function as follows:

VOID
 MyCompletionRoutine (
    IN WDFREQUEST  Request,
    IN WDFIOTARGET  Target,
    IN PWDF_REQUEST_COMPLETION_PARAMS  Params,
    IN WDFCONTEXT  Context
    )
  {...}

Requirements

Requirement	Value
Target Platform	Universal
Minimum KMDF version	1.0
Minimum UMDF version	2.0
Header	wdfrequest.h (include Wdf.h)
IRQL	<=DISPATCH_LEVEL

Share via