WdfRequestReuse function

Description

[Applies to KMDF and UMDF]

The WdfRequestReuse method reinitializes a framework request object so that it can be reused.

Parameters

Request [in]

A handle to a framework request object.

ReuseParams [in]

A pointer to a caller-allocated WDF_REQUEST_REUSE_PARAMS structure.

Return value

WdfRequestReuse returns STATUS_SUCCESS if the operation succeeds. Otherwise, this method might return one of the following values:

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

Remarks

A framework-based driver can reuse framework request objects that it created by previous calls to WdfRequestCreate or WdfRequestCreateFromIrp. Drivers can also reuse request objects that they have received from the framework, but they cannot set the WDF_REQUEST_REUSE_SET_NEW_IRP flag for those request objects.

[!NOTE] Drivers should use caution when reusing request objects received from the framework. Reusing such a request resets the cancel flag of the underlying IRP and may prevent a calling driver from cancelling the request.

A driver can reuse a request object after the original request has been completed. After a driver has called WdfRequestReuse, the request's contents must be reinitialized. The driver can specify some request parameters in the WDF_REQUEST_REUSE_PARAMS structure.

If you want the reused request to have a CompletionRoutine callback function, the driver must call WdfRequestSetCompletionRoutine after calling WdfRequestReuse.

For more information about WdfRequestReuse, see Reusing Framework Request Objects.

Examples

The following code example is part of a CompletionRoutine callback function that calls WdfRequestReuse so that the driver can reuse a driver-allocated request.

VOID
MyRequestCompletionRoutine(
    IN WDFREQUEST  Request,
    IN WDFIOTARGET  Target,
    PWDF_REQUEST_COMPLETION_PARAMS  CompletionParams,
    IN WDFCONTEXT  Context
    )
{
    WDF_REQUEST_REUSE_PARAMS  params;
    NTSTATUS  status;
...
    WDF_REQUEST_REUSE_PARAMS_INIT(
                                  &params,
                                  WDF_REQUEST_REUSE_NO_FLAGS,
                                  STATUS_SUCCESS
                                  );

    status = WdfRequestReuse(
                             Request,
                             &params
                             );
    ASSERT(NT_SUCCESS(status));
...
}

See also

CompletionRoutine

WDF_REQUEST_REUSE_PARAMS

WDF_REQUEST_REUSE_PARAMS_INIT

WdfRequestCreate

WdfRequestCreateFromIrp

WdfRequestSetCompletionRoutine