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

Эта подпрограмма запускает передачу данных DMA или операцию передачи данных.

Синтаксис

DRIVER_CONTROL DriverControl;

IO_ALLOCATION_ACTION DriverControl(
  [in]      _DEVICE_OBJECT *DeviceObject,
  [in, out] _IRP *Irp,
  [in]      PVOID MapRegisterBase,
  [in]      PVOID Context
)
{...}

Параметры

[in] DeviceObject

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

[in, out] Irp

Предоставленный вызывающим элементом указатель на структуру IRP . Значение Irp равно значению элемента CurrentIrpобъекта DeviceObject при регистрации процедуры обратного вызова.

[in] MapRegisterBase

В случае AdapterControl это поставляемое вызывающим объектом непрозрачное значение, представляющее регистры карты, назначенные системой для этой операции передачи. Драйвер передает это значение в FlushAdapterBuffers, FreeMapRegisters и MapTransfer.

В случае ControllerControl это не используется.

[in] Context

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

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

Подпрограмма должна возвращать одно из значений, определенных перечислением IO_ALLOCATION_ACTION . Драйверы устройств с master автобуса возвращают Либо DeallocateObject, либо DeallocateObjectKeepRegisters; драйверы, использующие системные DMA, возвращают KeepObject.

Комментарии

Чтобы зарегистрировать подпрограмму AdapterControl для определенного объекта устройства, драйвер должен вызвать IoGetDmaAdapter , чтобы получить объект адаптера, а затем вызвать AllocateAdapterChannel , чтобы запросить использование адаптера и указать адрес подпрограммы AdapterControl . Когда адаптер свободен, система вызывает подпрограмму AdapterControl .

Если AdapterControl был зарегистрирован подпрограммой StartIo , то параметр Irp гарантированно указывает на IRP, обрабатываемый в данный момент подпрограммой StartIo . В противном случае драйверы должны задать элемент CurrentIrp структуры объекта устройства перед вызовом AllocateAdapterChannel.

Подробные сведения о реализации подпрограммы AdapterControl см. в статье Написание подпрограмм AdapterControl.

Подпрограмма ControllerControl драйвера выполняется в произвольном контексте потока в irQL = DISPATCH_LEVEL.

Чтобы зарегистрировать подпрограмму ControllerControl для определенного объекта устройства, драйвер должен вызвать IoCreateController , чтобы получить объект контроллера, а затем вызвать IoAllocateController , чтобы запросить использование контроллера и указать адрес подпрограммы ControllerControl . Когда контроллер свободен, система вызывает подпрограмму ControllerControl .

Подробные сведения о реализации подпрограммы ControllerControl см. в статье Написание подпрограмм ControllerControl. См. также статью Объекты контроллера.

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

Примеры

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

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

DRIVER_CONTROL MyAdapterControl;

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

_Use_decl_annotations_
IO_ALLOCATION_ACTION
 MyAdapterControl(
    struct _DEVICE_OBJECT  *DeviceObject,
    struct _IRP  *Irp,
    PVOID  MapRegisterBase,
    PVOID  Context
    )
  {
      // Function body
  }

Требования

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

См. также раздел

AllocateAdapterChannel