функция обратного вызова DRIVER_CANCEL (wdm.h)

  • Статья

Подпрограмма Отмена отменяет операцию ввода-вывода.

Синтаксис

DRIVER_CANCEL DriverCancel;

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

Параметры

[in, out] DeviceObject

Указатель на структуру DEVICE_OBJECT , предоставленный вызывающим абонентом. Это объект устройства для целевого устройства, ранее созданный подпрограммой AddDevice драйвера.

[in, out] Irp

Предоставленный вызывающим абонентом указатель на структуру IRP , которая описывает операцию ввода-вывода, которую необходимо отменить.

Возвращаемое значение

None

Remarks

Когда драйвер или другой системный компонент вызывает IoCancelIrp, диспетчер операций ввода-вывода вызывает процедуру отмены IRP, если она зарегистрирована для IRP.

Чтобы зарегистрировать подпрограмму отмены для IRP, драйвер может использовать один из следующих двух методов:

  1. Драйвер, предоставляющий подпрограмму StartIo и использующий очередь устройств, предоставляемую диспетчером ввода-вывода, может указывать подпрограмму Отмена при вызове IoStartPacket.

  2. Драйвер, который создает дополнительные очереди устройств и управляет ими, может зарегистрировать подпрограмму отмены , вызвав IoSetCancelRoutine.

Одновременно для IRP можно зарегистрировать только одну подпрограмму отмены .

Диспетчер операций ввода-вывода вызывает IoAcquireCancelSpinLock перед вызовом процедуры отмены драйвера, поэтому подпрограмма Отмена в какой-то момент должна вызвать IoReleaseCancelSpinLock . Подпрограмма не должна содержать спин-блокировку дольше, чем необходимо.

Подпрограмма Cancel выполняется в произвольном контексте потока в irQL = DISPATCH_LEVEL, пока не вызовет IoReleaseCancelSpinLock, который изменяет IRQL на предоставленное вызывающим объектом значение. Драйвер должен указать Irp-CancelIrql> для этого значения.

Подпрограмма Отмена должна задать для элемента Status блока "Состояние ввода-вывода" значение STATUS_CANCELLED, а для элемента Information — нулевое значение. Затем подпрограмма должна завершить указанный IRP, вызвав IoCompleteRequest.

Подробные сведения о реализации процедуры отмены драйвера см. в разделе Отмена IRP.

Примеры

Чтобы определить подпрограмму отмены обратного вызова, необходимо сначала предоставить объявление функции, определяющее тип определяемой процедуры обратного вызова. Windows предоставляет набор типов функций обратного вызова для драйверов. Объявление функции с помощью типов функций обратного вызова помогает анализу кода для драйверов, средству проверки статических драйверов (SDV) и другим средствам проверки находить ошибки, и это требование для написания драйверов для операционной системы Windows.

Например, чтобы определить подпрограмму отмены обратного вызова с именем MyCancel, используйте тип DRIVER_CANCEL, как показано в следующем примере кода:

DRIVER_CANCEL MyCancel;

Затем реализуйте процедуру обратного вызова следующим образом:

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

Тип функции DRIVER_CANCEL определяется в файле заголовка Wdm.h. Чтобы более точно определить ошибки при запуске средств анализа кода, обязательно добавьте заметку в _Use_decl_annotations_ определение функции. Заметка _Use_decl_annotations_ гарантирует, что будут использоваться заметки, которые применяются к типу функции DRIVER_CANCEL в файле заголовка. Дополнительные сведения о требованиях к объявлениям функций см. в разделе Объявление функций с помощью типов ролей функций для драйверов WDM. Дополнительные сведения о _Use_decl_annotations_см. в статье Поведение функции с заметками.

Требования

Требование Значение
Целевая платформа Персональный компьютер
Верхняя часть wdm.h (включая Wdm.h, Ntddk.h, Ntifs.h)
IRQL Вызывается на DISPATCH_LEVEL (см. раздел "Примечания").