Funzione WdfWorkItemEnqueue (wdfworkitem.h)

[Si applica a KMDF e UMDF]

Il metodo WdfWorkItemEnqueue aggiunge un oggetto elemento di lavoro del framework specificato alla coda dell'elemento di lavoro del sistema.

Sintassi

void WdfWorkItemEnqueue(
  [in] WDFWORKITEM WorkItem
);

Parametri

[in] WorkItem

Handle per un oggetto elemento di lavoro del framework ottenuto da una chiamata precedente a WdfWorkItemCreate.

Valore restituito

nessuno

Osservazioni

Se il driver fornisce un handle di oggetto non valido, si verifica un controllo di bug.

Dopo che il driver chiama WdfWorkItemCreate per creare un elemento di lavoro, il driver deve chiamare WdfWorkItemEnqueue per aggiungere l'elemento di lavoro alla coda dell'elemento di lavoro del sistema. Un thread di lavoro di sistema rimuove successivamente l'elemento di lavoro dalla coda e chiama la funzione di callback EvtWorkItem dell'elemento di lavoro. Il sistema rimuove gli elementi di lavoro nell'ordine in cui sono stati aggiunti alla coda.

Prima che i driver chiamino WdfWorkItemEnqueue, in genere usano la memoria di contesto dell'oggetto elemento di lavoro per archiviare informazioni sull'elemento di lavoro. La funzione di callback EvtWorkItem usa queste informazioni per determinare l'operazione che deve eseguire.

Per le versioni 1.7 e successive di KMDF, se il driver riutilizza gli oggetti elemento di lavoro, il driver può chiamare nuovamente WdfWorkItemEnqueue per lo stesso elemento di lavoro prima che un thread di lavoro di sistema abbia dequeuato l'elemento di lavoro e successivamente chiamato la funzione di callback EvtWorkItem del driver. Tuttavia, KMDF non aggiungerà l'elemento di lavoro alla coda, se è già presente. Pertanto, la funzione di callback EvtWorkItem deve elaborare tutto il lavoro in coda ogni volta che viene chiamato.

Il driver può anche chiamare WdfWorkItemEnqueue mentre è in esecuzione una funzione di callback EvtWorkItem per accodare un altro elemento di lavoro. Il callback EvtWorkItem del secondo elemento di lavoro potrebbe essere eseguito anche prima del completamento della prima.

Nelle versioni di KMDF precedenti alla versione 1.7, se il driver riutilizza i relativi oggetti elemento di lavoro, non deve chiamare nuovamente WdfWorkItemEnqueue per lo stesso elemento di lavoro finché un thread di lavoro di sistema non ha dequeuato l'elemento di lavoro e chiamato la relativa funzione di callback EvtWorkItem .

Per altre informazioni sugli elementi di lavoro, vedere Using Framework Work Items.For more information about work items, see Using Framework Work Items.

Esempio

Questa sezione contiene due esempi. Il primo esempio illustra come aggiungere elementi di lavoro a una coda per KMDF versioni 1.7 e successive. Il secondo esempio illustra come aggiungere elementi di lavoro a una coda per le versioni kmDF precedenti alla versione 1.7

Esempio 1: KMDF versione 1.7 e successive

Nell'esempio di codice seguente viene chiamata una routine locale che restituisce un puntatore alla memoria di contesto di un oggetto elemento di lavoro. L'esempio imposta le informazioni nella memoria del contesto dell'oggetto e quindi chiama WdfWorkItemEnqueue. La funzione di callback EvtWorkItem del driver recupera le informazioni dall'oggetto elemento di lavoro.

PMY_CONTEXT_TYPE context;

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

WdfWorkItemEnqueue(hWorkItem);

La funzione di callback EvtWorkItem del driver contiene il codice seguente.

MyWorkItemCallback (
    IN WDFWORKITEM hWorkItem
    )
{
    PMY_CONTEXT_TYPE context;

    context = GetWorkItemContext(hWorkItem);

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

Esempio 2: versioni kmdf precedenti alla 1.7

Nell'esempio di codice seguente viene chiamata una routine locale che restituisce un puntatore alla memoria di contesto di un oggetto elemento di lavoro. L'esempio imposta le informazioni nella memoria del contesto dell'oggetto, imposta una variabile di stato su "occupato" e quindi chiama WdfWorkItemEnqueue. La funzione di callback EvtWorkItem del driver recupera le informazioni dall'oggetto elemento di lavoro.

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);
}

La funzione di callback EvtWorkItem del driver contiene il codice seguente. Subito prima dell'istruzione return , il codice imposta la variabile di stato dell'oggetto dell'elemento di lavoro su "libera" in modo che il driver possa accodare nuovamente l'oggetto.

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;
}

Requisiti

   
Piattaforma di destinazione Universale
Versione KMDF minima 1,0
Versione UMDF minima 2,0
Intestazione wdfworkitem.h (include Wdf.h)
Libreria Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL <= DISPATCH_LEVEL
Regole di conformità DDI DeferredRequestCompleted(kmdf), DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestCompleted(kmdf), RequestCompletedLocal(kmdf)

Vedi anche

EvtWorkItem

InterlockedCompareExchange

InterlockedExchange

WdfWorkItemCreate