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 WdfWorkItemCreare.
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 degli elementi di lavoro del sistema. Un thread di lavoro di sistema rimuove successivamente l'elemento di lavoro dalla coda e chiama la evtWorkItem funzione di callback 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 dell'elemento di lavoro per archiviare informazioni sull'elemento di lavoro. La EvtWorkItem funzione di callback usa queste informazioni per determinare l'operazione che deve eseguire.
Per le versioni 1.7 e successive di KMDF, se il driver riutilizza i relativi oggetti elemento di lavoro, il driver può chiamare WdfWorkItemEnqueue di nuovo 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, l'EvtWorkItem funzione di callback 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 secondo elemento di lavoro EvtWorkItem callback potrebbe essere eseguito anche prima del completamento della prima.
Nelle versioni di KMDF precedenti alla versione 1.7, se il driver riutilizza gli oggetti elemento di lavoro, non deve chiamare WdfWorkItemEnqueue di nuovo per lo stesso elemento di lavoro finché un thread di lavoro di sistema non ha dequeuato l'elemento di lavoro e chiamato il relativo EvtWorkItem funzione di callback.
Per altre informazioni sugli elementi di lavoro, vedere Using Framework Work Items.
Esempi
Questa sezione contiene due esempi. Il primo esempio mostra come aggiungere elementi di lavoro a una coda per KMDF versioni 1.7 e successive. Il secondo esempio mostra come aggiungere elementi di lavoro a una coda per le versioni kmDF precedenti alla versione 1.7
esempio 1: KMDF versioni 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. Il driver EvtWorkItem funzione di callback recupererà successivamente 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);
Il driver EvtWorkItem funzione di callback contiene il codice seguente.
MyWorkItemCallback (
IN WDFWORKITEM hWorkItem
)
{
PMY_CONTEXT_TYPE context;
context = GetWorkItemContext(hWorkItem);
//
// Do work here.
//
...
//
return;
}
esempio 2: versioni di 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. Il driver EvtWorkItem funzione di callback recupererà successivamente 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);
}
Il driver EvtWorkItem funzione di callback contiene il codice seguente. Poco prima che il restituisca istruzione, 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;
}
Fabbisogno
| Requisito | Valore |
|---|---|
| piattaforma di destinazione | Universale |
| versione minima di KMDF | 1.0 |
| versione minima di UMDF | 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) |