Función WdfRequestStopAcknowledge (wdfrequest.h)

Artículo
08/08/2023

[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.

Si el controlador llama a WdfRequestStopAcknowledge, debe llamar a este método desde su función de devolución de llamada EvtIoStop .

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.

Si el controlador había llamado previamente a WdfRequestMarkCancelable o WdfRequestMarkCancelableEx, debe llamar a WdfRequestUnmarkCancelable antes de llamar a WdfRequestStopAcknowledge con Requeue establecido en TRUE.

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)

Consulte también

EvtIoStop

EvtRequestCancel

WdfRequestComplete

Compartir a través de