WdfWorkItemCreate function (wdfworkitem.h)
[Applies to KMDF and UMDF]
The WdfWorkItemCreate method creates a framework work-item object, which can subsequently be added to the system's work-item queue.
Syntax
NTSTATUS WdfWorkItemCreate(
[in] PWDF_WORKITEM_CONFIG Config,
[in] PWDF_OBJECT_ATTRIBUTES Attributes,
[out] WDFWORKITEM *WorkItem
);
Parameters
[in] Config
A pointer to a caller-allocated WDF_WORKITEM_CONFIG structure that the driver must have already initialized by calling WDF_WORKITEM_CONFIG_INIT.
[in] Attributes
A pointer to a caller-allocated WDF_OBJECT_ATTRIBUTES structure that specifies attributes for the work-item object.
[out] WorkItem
A pointer to a variable that receives a handle to the new work-item object.
Return value
WdfWorkItemCreate returns STATUS_SUCCESS if the operation succeeds. Otherwise, this method might return one of the following values:
| Return code | Description |
|---|---|
|
An invalid parameter was supplied. |
|
The work-item object's parent is not a device object or the ancestor of a device object. |
|
There were insufficient system resources to create a work-item object. |
|
The AutomaticSerialization member in the WDF_WORKITEM_CONFIG structure that the Config parameter points to is TRUE, but the parent object's execution level is not WdfExecutionLevelPassive. |
|
The Attributes parameter was NULL, or the ParentObject member of the WDF_OBJECT_ATTRIBUTES structure that Attributes specifies was NULL. |
Remarks
After a driver calls WdfWorkItemCreate to create a work item, it typically stores item-specific information in the context memory of the work-item object. The driver's EvtWorkItem callback function, which performs the work item's tasks, can access this information to determine the tasks that it must perform. (For more information about storing information in the context memory, see Framework Object Context Space.)
After storing work-item information, the driver must call WdfWorkItemEnqueue to add the work item to the system's work-item queue. When a system worker thread becomes available, the thread removes the work item from the queue and calls the EvtWorkItem callback function.
When the driver creates a work-item object, it must specify a parent object for the work-item object in the ParentObject member of the WDF_OBJECT_ATTRIBUTES structure. The parent object must be a framework device object or any object whose chain of parents leads to a framework device object. The framework will delete the work-item object when it deletes the device object.
To delete the work-item object earlier, the driver can call WdfObjectDelete, as described in Using Framework Work Items.
The driver can retrieve a work item's parent object by calling WdfWorkItemGetParentObject.
If your driver provides EvtCleanupCallback or EvtDestroyCallback callback functions for the work-item object, note that the framework calls these callback functions at IRQL = PASSIVE_LEVEL.
For more information about work items, see Using Framework Work Items.
Examples
The following code example initializes a WDF_OBJECT_ATTRIBUTES structure, initializes a WDF_WORKITEM_CONFIG structure, and calls WdfWorkItemCreate.
NTSTATUS status = STATUS_SUCCESS;
PWORKER_ITEM_CONTEXT context;
WDF_OBJECT_ATTRIBUTES attributes;
WDF_WORKITEM_CONFIG workitemConfig;
WDFWORKITEM hWorkItem;
WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE(
&attributes,
WORKER_ITEM_CONTEXT
);
attributes.ParentObject = FdoData->WdfDevice;
WDF_WORKITEM_CONFIG_INIT(
&workitemConfig,
CallbackFunction
);
status = WdfWorkItemCreate(
&workitemConfig,
&attributes,
&hWorkItem
);
if (!NT_SUCCESS(status)) {
return status;
}
Requirements
| Requirement | Value |
|---|---|
| Target Platform | Universal |
| Minimum KMDF version | 1.0 |
| Minimum UMDF version | 2.0 |
| Header | wdfworkitem.h (include Wdf.h) |
| Library | Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF) |
| IRQL | <= DISPATCH_LEVEL |
| DDI compliance rules | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf) |