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

Статья
03/08/2023

Подпрограмма InterruptMessageService обслуживает прерывание по сигналу сообщения.

Синтаксис

KMESSAGE_SERVICE_ROUTINE KmessageServiceRoutine;

BOOLEAN KmessageServiceRoutine(
  [in] _KINTERRUPT *Interrupt,
  [in] PVOID ServiceContext,
       ULONG MessageID
)
{...}

Параметры

[in] Interrupt

Указатель на структуру KINTERRUPT для прерывания. Драйвер получил этот указатель в вызове процедуры IoConnectInterruptEx , которая зарегистрировала подпрограмму InterruptMessageService драйвера.

[in] ServiceContext

Значение ServiceContext , переданное драйвером в IoConnectInterruptEx при регистрации подпрограммы InterruptMessageService .

MessageID

Идентификатор сообщения для прерывания. Это значение является индексом для записи прерывания в массиве элементов MessageInfo в структуре IO_INTERRUPT_MESSAGE_INFO , описывающей прерывания драйвера, сигнализированные сообщением.

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

Подпрограмма InterruptMessageService возвращает значение TRUE , если прерывание обрабатывается подпрограммой InterruptMessageService . В противном случае возвращается значение FALSE.

Драйверы используют IoConnectInterruptEx для регистрации подпрограммы InterruptMessageService для обработки прерываний, сигнальных сообщением. Впоследствии драйвер может отменить регистрацию подпрограммы, вызвав IoDisconnectInterruptEx. Прерывания с сигналом сообщения поддерживаются, начиная с Windows Vista.

Система может вызывать подпрограмму InterruptMessageService , даже если прерывания подпрограммы не произошло. Например, если прерывание, по сигналу о сообщении, является общим, можно вызвать InterruptMessageService для прерываний, принадлежащих другим устройствам. Подпрограмма должна проверка, совпадает ли значение параметра ServiceContext со значением, переданным в IoConnectInterruptEx. Если значение совпадает, функция InterruptMessageService обрабатывает прерывание и возвращает значение TRUE. В противном случае функция InterruptMessageService не обрабатывает прерывание и возвращает значение FALSE.

Драйвер, использующий MSI (PCI 2.2), должен проверять параметр MessageID , чтобы различать различные сообщения, созданные устройством, так как все они используют один и тот же ресурс прерывания (и, следовательно, один и тот же обратный вызов InterruptMessageService> ).

Обратите внимание, что если система получает несколько одинаковых прерываний в течение короткого интервала времени, она может объединить их в один вызов InterruptMessageService. Подпрограмма должна быть записана для обработки нескольких одинаковых прерываний в одном вызове.

Прерывания, по сигналу сообщения, по поведению аналогичны прерываниям, инициированным ребрами. Устройство отправляет запрос прерывания, но не получает аппаратного подтверждения того, что запрос был получен.

InterruptMessageService выполняется в irQL, превышающем максимальное значение IRQL устройства (DIRQL) для каждого прерывания, выполняемого подпрограммой.

Примеры

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

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

KMESSAGE_SERVICE_ROUTINE MyInterruptMessageService;

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

_Use_decl_annotations_
BOOLEAN
  MyInterruptMessageService(
    struct _KINTERRUPT  *Interrupt,
    PVOID  ServiceContext,
    ULONG  MessageId 
    )
  {
      // Function body
  }

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

Требования

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