Funzione WdfRequestStopAcknowledge (wdfrequest.h)
[Si applica a KMDF e UMDF]
Il metodo WdfRequestStopAcknowledge informa il framework che il driver ha interrotto l'elaborazione di una richiesta di I/O specificata.
Sintassi
void WdfRequestStopAcknowledge(
[in] WDFREQUEST Request,
[in] BOOLEAN Requeue
);
Parametri
[in] Request
Handle per un oggetto richiesta framework.
[in] Requeue
Valore booleano che, se TRUE, causa la riquequezione della richiesta nella coda in modo che il framework lo distribuirà di nuovo al driver. Se FALSE, il framework non esegue nuovamente la richiesta. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.
Valore restituito
nessuno
Osservazioni
Un controllo di bug si verifica se il driver fornisce un handle di oggetti non valido.
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. Il driver deve completare, annullare o rinviare l'elaborazione di ogni richiesta eseguendo una delle operazioni seguenti:
- Se il driver possiede la richiesta, può chiamare WdfRequestComplete per completare o annullare la richiesta.
- Se il driver ha inoltrato la richiesta a una destinazione di I/O, può chiamare WdfRequestCancelSentRequest per tentare di annullare la richiesta.
- Se il driver rimanda l'elaborazione della richiesta, deve chiamare WdfRequestStopAcknowledge.
Il framework non consente al dispositivo di lasciare lo stato di lavoro (D0) fino a quando il driver non è stato completato, annullato o posticipato ogni richiesta ricevuta da una funzione di callback EvtIoStop . Potenzialmente, questa inazione può impedire a un sistema di immettere lo stato di ibernazione o un altro stato di alimentazione di sistema basso.
Quando la funzione di callback EvtIoStop di un driver chiama WdfRequestStopAcknowledge, può impostare il parametro Requeue su TRUE o FALSE:
-
L'impostazione di Requeue su TRUE determina che il framework inserisca nuovamente la richiesta nella coda di I/O.
Quando il dispositivo sottostante torna allo stato funzionante (D0), il framework ridistribuirà la richiesta al driver.
-
L'impostazione di Requeue su FALSE causa la ripetizione della richiesta da parte del framework. Se il driver possiede la richiesta, la proprietà rimane con il driver. Se il driver ha inoltrato la richiesta, il driver è responsabile della gestione della richiesta al termine della richiesta. Il driver deve interrompere l'esecuzione di qualsiasi elaborazione di I/O che richiede l'accesso hardware.
Quando il dispositivo sottostante torna allo stato di lavoro (D0), il framework chiamerà la funzione di callback evtIoResume del driver, in modo che il driver possa continuare a elaborare la richiesta.
Prima di chiamare WdfRequestStopAcknowledge, la funzione di callback EvtIoStop del driver deve arrestare tutte le elaborazioni della richiesta di I/O che richiede l'accesso al dispositivo sottostante, perché il dispositivo sta per immettere uno stato di bassa potenza.
Per altre informazioni sul metodo WdfRequestStopAcknowledge , vedere Uso di Power-Managed code di I/O.
Esempio
Se un driver chiama WdfRequestStopAcknowledge con Requeue impostato su TRUE, deve in precedenza chiamare WdfRequestUnmarkCancelable.
L'esempio di codice seguente è una funzione di callback EvtIoStop che verifica se una richiesta ricevuta è annullabile e, se è, chiama WdfRequestUnmarkCancelable. Se WdfRequestUnmarkCancelable restituisce STATUS_CANCELLED, l'esempio restituisce solo perché la funzione di callback EvtRequestCancel del driver gestirà la richiesta. In caso contrario, l'esempio chiama WdfRequestStopAcknowledge e specifica TRUE in modo che il framework requeue la richiesta quando il dispositivo sottostante torna allo stato di lavoro (D0).
VOID
MyEvtIoStop(
IN WDFQUEUE Queue,
IN WDFREQUEST Request,
IN ULONG ActionFlags
)
{
NTSTATUS status;
// TODO: Take steps here to suspend and, if necessary, roll back any processing that has already occurred on this request
if (ActionFlags & WdfRequestStopRequestCancelable) {
status = WdfRequestUnmarkCancelable(Request);
if (status == STATUS_CANCELLED) {
return;
}
}
// Inform framework that driver is postponing processing, cause framework to redeliver request when device returns to D0
WdfRequestStopAcknowledge(Request, TRUE);
}
In genere, se un driver chiama WdfRequestStopAcknowledge con Requeue impostato su FALSE, lascia la richiesta annullabile.
L'esempio di codice seguente è una funzione di callback EvtIoStop che chiama WdfRequestStopAcknowledge e specifica FALSE in modo che il framework chiami infine la funzione di callback EvtIoResume del driver, in cui il driver riprende l'elaborazione della richiesta.
È possibile usare il codice come questo se è accettabile interrompere l'elaborazione di una richiesta specifica e continuare in un secondo momento, anziché avere la richiesta ridistribuibile e riavviare l'elaborazione dall'inizio.
VOID
MyEvtIoStop(
IN WDFQUEUE Queue,
IN WDFREQUEST Request,
IN ULONG ActionFlags
)
{
//TODO: Take steps here to suspend processing of the request so it can be resumed when power returns
// Acknowledge the stop, but leave the request under driver's ownership.
// Provide a corresponding EvtIoResume handler to resume processing when power returns
WdfRequestStopAcknowledge(Request, FALSE);
}
Requisiti
| Requisito | Valore |
|---|---|
| Piattaforma di destinazione | Universale |
| Versione KMDF minima | 1.0 |
| Versione UMDF minima | 2,0 |
| Intestazione | wdfrequest.h (include Wdf.h) |
| Libreria | Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF) |
| IRQL | <=DISPATCH_LEVEL |
| Regole di conformità DDI | DeferredRequestCompleted(kmdf), DriverCreate(kmdf), EvtIoStopCancel(kmdf), EvtIoStopCompleteOrStopAck(kmdf), EvtIoStopResume(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestCompleted(kmdf), RequestCompletedLocal(kmdf), StopAckWithinEvtIoStop(kmdf) |