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

Статья
08/08/2023

[Применимо к 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	Параметр Attributes имеет значение NULL, или элемент ParentObjectструктуры WDF_OBJECT_ATTRIBUTES , указанной атрибутами , имеет значение NULL.

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

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

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

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

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

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

Дополнительные сведения о рабочих элементах см. в разделе Использование рабочих элементов платформы.

Примеры

В следующем примере кода выполняется инициализация структуры 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 (включая Wdf.h)
Библиотека	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<= DISPATCH_LEVEL
Правила соответствия DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

См. также раздел

WdfWorkItemEnqueue

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