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
属性 参数 NULL,或者 属性 指定的 WDF_OBJECT_ATTRIBUTES 结构的 ParentObject 成员 NULL

言论

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

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

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

若要更早删除工作项对象,驱动程序可以调用 WdfObjectDelete,如 Using Framework Work Items中所述。

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

如果驱动程序为工作项对象提供 EvtCleanupCallbackEvtDestroyCallback 回调函数,请注意框架在 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