Función WdfIoTargetPurge (wdfiotarget.h)

Artículo
08/08/2023

[Se aplica a KMDF y UMDF]

El método WdfIoTargetPurge cancela todas las solicitudes de E/S en cola a un destino de E/S local, remoto o especializado y evita que se ponen en cola todas las solicitudes de E/S nuevas. El método también intenta cancelar las solicitudes de E/S que han dejado la cola del destino de E/S y han entrado en controladores inferiores.

Sintaxis

void WdfIoTargetPurge(
  [in] WDFIOTARGET                   IoTarget,
  [in] WDF_IO_TARGET_PURGE_IO_ACTION Action
);

Parámetros

[in] IoTarget

Identificador de un objeto de destino de E/S local o remoto obtenido de una llamada anterior a WdfDeviceGetIoTarget o WdfIoTargetCreate, o a partir de un método proporcionado por un destino de E/S especializado, como WdfUsbTargetPipeGetIoTarget.

[in] Action

Valor de tipo WDF_IO_TARGET_PURGE_IO_ACTION que indica si el marco debe esperar a que se devuelva de WdfIoTargetPurge hasta que se completen o cancelen todas las solicitudes entregadas.

Valor devuelto

None

Observaciones

Se produce una comprobación de errores si el controlador proporciona un identificador de objeto no válido.

Si el controlador ha llamado previamente a WdfUsbTargetPipeConfigContinuousReader, se debe llamar a WdfIoTargetPurge en IRQL = PASSIVE_LEVEL. Si el controlador no ha llamado a WdfUsbTargetPipeConfigContinuousReader y si el parámetro Action de WdfIoTargetPurge es WdfIoTargetPurgeIo, se puede llamar a WdfIoTargetPurge en IRQL <= DISPATCH_LEVEL. De lo contrario, se debe llamar a WdfIoTargetPurge en IRQL = PASSIVE_LEVEL.

Para que WdfIoTargetPurge sea una llamada sincrónica, el controlador puede establecer el valor WdfIoTargetPurgeIoAndWait del parámetro Action . En este caso, WdfIoTargetPurge espera a que se devuelvan hasta que se completen o cancelen todas las solicitudes entregadas.

Después de que un controlador haya llamado WdfIoTargetPurge, todavía puede enviar una solicitud al destino estableciendo la marca WDF_REQUEST_SEND_OPTION_IGNORE_TARGET_STATE en la estructura de WDF_REQUEST_SEND_OPTIONS de la solicitud. Por ejemplo, un controlador podría enviar una solicitud, como una solicitud para restablecer una canalización USB (consulte WdfUsbTargetPipeResetSynchronously), a un dispositivo después de llamar al controlador WdfIoTargetPurge.

Cuando un controlador llama a WdfIoTargetPurge, el marco no intenta cancelar ni esperar solicitudes de E/S que se enviaron anteriormente al destino mediante la marca WDF_REQUEST_SEND_OPTION_IGNORE_TARGET_STATE o la marca WDF_REQUEST_SEND_OPTION_SEND_AND_FORGET en la estructura de WDF_REQUEST_SEND_OPTIONS de la solicitud.

Una vez que un controlador ha purgado una cola de E/S, puede reiniciar la cola llamando a WdfIoTargetStart.

El controlador debe llamar a WdfIoTargetStart, WdfIoTargetStop y WdfIoTargetPurge de forma sincrónica. Después de que el controlador llame a una de estas funciones, no debe llamar a ninguno de los demás hasta que se devuelva la llamada anterior.

El controlador puede llamar a WdfIoTargetPurge varias veces sin llamar a WdfIoTargetStart. Por ejemplo, el controlador puede hacer lo siguiente:

Llame a WdfIoTargetPurge y especifique un valor action de WdfIoTargetPurgeIo.
Determine si el destino debe reanudar el procesamiento de solicitudes de E/S.
Si el destino debe reanudarse, llame a WdfIoTargetStart. De lo contrario, vuelva a llamar a WdfIoTargetPurge con un valor action de WdfIoTargetPurgeIoAndWait.

Para obtener más información sobre los estados de destino de E/S, vea Controlar el estado de un destino de E/S general.

Para obtener más información sobre los destinos de E/S, consulte Uso de destinos de E/S.

Ejemplos

En el ejemplo de código siguiente se muestra cómo una función de devolución de llamada EvtDeviceD0Exit puede llamar a WdfIoTargetPurge, si el controlador usa un lector continuo para una canalización USB.

NTSTATUS
MyEvtDeviceD0Exit(
    IN  WDFDEVICE Device,
    IN  WDF_POWER_DEVICE_STATE TargetState
)
{
    PDEVICE_CONTEXT  pDeviceContext;
    pDeviceContext = GetMyDeviceContext(Device);

    WdfIoTargetPurge(
                    WdfUsbTargetPipeGetIoTarget(pDeviceContext->InterruptPipe),
                    WdfIoTargetPurgeIoAndWait
                    );

    return STATUS_SUCCESS;
}

Requisitos

Requisito	Value
Plataforma de destino	Universal
Versión mínima de KMDF	1.11
Versión mínima de UMDF	2.0
Encabezado	wdfiotarget.h (incluya Wdf.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	vea la sección Comentarios.
Reglas de cumplimiento de DDI	DriverCreate(kmdf)