共用方式為

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 結構 ParentObj ect 成員 NULL。

言論

驅動程式呼叫 WdfWorkItemCreate 建立工作項目之後，通常會將專案特定資訊儲存在工作專案對象的內容記憶體中。 驅動程式的 EvtWorkItem 回呼函式可執行工作專案的工作，可以存取這項資訊，以判斷其必須執行的工作。 （如需將資訊儲存在內容記憶體的詳細資訊，請參閱 Framework 物件內容空間。

儲存工作專案資訊之後，驅動程式必須呼叫 WdfWorkItemEnqueue，將工作專案新增至系統的工作專案佇列。 當系統背景工作線程變成可用時，線程會從佇列中移除工作專案，並呼叫 EvtWorkItem 回呼函式。

當驅動程式建立工作項目物件時，它必須在 ParentObject 中指定工作專案物件的父物件，WDF_OBJECT_ATTRIBUTES 結構的成員。 父對象必須是架構裝置物件，或是父系鏈結導致架構裝置物件的任何物件。 架構會在刪除裝置物件時刪除工作項目物件。

若要刪除稍早的工作專案對象，驅動程式可以呼叫 WdfObjectDelete，如 使用 Framework 工作專案中所述。

驅動程式可以呼叫 WdfWorkItemGetParentObject來擷取工作專案的父物件。

如果您的驅動程式提供 EvtCleanupCallback 或 EvtDestroyCallback 工作項目物件的回呼函式，請注意架構會在 IRQL = PASSIVE_LEVEL 呼叫這些回呼函式。

如需工作項目的詳細資訊，請參閱使用 Framework 工作專案 。

例子

下列程式代碼範例會初始化 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