Функция WdfWorkItemCreate (wdfworkitem.h)

Статья
02/07/2025

[Применимо к KMDF и UMDF]

Метод WdfWorkItemCreate создает объект рабочего элемента платформы, который впоследствии можно добавить в очередь рабочих элементов системы.

Синтаксис

NTSTATUS WdfWorkItemCreate(
  [in]  PWDF_WORKITEM_CONFIG   Config,
  [in]  PWDF_OBJECT_ATTRIBUTES Attributes,
  [out] WDFWORKITEM            *WorkItem
);

Параметры

[in] Config

Указатель на структуру, выделенную вызывающим объектом WDF_WORKITEM_CONFIG, которую драйвер должен инициализировать путем вызова WDF_WORKITEM_CONFIG_INIT.

[in] Attributes

Указатель на структуру, выделенную вызывающим объектом, WDF_OBJECT_ATTRIBUTES, которая задает атрибуты для объекта рабочего элемента.

[out] WorkItem

Указатель на переменную, которая получает дескриптор к новому объекту рабочего элемента.

Возвращаемое значение

WdfWorkItemCreate возвращает STATUS_SUCCESS, если операция выполнена успешно. В противном случае этот метод может вернуть одно из следующих значений:

Возвращаемый код	Описание
STATUS_INVALID_PARAMETER	Указан недопустимый параметр.
STATUS_INVALID_DEVICE_REQUEST	Родительский объект рабочего элемента не является объектом устройства или предком объекта устройства.
STATUS_INSUFFICIENT_RESOURCES	Для создания объекта рабочего элемента недостаточно системных ресурсов.
STATUS_WDF_INCOMPATIBLE_EXECUTION_LEVEL	Элемент AutomaticSerialization в структуре WDF_WORKITEM_CONFIG, на которую указывает параметр Config, TRUE, но уровень выполнения родительского объекта не WdfExecutionLevelPassive.
STATUS_WDF_PARENT_NOT_SPECIFIED	Параметр атрибутов был NULLили элемент ParentObject структуры WDF_OBJECT_ATTRIBUTES, которая атрибутов null.

Замечания

Когда драйвер вызывает WdfWorkItemCreate для создания рабочего элемента, обычно он сохраняет сведения, относящиеся к элементам, в памяти контекста объекта рабочего элемента. Функция обратного вызова драйвера EvtWorkItem, которая выполняет задачи рабочего элемента, может получить доступ к этой информации, чтобы определить задачи, которые он должен выполнять. (Дополнительные сведения о хранении сведений в памяти контекста см. в разделе Контекстное пространство объектов Платформы.)

После хранения сведений о рабочем элементе драйвер должен вызвать WdfWorkItemEnqueue, чтобы добавить рабочий элемент в очередь рабочих элементов системы. Когда рабочий поток системы становится доступным, поток удаляет рабочий элемент из очереди и вызывает функцию обратного вызова EvtWorkItem.

При создании объекта рабочего элемента драйвер должен указать родительский объект для объекта рабочего элемента в элементе ParentObject структуры WDF_OBJECT_ATTRIBUTES. Родительский объект должен быть объектом устройства платформы или любым объектом, цепочка родителей которого приводит к объекту устройства платформы. Платформа удаляет объект рабочего элемента при удалении объекта устройства.

Чтобы удалить объект рабочего элемента ранее, драйвер может вызвать WdfObjectDelete, как описано в Using Framework Work Items.

Драйвер может получить родительский объект рабочего элемента, вызвав WdfWorkItemGetParentObject.

Если драйвер предоставляет EvtCleanupCallback или EvtDeqlCallback функции обратного вызова для объекта рабочего элемента, обратите внимание, что платформа вызывает эти функции обратного вызова в IRQL = PASSIVE_LEVEL.

Дополнительные сведения о рабочих элементах см. в разделе Using Framework Work Items.

Примеры

Следующий пример кода инициализирует структуру WDF_OBJECT_ATTRIBUTES, инициализирует структуру WDF_WORKITEM_CONFIG и вызывает 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;
}

Требования

Требование	Ценность
целевая платформа	Всеобщий
минимальная версия KMDF	1.0
минимальная версия UMDF	2.0
заголовка	wdfworkitem.h (include Wdf.h)
библиотеки	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<= DISPATCH_LEVEL
правил соответствия DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

См. также

WdfWorkItemEnqueue

Поделиться через