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

  • Статья

Процедура обратного вызова обслуживает различные irP. Список кодов функций см. в разделе Примечания.

Синтаксис

DRIVER_DISPATCH DriverDispatch;

NTSTATUS DriverDispatch(
  [in, out] _DEVICE_OBJECT *DeviceObject,
  [in, out] _IRP *Irp
)
{...}

Параметры

[in, out] DeviceObject

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

[in, out] Irp

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

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

Если подпрограмма завершается успешно, она должна вернуть STATUS_SUCCESS. В противном случае он должен вернуть одно из значений состояния ошибки, определенных в ntstatus.h.

Комментарии

Входные параметры для всех подпрограмм dispatch предоставляются в структуре IRP , на которую указывает Irp. Дополнительные параметры предоставляются в связанном с драйвером расположении стека ввода-вывода, которое описывается структурой IO_STACK_LOCATION и может быть получено путем вызова IoGetCurrentIrpStackLocation.

Как правило, все подпрограммы dispatch выполняются в произвольном контексте потока в IRQL = PASSIVE_LEVEL, но существуют исключения. Дополнительные сведения см. в разделе Подпрограммы диспетчеризации и списки IRQ.

Дополнительные сведения о подпрограммах диспетчеризации см. в статье Написание подпрограмм диспетчеризации. Дополнительные сведения о irPs см. в разделе Обработка irPs.

IRP Сведения о реализации обратного вызова
IRP_MJ_CLEANUP Подпрограмма DispatchCleanup драйвера должна называться XxxDispatchCleanup, где Xxx — это префикс драйвера. Подпрограмма DriverEntry драйвера должна хранить адрес подпрограммы DispatchCleanup в Файле DriverObject-MajorFunction>[IRP_MJ_CLEANUP].
IRP_MJ_CLOSE Подпрограмма DispatchClose драйвера должна называться XxxDispatchClose, где Xxx — это префикс драйвера. Подпрограмма DriverEntry драйвера должна хранить адрес подпрограммы DispatchClose в Файле DriverObject-MajorFunction>[IRP_MJ_CLOSE].
IRP_MJ_CREATE Подпрограмма DispatchCreate драйвера должна называться XxxDispatchCreate, где Xxx — это префикс, зависящий от драйвера. Подпрограмма DriverEntry драйвера должна хранить адрес подпрограммы DispatchCreate в Файле DriverObject-MajorFunction>[IRP_MJ_CREATE].
IRP_MJ_CREATE или IRP_MJ_CLOSE Драйвер может предоставить одну подпрограмму DispatchCreateClose вместо отдельных подпрограмм DispatchCreate и DispatchClose .

Подпрограмма DispatchCreateClose драйвера должна называться XxxDispatchCreateClose, где Xxx — это префикс для конкретного драйвера. Подпрограмма DriverEntry драйвера должна хранить адрес подпрограммы DispatchCreateClose в файлах DriverObject-MajorFunction>[IRP_MJ_CREATE] иDriverObject-MajorFunction>[IRP_MJ_CLOSE].
IRP_MJ_DEVICE_CONTROL Подпрограмма DispatchDeviceControl драйвера должна называться XxxDispatchDeviceControl, где Xxx — это префикс для конкретного драйвера. Подпрограмма DriverEntry драйвера должна хранить адрес подпрограммы DispatchDeviceControl в Файле DriverObject-MajorFunction>[IRP_MJ_DEVICE_CONTROL].

