WdfWorkItemCreate 函数 (wdfworkitem.h)

  • 项目

[适用于 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
 Config 参数指向的 WDF_WORKITEM_CONFIG 结构中的 AutomaticSerialization 成员为 TRUE，但父对象的执行级别不是 WdfExecutionLevelPassive。
STATUS_WDF_PARENT_NOT_SPECIFIED
 Attributes 参数为 NULL，或者 Attributes 指定的WDF_OBJECT_ATTRIBUTES结构的 ParentObject 成员为 NULL。

注解

驱动程序调用 WdfWorkItemCreate 创建工作项后，通常会将特定于项的信息存储在工作项对象的上下文内存中。 驱动程序的 EvtWorkItem 回调函数执行工作项的任务，可以访问此信息来确定它必须执行的任务。 (有关在上下文内存中存储信息的详细信息，请参阅 框架对象上下文 Space.)

存储工作项信息后，驱动程序必须调用 WdfWorkItemEnqueue 以将工作项添加到系统的工作项队列。 当系统工作线程变为可用时，该线程将从队列中删除工作项并调用 EvtWorkItem 回调函数。

当驱动程序创建工作项对象时，它必须为WDF_OBJECT_ATTRIBUTES结构的 ParentObject 成员中的工作项对象指定父对象。 父对象必须是框架设备对象或其父级链导致框架设备对象的任何对象。 框架在删除设备对象时将删除工作项对象。

若要删除之前的工作项对象，驱动程序可以调用 WdfObjectDelete，如 使用框架工作项中所述。

驱动程序可以通过调用 WdfWorkItemGetParentObject 来检索工作项的父对象。

如果驱动程序为工作项对象提供 EvtCleanupCallback 或 EvtDestroyCallback 回调函数，请注意，框架在 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)
Library Wdf01000.sys (KMDF) ;WUDFx02000.dll (UMDF)
IRQL <= DISPATCH_LEVEL
DDI 符合性规则 DriverCreate (kmdf) 、 KmdfIrql (kmdf) 、 KmdfIrql2 (kmdf) 、 KmdfIrqlExplicit (kmdf)

另请参阅

WdfWorkItemEnqueue