DRIVER_CANCEL función de devolución de llamada (wdm.h)

La rutina Cancelar cancela una operación de E/S.

Sintaxis

DRIVER_CANCEL DriverCancel;

void DriverCancel(
  [in, out] _DEVICE_OBJECT *DeviceObject,
  [in, out] _IRP *Irp
)
{...}

Parámetros

[in, out] DeviceObject

Puntero proporcionado por el autor de la llamada a una estructura de DEVICE_OBJECT . Este es el objeto de dispositivo para el dispositivo de destino, creado anteriormente por la rutina AddDevice del controlador.

[in, out] Irp

Puntero proporcionado por el autor de la llamada a una estructura IRP que describe la operación de E/S que se va a cancelar.

Valor devuelto

None

Observaciones

Cuando un controlador u otro componente del sistema llama a IoCancelIrp, el administrador de E/S llama a la rutina Cancel de IRP, si se ha registrado para irP.

Para registrar una rutina Cancel para un IRP, un controlador puede usar cualquiera de los dos métodos siguientes:

1. Un controlador que proporciona una rutina StartIo y usa la cola de dispositivos proporcionada por el administrador de E/S puede especificar una rutina Cancel al llamar a IoStartPacket.

2. Un controlador que crea y administra colas de dispositivos adicionales puede registrar una rutina Cancel llamando a IoSetCancelRoutine.

Solo se puede registrar una rutina Cancel para un IRP al mismo tiempo.

El administrador de E/S llama a IoAcquireCancelSpinLock antes de llamar a la rutina Cancel de un controlador, por lo que la rutina Cancel debe llamar a IoReleaseCancelSpinLock en algún momento. La rutina no debe mantener el bloqueo de número más largo de lo necesario.

La rutina Cancel se ejecuta en un contexto de subproceso arbitrario en IRQL = DISPATCH_LEVEL hasta que llama a IoReleaseCancelSpinLock, que cambia el IRQL a un valor proporcionado por el autor de la llamada. El controlador debe especificar Irp-CancelIrql> para este valor.

La rutina Cancel debe establecer el miembro Status del bloque de estado de E/S en STATUS_CANCELLED y establecer su miembro Information en cero. A continuación, la rutina debe completar el IRP especificado llamando a IoCompleteRequest.

Para obtener información detallada sobre cómo implementar la rutina Cancel de un controlador, consulte Cancelar IRP.

Ejemplos

Para definir una rutina cancelar devolución de llamada, primero debe proporcionar una declaración de función que identifique el tipo de rutina 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.

Por ejemplo, para definir una rutina cancelar devolución de llamada denominada MyCancel, use el tipo de DRIVER_CANCEL como se muestra en este ejemplo de código:

DRIVER_CANCEL MyCancel;

A continuación, implemente la rutina de devolución de llamada de la siguiente manera:

_Use_decl_annotations_
VOID
  MyCancel(
    struct _DEVICE_OBJECT  *DeviceObject,
    struct _IRP  *Irp
    )
  {
      // Function body
  }

El tipo de función DRIVER_CANCEL se define en el archivo de encabezado Wdm.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 a la _Use_decl_annotations_ definición de la función. La _Use_decl_annotations_ anotación garantiza que se usen las anotaciones que se aplican al tipo de función DRIVER_CANCEL en el archivo de encabezado. Para obtener más información sobre los requisitos de las declaraciones de función, vea Declarar funciones mediante tipos de roles de función para controladores WDM. Para obtener información sobre _Use_decl_annotations_, consulte Anotación del comportamiento de la función.

Requisitos

Requisito	Value
Plataforma de destino	Escritorio
Encabezado	wdm.h (incluya Wdm.h, Ntddk.h, Ntifs.h)
IRQL	Se llama en DISPATCH_LEVEL (consulte la sección Comentarios).