WdfWorkItemEnqueue 函式 (wdfworkitem.h)

  • 發行項

[適用於 KMDF 和 UMDF]

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

語法

void WdfWorkItemEnqueue(
  [in] WDFWORKITEM WorkItem
);

參數

[in] WorkItem

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

傳回值

無

備註

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

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

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

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

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

在 1.7 版之前的 KMDF 版本中，如果您的驅動程式重複使用其工作項目物件，則它不得針對相同的工作專案再次呼叫 WdfWorkItemEnqueue ，直到系統背景工作線程取消佇列工作專案並呼叫其 EvtWorkItem 回呼函式為止。

如需工作專案的詳細資訊，請參閱 使用 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 版本

下列程式代碼範例會呼叫傳回工作專案對象內容記憶體指標的本機例程。 此範例會設定對象內容記憶體中的資訊、將狀態變數設定為 「忙碌」，然後呼叫 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 回呼函式包含下列程式代碼。 在 return 語句之前，程式代碼會將工作專案物件的狀態變數設定為 「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;
}

規格需求

需求 值
目標平台 Universal
最小 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 () ， KmdfIrqlExplicit (kmdf) ， RequestCompleted (kmdf) 、RequestCompletedLocal (kmdf)

另請參閱

EvtWorkItem

InterlockedCompareExchange

InterlockedExchange

WdfWorkItemCreate