Edit

EVT_WDF_IO_ALLOCATE_REQUEST_RESOURCES callback function (wdfio.h)

  • Article

[Applies to KMDF only]

A driver's EvtIoAllocateRequestResources callback function allocates request-specific resources that the driver requires to process the specified request.

Syntax

EVT_WDF_IO_ALLOCATE_REQUEST_RESOURCES EvtWdfIoAllocateRequestResources;

NTSTATUS EvtWdfIoAllocateRequestResources(
  [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. The framework has not yet added the request object to the I/O queue that the Queue parameter's handle specifies.

Return value

The EvtIoAllocateRequestResources 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 EvtIoAllocateRequestResources callback function when it calls WdfIoQueueAssignForwardProgressPolicy.

If your driver registers an EvtIoAllocateRequestResources callback function, the framework calls the function immediately after it creates a request object for an I/O request packet (IRP) that the I/O manager has sent to your driver.

The callback function can allocate resources that your driver will require to process the request later, after the driver has obtained the request object from the I/O queue that the Queue parameter's handle specifies.

If the callback function successfully allocates resources and returns STATUS_SUCCESS, the framework will eventually deliver the request object to the driver.

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 follows the driver's forward progress policy, which the driver previously specified with a WDF_IO_FORWARD_PROGRESS_RESERVED_POLICY value when it called WdfIoQueueAssignForwardProgressPolicy.

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

This callback function can be called at IRQL <= DISPATCH_LEVEL. If the IRQL is PASSIVE_LEVEL, the framework calls the callback function within a critical region.

Requirements

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

See also

EvtIoAllocateResourcesForReservedRequest

WdfIoQueueAssignForwardProgressPolicy