Функция KeSetEvent (wdm.h)

Статья
08/08/2023

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

Синтаксис

LONG KeSetEvent(
  [in, out] PRKEVENT  Event,
  [in]      KPRIORITY Increment,
  [in]      BOOLEAN   Wait
);

Параметры

[in, out] Event

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

[in] Increment

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

[in] Wait

Указывает, должен ли за вызовом KeSetEvent немедленно следовать вызов одной из подпрограмм KeWaitXxx . Если задано значение TRUE, за вызовом KeSetEvent должен следовать вызов KeWaitForMultipleObjects, KeWaitForMutexObject или KeWaitForSingleObject. Дополнительные сведения см. в разделе "Примечания".

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

Если было указано предыдущее состояние объекта события, возвращается ненулевое значение.

Вызов KeSetEvent приводит к тому, что событие достигает состояния сигнала. Если событие является событием уведомления, система пытается удовлетворить как можно больше ожиданий объекта события. Событие остается сигнальным до тех пор, пока вызов KeClearEvent или KeResetEvent не очислит его. Если событие является событием синхронизации, выполняется одно ожидание, прежде чем система автоматически очистет событие.

Подпрограмма KeSetEvent может временно вызвать IRQL. Если параметр Wait имеет значение FALSE, подпрограмма перед возвратом восстанавливает значение IRQL до исходного значения, которое она имела в начале вызова.

Если значение Wait = TRUE, подпрограмма возвращает без снижения значения IRQL. В этом случае за вызовом KeSetEvent должен следовать вызов KeWaitXxx . Установив параметр Wait = TRUE, вызывающий объект может предотвратить ненужное переключение контекста между вызовом KeSetEvent и вызовом KeWaitXxx . Подпрограмма KeWaitXxx перед возвратом восстанавливает исходное значение IRQL в начале вызова KeSetEvent . Хотя IRQL отключает переключение контекста между двумя вызовами, эти вызовы не могут надежно использоваться в качестве начала и окончания атомарной операции. Например, между этими двумя вызовами поток, выполняющийся одновременно на другом процессоре, может изменить состояние объекта события или целевого объекта ожидания.

Выстраиваемый поток или подпрограмма драйвера, которая выполняется в IRQL = PASSIVE_LEVEL никогда не должна вызывать KeSetEvent с параметром Wait , равным TRUE. Такой вызов вызывает неустранимую ошибку страницы, если вызывающий объект выходит на страницу между вызовами KeSetEvent и KeWaitXxx.

Дополнительные сведения об объектах событий см. в разделе Объекты событий.

Если параметр Wait имеет значение FALSE, вызывающий объект может выполняться в irQL <= DISPATCH_LEVEL. В противном случае вызывающие функции KeSetEvent должны выполняться в среде IRQL <= APC_LEVEL и в контексте неарбитарных потоков.

Требования

Требование	Значение
Минимальная версия клиента	Доступно начиная с Windows 2000.
Целевая платформа	Универсальное
Верхняя часть	wdm.h (включая Wdm.h, Ntddk.h, Ntifs.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	См. раздел "Примечания".
Правила соответствия DDI	CompletionEventChecking(wdm), DoubleKeSetEvent(storport), HwStorPortProhibitedDDIs(storport), IoAllocateIrpSignalEventInCompletion(wdm), IoBuildDeviceIoControlSetEvent(wdm), IoBuildFsdIrpSignalEventInCompletion(wdm), IrqlKeSetEvent(wdm), SignalEventInCompletion(wdm)