IO_WORKITEM_ROUTINE_EX callback function (wdm.h)

Artikel
02/28/2023

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

Syntax

IO_WORKITEM_ROUTINE_EX IoWorkitemRoutineEx;

void IoWorkitemRoutineEx(
  [in]           PVOID IoObject,
  [in, optional] PVOID Context,
  [in]           PIO_WORKITEM IoWorkItem
)
{...}

Parameters

[in] IoObject

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 or IoTryQueueWorkItem 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 IoQueueWorkItemEx or IoTryQueueWorkItem when the work item was queued.

[in] IoWorkItem

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

Return value

None

Remarks

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

The driver queues a WorkItemEx routine by calling IoQueueWorkItemEx or IoTryQueueWorkItem, 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.

Examples

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:

IO_WORKITEM_ROUTINE_EX MyWorkItemEx;

Then, implement your callback routine as follows:

_Use_decl_annotations_
VOID
  MyWorkItemEx(
    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.

Requirements

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

Delen via