NdisAllocateIoWorkItem function (ndis.h)

Article
04/18/2022

NDIS drivers call the NdisAllocateIoWorkItem function to allocate a work item. For more information, see NDIS I/O Work Items.

Syntax

NDIS_HANDLE NdisAllocateIoWorkItem(
  [in] NDIS_HANDLE NdisObjectHandle
);

Parameters

[in] NdisObjectHandle

The handle of an NDIS object that is associated with a device object or driver object.

Return value

If NdisAllocateIoWorkItem successfully allocates a work item, it returns a handle to the work item. If it fails, NdisAllocateIoWorkItem returns NULL.

Remarks

NDIS miniport drivers pass NdisAllocateIoWorkItem either of two handles: the adapter handle that NDIS passed to the MiniportInitializeEx function or the miniport driver handle that NDIS returned when the miniport driver called NdisMRegisterMiniportDriver.

NDIS filter drivers can pass NdisAllocateIoWorkItem the filter driver handle that NDIS returned when the filter driver called NdisFRegisterFilterDriver.

NDIS miniport drivers and filter drivers can also pass NdisAllocateIoWorkItem the NDIS device handle that NDIS returned when the driver called NdisRegisterDeviceEx. NdisAllocateIoWorkItem gets the device object or driver object that is associated with the handle and passes the device object or driver object to the IoAllocateWorkItem function.

Note Protocol drivers cannot use NdisAllocateIoWorkItem because NDIS does not associate protocol drivers with device objects or driver objects.

NDIS drivers call the NdisQueueIoWorkItem function to queue work items. After a driver calls NdisQueueIoWorkItem, NDIS calls the driver-specified callback function at IRQL = PASSIVE_LEVEL. This can improve system performance by allowing the current function to end immediately and the driver to do work later at a lower IRQL.

NDIS drivers must call the NdisFreeIoWorkItem function to free the resources associated with a work item that NdisAllocateIoWorkItem allocated.

Drivers can call NdisFreeIoWorkItem in the callback routine that is passed to NdisQueueIoWorkItem.

If a miniport driver used the handle that NDIS passed to MiniportInitializeEx when it called NdisAllocateIoWorkItem, the work item must be freed before or in the call to the drivers MiniportHaltEx function.

If a miniport driver used the handle that NdisMRegisterMiniportDriver returned when the driver called NdisAllocateIoWorkItem, the driver must free the work item before the driver unloads.

In general, a driver must free the work item before the driver unloads.

Requirements

Requirement	Value
Minimum supported client	Supported in NDIS 6.0 and later.
Target Platform	Universal
Header	ndis.h (include Ndis.h)
Library	Ndis.lib
IRQL	<= DISPATCH_LEVEL
DDI compliance rules	Init_NdisAllocateIoWorkItem(ndis), Irql_Miscellaneous_Function(ndis)