EVT_WDF_IO_ALLOCATE_RESOURCES_FOR_RESERVED_REQUEST callback function (wdfio.h)

Article
10/21/2021

[Applies to KMDF only]

A driver's EvtIoAllocateResourcesForReservedRequest callback function allocates request-specific resources that the driver can use to process an I/O request in the future. The framework is pre-allocating the specified request object for future use in low-memory situations.

Syntax

EVT_WDF_IO_ALLOCATE_RESOURCES_FOR_RESERVED_REQUEST EvtWdfIoAllocateResourcesForReservedRequest;

NTSTATUS EvtWdfIoAllocateResourcesForReservedRequest(
  [in] WDFQUEUE Queue,
  [in] WDFREQUEST Request
)
{...}

Parameters

[in] Queue

A handle to an I/O queue object.

[in] Request

A handle to a request object that the framework has created for use during future low-memory situations.

Return value

The EvtIoAllocateResourcesForReservedRequest callback function must return STATUS_SUCCESS or another status value for which NT_SUCCESS(status) equals TRUE if the function encounters no errors. Otherwise, this function must return a status value for which NT_SUCCESS(status) equals FALSE.

Remarks

A driver can register an EvtIoAllocateResourcesForReservedRequest callback function when it calls WdfIoQueueAssignForwardProgressPolicy.

If your driver registers an EvtIoAllocateResourcesForReservedRequest callback function, the framework calls the function immediately after it creates a request object that it reserves for low-memory situations.

The callback function can allocate resources that your driver will require to process a request later, if the framework uses the reserved request because of a low-memory situation.

To allocate memory for request-specific resources, an EvtIoAllocateResourcesForReservedRequest callback function might call WdfObjectAllocateContext, specifying the request object handle that the Request parameter specifies.

Alternatively or additionally, your driver might call WdfDeviceInitSetRequestAttributes before calling WdfDeviceCreate. As a result, the framework will allocate context space for each reserved request object when it creates the object.

If your driver allocates object context space for reserved request objects, the driver must reinitialize the context space when it completes an I/O request that uses a reserved request object. The framework does not reinitialize the context space of reserved request objects after use.

If your driver calls WdfDeviceInitSetRequestAttributes and specifies an EvtCleanupCallback or EvtDestroyCallback callback function for its request objects, the framework calls these callback functions for its reserved request objects only when it deletes the associated I/O queues.

The driver's request handlers can call WdfRequestIsReserved to determine if reserved request objects are being used.

For more information about how to use object context space, see Framework Object Context Space.

If the callback function successfully allocates resources, it should return STATUS_SUCCESS.

If a resource allocation error occurs, such as a low memory situation, the callback function must return an error status value. In this case, the framework stops allocating reserved request objects and uses the callback function's return value as the return value for WdfIoQueueAssignForwardProgressPolicy.

For more information about the EvtIoAllocateResourcesForReservedRequest callback function, see Guaranteeing Forward Progress of I/O Operations.

Requirements

Requirement	Value
Target Platform	Universal
Minimum KMDF version	1.9
Header	wdfio.h (include Wdf.h)
IRQL	<=DISPATCH_LEVEL