Función WdfRequestStopAcknowledge (wdfrequest.h)
[Se aplica a KMDF y UMDF]
El método WdfRequestStopAcknowledge informa al marco de trabajo que el controlador ha detenido el procesamiento de una solicitud de E/S especificada.
Sintaxis
void WdfRequestStopAcknowledge(
[in] WDFREQUEST Request,
[in] BOOLEAN Requeue
);
Parámetros
[in] Request
Identificador de un objeto de solicitud de marco.
[in] Requeue
Valor booleano que, si es TRUE, hace que el marco vuelva a poner la solicitud en la cola para que el marco lo vuelva a entregar al controlador. Si es FALSE, el marco no vuelve a poner en cola la solicitud. Para obtener más información, vea la sección Comentarios que se muestra más adelante.
Valor devuelto
None
Observaciones
Se produce una comprobación de errores si el controlador proporciona un identificador de objeto no válido.
Si un controlador registra una función de devolución de llamada EvtIoStop para una cola de E/S, el marco lo llama cuando el dispositivo subyacente de la cola deja su estado de funcionamiento (D0). El marco llama a la función de devolución de llamada EvtIoStop para cada solicitud de E/S que el controlador no ha completado, incluidas las solicitudes que posee el controlador y las que ha reenviado a un destino de E/S. El controlador debe completar, cancelar o posponer el procesamiento de cada solicitud realizando una de las siguientes acciones:
- Si el controlador posee la solicitud, puede llamar a WdfRequestComplete para completar o cancelar la solicitud.
- Si el controlador ha reenviado la solicitud a un destino de E/S, puede llamar a WdfRequestCancelSentRequest para intentar cancelar la solicitud.
- Si el controlador pospone el procesamiento de la solicitud, debe llamar a WdfRequestStopAcknowledge.
El marco de trabajo no permite que el dispositivo deje su estado de trabajo (D0) hasta que el controlador haya completado, cancelado o pospuesto todas las solicitudes que recibe una función de devolución de llamada EvtIoStop . Potencialmente, esta inacción puede impedir que un sistema entre en su estado de hibernación u otro estado de energía del sistema bajo.
Cuando la función de devolución de llamada EvtIoStop de un controlador llama a WdfRequestStopAcknowledge, puede establecer el parámetro Requeue en TRUE o FALSE:
-
Al establecer Requeue en TRUE , el marco vuelve a colocar la solicitud en su cola de E/S.
Cuando el dispositivo subyacente vuelve a su estado de trabajo (D0), el marco volverá a entregar la solicitud al controlador.
-
Al establecer Requeue en FALSE , el marco no vuelve a poner en cola la solicitud. Si el controlador posee la solicitud, la propiedad permanece con el controlador. Si el controlador ha reenviado la solicitud, el controlador es responsable de controlar la solicitud cuando se completa. El controlador debe dejar de realizar cualquier procesamiento de E/S que requiera acceso de hardware.
Cuando el dispositivo subyacente vuelve a su estado de trabajo (D0), el marco llamará a la función de devolución de llamada EvtIoResume del controlador para que el controlador pueda continuar procesando la solicitud.
Antes de llamar a WdfRequestStopAcknowledge, la función de devolución de llamada EvtIoStop del controlador debe detener todo el procesamiento de la solicitud de E/S que requiere acceso al dispositivo subyacente, ya que el dispositivo está a punto de entrar en un estado de baja energía.
Para obtener más información sobre el método WdfRequestStopAcknowledge , vea Uso de Power-Managed colas de E/S.
Ejemplos
Si un controlador llama a WdfRequestStopAcknowledge con Requeue establecido en TRUE, debe llamar previamente a WdfRequestUnmarkCancelable.
El ejemplo de código siguiente es una función de devolución de llamada EvtIoStop que comprueba si se puede cancelar una solicitud recibida y, si es así, llama a WdfRequestUnmarkCancelable. Si WdfRequestUnmarkCancelable devuelve STATUS_CANCELLED, el ejemplo simplemente devuelve porque la función de devolución de llamada EvtRequestCancel del controlador controlará la solicitud. De lo contrario, el ejemplo llama a WdfRequestStopAcknowledge y especifica TRUE para que el marco vuelva a poner en cola la solicitud cuando el dispositivo subyacente vuelva a su estado de trabajo (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);
}
Normalmente, si un controlador llama a WdfRequestStopAcknowledge con Requeue establecido en FALSE, deja la solicitud cancelable.
El siguiente ejemplo de código es una función de devolución de llamada EvtIoStop que llama a WdfRequestStopAcknowledge y especifica FALSE para que el marco llame finalmente a la función de devolución de llamada EvtIoResume del controlador, donde el controlador reanuda el procesamiento de la solicitud.
Puede usar código como este si es aceptable detener el procesamiento de una solicitud específica y continuar más adelante, en lugar de volver a entregar la solicitud y reiniciar el procesamiento desde el principio.
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);
}
Requisitos
| Requisito | Value |
|---|---|
| Plataforma de destino | Universal |
| Versión mínima de KMDF | 1.0 |
| Versión mínima de UMDF | 2.0 |
| Encabezado | wdfrequest.h (incluya Wdf.h) |
| Library | Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF) |
| IRQL | <=DISPATCH_LEVEL |
| Reglas de cumplimiento de DDI | DeferredRequestCompleted(kmdf), DriverCreate(kmdf), EvtIoStopCancel(kmdf), EvtIoStopCompleteOrStopAck(kmdf), EvtIoStopResume(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestCompleted(kmdf), RequestCompletedLocal(kmdf), StopAckWithinEvtIoStop(kmdf) |