共用方式為

WdfWorkItemEnqueue 函式 （wdfworkitem.h）

  • 發行項

[適用於 KMDF 和 UMDF]

WdfWorkItemEnqueue 方法會將指定的架構工作項目物件新增至系統的工作專案佇列。

語法

void WdfWorkItemEnqueue(
  [in] WDFWORKITEM WorkItem
);

參數

[in] WorkItem

從先前呼叫 WdfWorkItemCreate取得之架構工作項目物件的句柄。

傳回值

沒有

言論

如果驅動程式提供無效的物件句柄，就會發生錯誤檢查。

驅動程式呼叫 WdfWorkItemCreate 以建立工作項目之後，驅動程式必須呼叫 WdfWorkItemEnqueue，將工作專案新增至系統的工作專案佇列。 系統背景工作線程隨後會從佇列中移除工作專案，並呼叫工作專案的 EvtWorkItem 回呼函式。 系統會依新增至佇列的順序移除工作專案。

驅動程式呼叫 WdfWorkItemEnqueue之前，通常會使用工作專案對象的內容記憶體來儲存工作專案的相關信息。 EvtWorkItem 回呼函式會使用此資訊來判斷它必須執行的作業。

若為 KMDF 1.7 版和更新版本，如果您的驅動程式重複使用其工作項目物件，則驅動程式可以在系統背景工作線程取消佇列工作專案之前，針對相同的工作專案再次呼叫 WdfWorkItemEnqueue，然後呼叫驅動程式的 EvtWorkItem 回呼函式。 不過，如果工作項目已經存在，KMDF 將不會將工作專案新增至佇列。 因此，您的 EvtWorkItem 回呼函式每次呼叫時，都必須處理所有已排入佇列的工作。

您的驅動程式也可以呼叫 WdfWorkItemEnqueue，而 EvtWorkItem 回呼函式正在執行，以將另一個工作專案排入佇列。 第二個工作專案的 EvtWorkItem 回呼甚至可能在第一個工作完成之前執行。

在 1.7 版之前的 KMDF 版本中，如果您的驅動程式重複使用其工作項目物件，則必須先取消佇列工作專案，並呼叫其 EvtWorkItem 回呼函式，才能再次呼叫相同的工作專案 WdfWorkItem。

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

例子

本節包含兩個範例。 第一個範例示範如何將工作專案新增至 KMDF 1.7 版和更新版本的佇列。 第二個範例示範如何將工作專案新增至 1.7 版之前的 KMDF 版本佇列

範例 1：KMDF 1.7 版和更新版本

下列程式代碼範例會呼叫傳回工作專案對象內容記憶體指標的本機例程。 此範例會設定物件內容記憶體中的資訊，然後呼叫 WdfWorkItemEnqueue。 驅動程式的 EvtWorkItem 回呼函式稍後會從工作項目物件擷取資訊。

PMY_CONTEXT_TYPE context;

context = GetWorkItemContext(hWorkItem);
context->FdoData = FdoData;
context->Argument1 = Context1;
context->Argument2 = Context2;

WdfWorkItemEnqueue(hWorkItem);

驅動程式 EvtWorkItem 回呼函式包含下列程序代碼。

MyWorkItemCallback (
    IN WDFWORKITEM hWorkItem
    )
{
    PMY_CONTEXT_TYPE context;

    context = GetWorkItemContext(hWorkItem);

    //
    // Do work here.
    //
    ...
    //
    return;
}

範例 2：1.7 之前的 KMDF 版本

下列程式代碼範例會呼叫傳回工作專案對象內容記憶體指標的本機例程。 此範例會設定物件內容記憶體中的資訊、將狀態變數設定為 「busy」，然後呼叫 WdfWorkItemEnqueue。 驅動程式的 EvtWorkItem 回呼函式稍後會從工作項目物件擷取資訊。

typedef enum _WORKITEM_STATE {
    WORKITEM_STATE_FREE =0,
    WORKITEM_STATE_BUSY = 1
} WORKITEM_STATE;
...
PMY_CONTEXT_TYPE context;

context = GetWorkItemContext(hWorkItem);
context->FdoData = FdoData;
context->Argument1 = Context1;
context->Argument2 = Context2;

if (InterlockedCompareExchange(
                               (PLONG)&context->WorkItemState,
                               WORKITEM_STATE_BUSY,
                               WORKITEM_STATE_FREE
                               ) == WORKITEM_STATE_FREE) {
 WdfWorkItemEnqueue(hWorkItem);
}

驅動程式 EvtWorkItem 回呼函式包含下列程序代碼。 就在 傳回 語句之前，程式代碼會將工作專案物件的狀態變數設定為「free」，讓驅動程式可以再次將物件排入佇列。

MyWorkItemCallback (
    IN WDFWORKITEM hWorkItem
    )
{
    PMY_CONTEXT_TYPE context;
    LONG result;

    context = GetWorkItemContext(hWorkItem);

    //
    // Do work here.
    //
    ...
    //
    // Reset object state.
    //
    result = InterlockedExchange(
                                 (PLONG)&context->WorkItemState,
                                 WORKITEM_STATE_FREE
                                 );
    ASSERT(result == WORKITEM_STATE_BUSY);
    return;
}

要求

要求 價值
目標平臺 普遍
最低 KMDF 版本 1.0
最低 UMDF 版本 2.0
標頭 wdfworkitem.h （包括 Wdf.h）
連結庫 Wdf01000.sys （KMDF）：WUDFx02000.dll （UMDF）
IRQL <= DISPATCH_LEVEL
DDI 合規性規則 DeferredRequestCompleted（kmdf），DriverCreate（kmdf），KmdfIrql（kmdf），KmdfIrql2（kmdf），KmdfIrqlExplicit（kmdf），RequestCompleted（kmdf），RequestCompletedLocal（kmdf）

另請參閱

EvtWorkItem

InterlockedCompareExchange

InterlockedExchange

WdfWorkItemCreate