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。 否則，這個方法可能會傳回下列其中一個值：

傳回碼 Description
STATUS_INVALID_PARAMETER
 提供無效的參數。
STATUS_INVALID_DEVICE_REQUEST
 工作項目物件的父代不是裝置物件或裝置物件的上階。
STATUS_INSUFFICIENT_RESOURCES
 系統資源不足，無法建立工作項目物件。
STATUS_WDF_INCOMPATIBLE_EXECUTION_LEVEL
 WDF_WORKITEM_CONFIG結構中 Config 參數指向的 AutomaticSerialization 成員為 TRUE，但父對象的執行層級不是 WdfExecutionLevelPassive。
STATUS_WDF_PARENT_NOT_SPECIFIED
 Attributes 參數為 NULL，或是 Attributes 所指定之WDF_OBJECT_ATTRIBUTES結構的 ParentObject 成員為 NULL。

備註

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

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

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

若要稍早刪除工作專案對象，驅動程式可以呼叫 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;
}

規格需求

需求 值
目標平台 Universal
最低 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