Система использует флаги FILE_XXX в коде элемента управления ввода-вывода, чтобы определить, имеет ли отправитель IRP права на отправку IRP объекту устройства. Драйверы для Windows Server 2003 и более поздних версий Windows могут использовать подпрограмму IoValidateDeviceIoControlAccess для выполнения более строгих проверок доступа в DispatchDeviceControl.
IRP_MJ_FLUSH_BUFFERS Подпрограмма DispatchFlushBuffers драйвера должна называться XxxDispatchFlushBuffers, где Xxx — это префикс конкретного драйвера. Подпрограмма DriverEntry драйвера должна хранить адрес подпрограммы DispatchFlushBuffers в DriverObject-MajorFunction>[IRP_MJ_FLUSH_BUFFERS].
IRP_MJ_INTERNAL_DEVICE_CONTROL Подпрограмма DispatchInternalDeviceControl драйвера должна называться XxxDispatchInternalDeviceControl, где Xxx — это префикс, зависящий от драйвера. Подпрограмма DriverEntry драйвера должна хранить адрес подпрограммы DispatchInternalDeviceControl в Файле DriverObject-MajorFunction>[IRP_MJ_INTERNAL_DEVICE_CONTROL].
IRP_MJ_PNP Подпрограмма DispatchPnP драйвера должна называться XxxDispatchPnP, где Xxx — это префикс, зависящий от драйвера. Подпрограмма DriverEntry драйвера должна хранить адрес подпрограммы DispatchPnP в DriverObject-MajorFunction>[IRP_MJ_PNP].
IRP_MJ_POWER Подпрограмма DispatchPower драйвера должна называться XxxDispatchPower, где Xxx — это префикс конкретного драйвера. Подпрограмма DriverEntry драйвера должна хранить адрес подпрограммы DispatchPower в Файле DriverObject-MajorFunction>[IRP_MJ_POWER].
IRP_MJ_QUERY_INFORMATION Подпрограмма DispatchQueryInformation драйвера должна называться XxxDispatchQueryInformation, где Xxx — это префикс конкретного драйвера. Подпрограмма DriverEntry драйвера должна хранить адрес подпрограммы DispatchQueryInformation в Файле DriverObject-MajorFunction>[IRP_MJ_QUERY_INFORMATION].
IRP_MJ_READ Подпрограмма DispatchRead драйвера должна называться XxxDispatchRead, где Xxx — это префикс драйвера. Подпрограмма DriverEntry драйвера должна хранить адрес подпрограммы DispatchRead в Файле DriverObject-MajorFunction>[IRP_MJ_READ].
IRP_MJ_READ или IRP_MJ_WRITE Драйвер может предоставить одну подпрограмму DispatchReadWrite вместо отдельных подпрограмм DispatchRead и DispatchWrite .

Подпрограмма DispatchReadWrite драйвера должна называться XxxDispatchReadWrite, где Xxx — это префикс драйвера. Подпрограмма DriverEntry драйвера должна хранить адрес подпрограммы DispatchReadWrite в DriverObject-MajorFunction>[IRP_MJ_READ] и в DriverObject-MajorFunction>[IRP_MJ_WRITE].
IRP_MJ_SET_INFORMATION Подпрограмма DispatchSetInformation драйвера должна называться XxxDispatchSetInformation, где Xxx — это префикс конкретного драйвера. Подпрограмма DriverEntry драйвера должна хранить адрес подпрограммы DispatchSetInformation в Файле DriverObject-MajorFunction>[IRP_MJ_SET_INFORMATION].
IRP_MJ_SHUTDOWN Подпрограмма DispatchShutdown драйвера должна называться XxxDispatchShutdown, где Xxx — это префикс для конкретного драйвера. Подпрограмма DriverEntry драйвера должна хранить адрес подпрограммы DispatchShutdown в Файле DriverObject-MajorFunction>[IRP_MJ_SHUTDOWN].

Кроме того, для получения IRP_MJ_SHUTDOWN запросов драйвер должен вызвать IoRegisterShutdownNotification или IoRegisterLastChanceShutdownNotification , чтобы зарегистрировать свою подпрограмму DispatchShutdown в системе.
IRP_MJ_SYSTEM_CONTROL Подпрограмма DispatchSystemControl драйвера должна называться XxxDispatchSystemControl, где Xxx — это префикс, зависящий от драйвера. Подпрограмма DriverEntry драйвера должна хранить адрес подпрограммы DispatchSystemControl в Файле DriverObject-MajorFunction>[IRP_MJ_SYSTEM_CONTROL].
IRP_MJ_WRITE Подпрограмма DispatchWrite драйвера должна называться XxxDispatchWrite, где Xxx — это префикс, зависящий от драйвера. Подпрограмма DriverEntry драйвера должна хранить адрес подпрограммы DispatchWrite в DriverObject-MajorFunction>[IRP_MJ_WRITE].

Примеры

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

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

DRIVER_DISPATCH MyDispatchCleanup;

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

_Use_decl_annotations_
NTSTATUS
  MyDispatchCleanup(
    struct _DEVICE_OBJECT  *DeviceObject,
    struct _IRP  *Irp
    )
  {
      // Function body
  }

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

Требования

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