EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE función de devolución de llamada (wdfio.h)

  • Artículo

[Se aplica a KMDF y UMDF]

La función de devolución de llamada de eventos EvtIoCanceledOnQueue de un controlador informa al controlador de que debe completar una solicitud de E/S que el marco ha quitado de una cola de E/S.

Sintaxis

EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE EvtWdfIoQueueIoCanceledOnQueue;

void EvtWdfIoQueueIoCanceledOnQueue(
  [in] WDFQUEUE Queue,
  [in] WDFREQUEST Request
)
{...}

Parámetros

[in] Queue

Identificador de un objeto de cola de E/S.

[in] Request

Identificador de un objeto de solicitud.

Valor devuelto

None

Observaciones

Un controlador registra una función de devolución de llamada EvtIoCanceledOnQueue cuando llama al método WdfIoQueueCreate . Para obtener más información sobre cómo llamar a WdfIoQueueCreate, vea Crear colas de E/S.

Si un controlador registra una función de devolución de llamada EvtIoCanceledOnQueue para una cola de E/S, el marco llama a la función de devolución de llamada en las situaciones siguientes:

  • Un controlador de solicitudes recibe una solicitud de E/S de una cola de E/S, el controlador llama a WdfRequestForwardToIoQueue, WdfRequestForwardToParentDeviceIoQueue o WdfRequestRequeue para volver a poner en cola la solicitud a la cola de E/S para la que se registra la función de devolución de llamada EvtIoCanceledOnQueue y la operación de E/S asociada se cancela posteriormente.
  • La función de devolución de llamada EvtIoInCallerContext del controlador recibe una solicitud de E/S, el controlador llama a WdfDeviceEnqueueRequest para volver a pasar la solicitud al marco, el marco realiza la solicitud en la cola de E/S para la que se registra la función de devolución de llamada EvtIoCanceledOnQueue y la operación de E/S asociada se cancela posteriormente.
Una vez que el marco llama a la función de devolución de llamada EvtIoCanceledOnQueue , el controlador posee el objeto de solicitud y debe completar la solicitud con un código de estado adecuado, ya sea en EvtIoCanceledOnQueue o posterior. Cuando el marco llama a EvtIoCanceledOnQueue, la solicitud sigue asociada a la cola de E/S, pero el controlador no puede volver a poner en cola la solicitud. La propiedad de la solicitud permanece con el controlador incluso si el controlador no completa la solicitud en EvtIoCanceledOnQueue. Si el controlador completa la solicitud después de que EvtIoCanceledOnQueue devuelva, no puede llamar a WdfIoQueueFindRequest y WdfIoQueueRetrieveFoundRequest para volver a adquirir la propiedad de la solicitud porque el controlador ya tiene la propiedad de la solicitud.

Normalmente, en EvtIoCanceledOnQueue, el controlador completa la solicitud de E/S con un estado de finalización de STATUS_CANCELLED.

En algunos casos, es posible que el controlador haya vuelto a poner en cola previamente una solicitud de E/S a una cola manual, quizás esperar información. Por ejemplo, en uno de sus controladores de solicitudes, un controlador podría realizar una solicitud de E/S asociada a una transacción DMA pendiente en una cola manual. En este caso, el controlador intenta cancelar la transacción DMA en su devolución de llamada EvtIoCanceledOnQueue . Dependiendo de los resultados de la operación de cancelación, el controlador completa la solicitud con un estado adecuado, ya sea en EvtIoCanceledOnQueue o posterior.

El marco no llama a la función de devolución de llamada EvtIoCanceledOnQueue del controlador para las solicitudes de E/S que el marco nunca ha entregado al controlador.

El marco llama a una función de devolución de llamada EvtIoCanceledOnQueue en cuanto determina que se ha cancelado una solicitud de E/S, independientemente del método de envío que el controlador haya establecido para la cola de E/S. Por lo tanto, el marco puede llamar a una función de devolución de llamada EvtIoCanceledOnQueue para:

  • Solicitud en una cola que usa el envío secuencial, incluso si el controlador posee actualmente otra solicitud de la cola.
  • Una solicitud en una cola para la que el controlador ha establecido NumberOfPresentedRequests, incluso si el controlador posee actualmente el número máximo de solicitudes.
Para obtener más información sobre la función de devolución de llamada EvtIoCanceledOnQueue , vea Cancelar solicitudes de E/S.

Se puede llamar a la función de devolución de llamada EvtIoCanceledOnQueue en IRQL <= DISPATCH_LEVEL, a menos que el miembro ExecutionLevel de la estructura de WDF_OBJECT_ATTRIBUTES del dispositivo o del controlador esté establecido en WdfExecutionLevelPassive.

Si irQL está PASSIVE_LEVEL, el marco llama a la función de devolución de llamada dentro de una región crítica.

Ejemplos

Para definir una función de devolución de llamada EvtIoCanceledOnQueue , primero debe proporcionar una declaración de función que identifique el tipo de función de devolución de llamada que está definiendo. Windows proporciona un conjunto de tipos de función de devolución de llamada para controladores. Declarar una función mediante los tipos de función de devolución de llamada ayuda a Code Analysis for Drivers, Static Driver Verifier (SDV) y otras herramientas de comprobación encuentran errores y es un requisito para escribir controladores para el sistema operativo Windows.

Para definir una función de devolución de llamada EvtIoCanceledOnQueue , primero debe proporcionar una declaración de función que requieren SDV y otras herramientas de comprobación. El ejemplo siguiente se toma del ejemplo de controlador de tarjeta inteligente PCMCIA .

EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE PscrEvtIoCanceledOnQueue;

En el ejemplo de controlador de tarjeta inteligente PCMCIA , el controlador usa una cola manual para almacenar las solicitudes de notificación de tarjetas inteligentes pendientes. El controlador proporciona una función de devolución de llamada EvtIoCanceledOnQueue en la que el controlador borra el campo de notificación y completa la solicitud.

_Use_decl_annotations_
VOID
PscrEvtIoCanceledOnQueue(
    WDFQUEUE  Queue,
    WDFREQUEST  Request
    )

{
    PDEVICE_EXTENSION DeviceExtension;
    PSMARTCARD_EXTENSION smartcardExtension;

    DeviceExtension = GetDeviceExtension(WdfIoQueueGetDevice(Queue));
    smartcardExtension = (PSMARTCARD_EXTENSION) &DeviceExtension->SmartcardExtension;

    //KdPrint(("Cancelled on queue 0x%x\n", WdfRequestWdmGetIrp(Request)));

    InterlockedExchangePointer(
                             &(smartcardExtension->OsData->NotificationIrp),
                             NULL
                             );

    WdfRequestComplete(Request, STATUS_CANCELLED);
}

El tipo de función EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE se define en el archivo de encabezado Wdfio.h. Para identificar con más precisión los errores al ejecutar las herramientas de análisis de código, asegúrese de agregar la anotación Use_decl_annotations a la definición de función. La anotación Use_decl_annotations garantiza que se usen las anotaciones que se aplican al tipo de función EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE en el archivo de encabezado. Para obtener más información sobre los requisitos de las declaraciones de función, consulte Declaración de funciones mediante tipos de roles de función para controladores KMDF. Para obtener información sobre Use_decl_annotations, consulte Anotación del comportamiento de la función.

Requisitos

Requisito Value
Plataforma de destino Universal
Versión mínima de KMDF 1.0
Versión mínima de UMDF 2.0
Encabezado wdfio.h (incluya Wdf.h)
IRQL <= DISPATCH_LEVEL (consulte la sección Comentarios)

Consulte también

WdfIoQueueCreate

WdfRequestForwardToIoQueue