WdfRequestReuse function (wdfrequest.h)

Article
04/18/2022

[Applies to KMDF and UMDF]

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

Syntax

NTSTATUS WdfRequestReuse(
  [in] WDFREQUEST                Request,
  [in] PWDF_REQUEST_REUSE_PARAMS ReuseParams
);

Parameters

[in] Request

A handle to a framework request object.

[in] ReuseParams

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:

Return code	Description
STATUS_INVALID_PARAMETER	An input parameter is invalid.
STATUS_WDF_REQUEST_INVALID_STATE	The driver supplied an IRP in the WDF_REQUEST_REUSE_PARAMS structure, but the specified request object was not obtained from WdfRequestCreateFromIrp.

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

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	DriverCreate(kmdf), InvalidReqAccess(kmdf), InvalidReqAccessLocal(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), ReqSendFail(kmdf)

Share via