функция обратного вызова 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 (см. раздел "Замечания"). |