Export (0) Print
Expand All
This topic has not yet been rated - Rate this topic

WorkItemEx routine

A WorkItemEx routine performs the processing for a work item that was queued by the IoQueueWorkItemEx routine.



VOID WorkItemEx(
  _In_      PVOID IoObject,
  _In_opt_  PVOID Context,
  _In_      PIO_WORKITEM IoWorkItem
{ ... }


IoObject [in]

Pointer to the caller's driver object or 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.

Context [in, optional]

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

IoWorkItem [in]

Pointer to the IO_WORKITEM structure for the work item. This is the pointer that was passed as the IoWorkItem parameter to IoQueueWorkItemEx.

Return value



Drivers can implement WorkItemEx routines only on Windows Vista and later versions of Windows.

The driver queues a WorkItemEx routine by calling IoQueueWorkItemEx, and a system worker thread subsequently executes the routine. For more information, see System Worker Threads.

A WorkItemEx routine must run for a limited amount of time; otherwise, the system can deadlock. For more information, see System Worker Threads.

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


To define a WorkItemEx 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 WorkItemEx callback routine that is named MyWorkItemEx, use the IO_WORKITEM_ROUTINE_EX type as shown in this code example:


Then, implement your callback routine as follows:

    PVOID  IoObject,
    PVOID  Context,
    PIO_WORKITEM  IoWorkItem 
      // Function body

The IO_WORKITEM_ROUTINE_EX 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_EX 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.



Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)



See also




Send comments about this topic to Microsoft

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
© 2014 Microsoft. All rights reserved.