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:

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

See also

WdfWorkItemEnqueue