EvtIoWdmIrpForForwardProgress function

[Applies to KMDF only]

A driver's EvtIoWdmIrpForForwardProgress callback function examines an I/O request packet (IRP) and determines whether to use a reserved request object to process the I/O request or to fail the I/O request.

Syntax


EVT_WDF_IO_WDM_IRP_FOR_FORWARD_PROGRESS EvtIoWdmIrpForForwardProgress;

WDF_IO_FORWARD_PROGRESS_ACTION EvtIoWdmIrpForForwardProgress(
  _In_  WDFQUEUE Queue,
  _In_  PIRP Irp
)
{ ... }

Parameters

Queue [in]

A handle to an I/O queue object.

Irp [in]

A pointer to an IRP structure.

Return value

The EvtIoWdmIrpForForwardProgress callback function must return a WDF_IO_FORWARD_PROGRESS_ACTION-typed value.

Remarks

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

If your driver registers an EvtIoWdmIrpForForwardProgress callback function, the framework calls the function if all of the following conditions exist:

  • The framework has received a I/O request packet (IRP) that the I/O manager is sending to the driver.

  • The framework has attempted to create a request object for the IRP, but the attempt failed.

  • The driver has enabled guaranteed forward progress for the I/O queue that should receive the request object, with the policy type set to WdfIoForwardProgressReservedPolicyUseExamine.

The framework passes the IRP to the EvtIoWdmIrpForForwardProgress callback function. The callback function must examine the IRP and determine whether the framework should use one of its reserved request objects for the IRP or (if the IRP is not important when the computer's available memory is low) fail the I/O request without delivering it to the driver. The callback function's return value specifies the action that the framework should take.

For more information about the EvtIoWdmIrpForForwardProgress 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 EvtIoWdmIrpForForwardProgress 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 EvtIoWdmIrpForForwardProgress callback function that is named MyIoForwardExamineIrpForForwardProgress, use the EVT_WDF_IO_WDM_IRP_FOR_FORWARD_PROGRESS type as shown in this code example:


EVT_WDF_IO_WDM_IRP_FOR_FORWARD_PROGRESS  MyIoWdmIrpForForwardProgress;

Then, implement your callback function as follows:


_Use_decl_annotations_
WDF_IO_FORWARD_PROGRESS_ACTION
 MyIoWdmIrpForForwardProgress(
    WDFQUEUE  Queue,
    PIRP  Irp
    )
  {...}

The EVT_WDF_IO_WDM_IRP_FOR_FORWARD_PROGRESS function type is defined in the Wdfinterrupt.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_WDM_IRP_FOR_FORWARD_PROGRESS 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

EvtIoAllocateRequestResources
EvtIoAllocateResourcesForReservedRequest

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft