EVT_WDF_IO_QUEUE_IO_STOP funzione di callback (wdfio.h)

Articolo
08/08/2023

[Si applica a KMDF e UMDF]

La funzione di callback dell'evento EvtIoStop di un driver viene completata, riqueue o sospende l'elaborazione di una richiesta specificata perché la coda di I/O della richiesta viene arrestata.

Sintassi

EVT_WDF_IO_QUEUE_IO_STOP EvtWdfIoQueueIoStop;

void EvtWdfIoQueueIoStop(
  [in] WDFQUEUE Queue,
  [in] WDFREQUEST Request,
  [in] ULONG ActionFlags
)
{...}

Parametri

[in] Queue

Handle per l'oggetto coda del framework associato alla richiesta di I/O.

[in] Request

Handle per un oggetto richiesta framework.

[in] ActionFlags

Or bit per bit di uno o più flag tipizzato WDF_REQUEST_STOP_ACTION_FLAGS che identificano il motivo per cui viene chiamata la funzione di callback e se la richiesta è annullabile.

Valore restituito

nessuno

Osservazioni

Un driver registra una funzione di callback EvtIoStop quando chiama WdfIoQueueCreate. Per altre informazioni sulla chiamata a WdfIoQueueCreate, vedere Creazione di code di I/O.

Se un driver registra una funzione di callback EvtIoStop per una coda di I/O, il framework lo chiama quando il dispositivo sottostante della coda lascia lo stato di lavoro (D0). Il framework chiama la funzione di callback EvtIoStop per ogni richiesta di I/O che il driver non è stato completato, incluse le richieste che il driver possiede e quelli che ha inoltrato a una destinazione di I/O.

Nella maggior parte dei casi, la funzione di callback EvtIoStopviene completata, annulla o rimanda ulteriormente l'elaborazione della richiesta di I/O.

In genere, il driver esegue una delle operazioni seguenti:

Se il driver possiede la richiesta di I/O, chiama WdfRequestUnmarkCancelable (se la richiesta è annullabile) e chiama WdfRequestStopAcknowledge con un valore Requeue true oppure chiama WdfRequestComplete con un valore di stato di completamento di STATUS_SUCCESS o STATUS_CANCELLED.
Prima di poter chiamare i metodi WdfRequestXxx in modo sicuro, il driver deve assicurarsi che l'implementazione di EvtIoStop abbia accesso esclusivo alla richiesta.

A tale scopo, il driver deve sincronizzare l'accesso alla richiesta per impedire ad altri thread di modificare la richiesta simultaneamente. Il metodo di sincronizzazione scelto dipenderà dalla progettazione del driver.

Ad esempio, se la richiesta viene mantenuta in un'area di contesto condivisa, il callback EvtIoStop potrebbe acquisire un blocco driver interno, rimuovere la richiesta dal contesto condiviso e quindi rilasciare il blocco. A questo punto, il callback EvtIoStop possiede la richiesta e può completare o ripetere la richiesta in modo sicuro.

In alternativa, il driver rinvia ulteriormente l'elaborazione della richiesta e chiama WdfRequestStopAcknowledge con un valore Requeue di FALSE.
Se il driver ha inoltrato la richiesta di I/O a una destinazione di I/O, può chiamare WdfRequestCancelSentRequest per tentare di annullare la richiesta.
In alternativa, se il driver ha inoltrato la richiesta di I/O a un driver di livello inferiore nello stack di driver e il framework chiama il callback EvtIoStop del driver con un valore ActionFlags di WdfRequestStopActionSuspend, il driver può chiamare WdfRequestStopStopAcknowledge con un valore Requeue di FALSE. Prima di procedere, il driver deve verificare che siano soddisfatte le condizioni seguenti:
- Il driver inferiore interrompe l'elaborazione di tutte le richieste di I/O in sospeso in risposta alla ricezione di un'IRP (Dx) del set di dispositivi.
- La funzione di callback completamento del driver può completare le richieste mentre il dispositivo è in stato di bassa potenza.

Un driver potrebbe scegliere di non eseguire alcuna azione in EvtIoStop per le richieste che sono garantite di completare in un piccolo periodo di tempo.

In questo caso, il framework attende fino al completamento della richiesta specificata prima di spostare il dispositivo (o il sistema) in uno stato di alimentazione inferiore o rimuovendo il dispositivo. Potenzialmente, questa inazione può impedire a un sistema di immettere lo stato di ibernazione o un altro stato di alimentazione di sistema basso. In casi estremi, può causare l'arresto anomalo del sistema con il codice di controllo bug 9F.

Se il flag WdfRequestStopRequestCancelable è impostato nel parametro ActionFlags , il driver deve chiamare WdfRequestUnmarkCancelable prima di chiamare WdfRequestComplete per completare (o annullare) la richiesta o WdfRequestStopAcknowledge per ripetere la richiesta.

Se il driver inoltra una richiesta di I/O da uno dei gestori delle richieste e specifica il flag di WDF_REQUEST_SEND_OPTION_SEND_AND_FORGET nella struttura di WDF_REQUEST_SEND_OPTIONS della richiesta, il framework non chiama la funzione di callback evtIoStop del driver per questa richiesta. Tuttavia, se il driver inoltra la stessa richiesta di I/O da un altro thread, il framework potrebbe chiamare EvtIoStop per questa richiesta.

Per altre informazioni sulla funzione di callback EvtIoStop , vedere Uso di Power-Managed code di I/O.

Questa funzione di callback può essere chiamata in IRQL <= DISPATCH_LEVEL, a meno che il membro ExecutionLevel della struttura di WDF_OBJECT_ATTRIBUTES del dispositivo o del driver sia impostato su WdfExecutionLevelPassive.

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Versione KMDF minima	1.0
Versione UMDF minima	2,0
Intestazione	wdfio.h (includere Wdf.h)
IRQL	<= DISPATCH_LEVEL (vedere sezione Osservazioni)