IO_WORKITEM_ROUTINE callback function (wdm.h)

Article
02/22/2024

A WorkItem routine performs the processing for a work item that was queued by the IoQueueWorkItem routine.

Syntax

IO_WORKITEM_ROUTINE IoWorkitemRoutine;

void IoWorkitemRoutine(
  [in]           PDEVICE_OBJECT DeviceObject,
  [in, optional] PVOID Context
)
{...}

Parameters

[in] DeviceObject

Pointer to one of the caller's device objects. This is the pointer that was passed as the DeviceObject parameter to IoAllocateWorkItem when the work item was allocated, or as the IoObject parameter to IoInitializeWorkItem when the work item was initialized.

[in, optional] Context

Specifies driver-specific context information. This is the value that was passed as the Context parameter to IoQueueWorkItem when the work item was queued.

Return value

None

Remarks

The driver queues a WorkItem routine by calling IoQueueWorkItem, and a system worker thread subsequently executes the routine. A WorkItem routine must run for a limited amount of time; otherwise, the system can deadlock. For more information, see System Worker Threads.

A WorkItem routine runs at IRQL = PASSIVE_LEVEL and in a system thread context.

Examples

To define a WorkItem callback routine, you must first provide a function declaration that identifies the type of callback routine 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 a WorkItem callback routine that is named MyWorkItem, use the IO_WORKITEM_ROUTINE type as shown in this code example:

IO_WORKITEM_ROUTINE MyWorkItem;

Then, implement your callback routine as follows:

_Use_decl_annotations_
VOID
  MyWorkItem(
    PDEVICE_OBJECT  DeviceObject,
    PVOID  Context 
    )
  {
      // Function body
  }

The IO_WORKITEM_ROUTINE function type is defined in the Wdm.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 IO_WORKITEM_ROUTINE 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 WDM Drivers. For information about _Use_decl_annotations_, see Annotating Function Behavior.

Requirements

Requirement	Value
Target Platform	Desktop
Header	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
IRQL	Called at PASSIVE_LEVEL.

Share via