EvtIoAllocateRequestResources function

[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 EvtIoAllocateRequestResources;

NTSTATUS EvtIoAllocateRequestResources(
  _In_  WDFQUEUE Queue,
  _In_  WDFREQUEST Request
)
{ ... }

Parameters

Queue [in]

A handle to an I/O queue object.

Request [in]

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.

Examples

To define an EvtIoAllocateRequestResources callback function, you must first provide a function declaration that identifies the type of callback function you’re defining. Windows provides a set of callback function types for drivers. Declaring a function using the callback function types helps Code Analysis for Drivers, Static Driver Verifier (SDV), and other verification tools find errors, and it’s a requirement for writing drivers for the Windows operating system.

For example, to define an EvtIoAllocateRequestResources callback function that is named MyIoAllocateRequestResources, use the EVT_WDF_IO_ALLOCATE_REQUEST_RESOURCES type as shown in this code example:


EVT_WDF_IO_ALLOCATE_REQUEST_RESOURCES  MyIoAllocateRequestResources;

Then, implement your callback function as follows:


_Use_decl_annotations_
NTSTATUS
 MyIoAllocateRequestResources (
    WDFQUEUE  Queue,
    WDFREQUEST  Request
    )
  {...}

The EVT_WDF_IO_ALLOCATE_REQUEST_RESOURCES function type is defined in the Wdfio.h header file. To more accurately identify errors when you run the code analysis tools, be sure to add the _Use_decl_annotations_ annotation to your function definition. The _Use_decl_annotations_ annotation ensures that the annotations that are applied to the EVT_WDF_IO_ALLOCATE_REQUEST_RESOURCES function type in the header file are used. For more information about the requirements for function declarations, see Declaring Functions by Using Function Role Types for KMDF Drivers. For information about _Use_decl_annotations_, see Annotating Function Behavior.

Requirements

Minimum KMDF version

1.9

Header

Wdfio.h (include Wdf.h)

IRQL

<=DISPATCH_LEVEL (see Remarks section)

See also

EvtIoAllocateResourcesForReservedRequest
WdfIoQueueAssignForwardProgressPolicy

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft. All rights reserved.