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。 否则,此方法可能会返回以下值之一:
返回代码 | 描述 |
---|---|
|
提供了无效参数。 |
|
工作项对象的父对象不是设备对象或设备对象的上级。 |
|
系统资源不足,无法创建工作项对象。 |
|
Config 参数指向 WDF_WORKITEM_CONFIG 结构中的 AutomaticSerialization 成员 TRUE,但父对象的执行级别不是 WdfExecutionLevelPassive。 |
|
属性 参数 NULL,或者 属性 指定的 WDF_OBJECT_ATTRIBUTES 结构的 ParentObject 成员 NULL。 |
驱动程序调用 WdfWorkItemCreate 创建工作项后,它通常会将特定于项的信息存储在工作项对象的上下文内存中。 驱动程序的 EvtWorkItem 回调函数(执行工作项的任务)可以访问此信息以确定它必须执行的任务。 (有关在上下文内存中存储信息的详细信息,请参阅 Framework 对象上下文空间。)
存储工作项信息后,驱动程序必须调用 WdfWorkItemEnqueue,才能将工作项添加到系统的工作项队列。 当系统工作线程可用时,线程将从队列中删除工作项,并调用 EvtWorkItem 回调函数。
当驱动程序创建工作项对象时,它必须为 WDF_OBJECT_ATTRIBUTES 结构的 ParentObject 成员中的工作项对象指定父对象。 父对象必须是框架设备对象,或者是其父级链导致框架设备对象的任何对象。 框架在删除设备对象时将删除工作项对象。
若要更早删除工作项对象,驱动程序可以调用 WdfObjectDelete,如 Using Framework Work Items中所述。
驱动程序可以通过调用 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) |
库 | Wdf01000.sys(KMDF):WUDFx02000.dll (UMDF) |
IRQL | <= DISPATCH_LEVEL |
DDI 符合性规则 | DriverCreate(kmdf),KmdfIrql(kmdf),KmdfIrql2(kmdf),KmdfIrqlExplicit(kmdf) |