KeInitializeEvent function (wdm.h)

Article
05/12/2023

The KeInitializeEvent routine initializes an event object as a synchronization (single waiter) or notification type event and sets it to a signaled or not-signaled state.

Syntax

void KeInitializeEvent(
  [out] PRKEVENT   Event,
  [in]  EVENT_TYPE Type,
  [in]  BOOLEAN    State
);

Parameters

[out] Event

Pointer to an event object, for which the caller provides the storage.

[in] Type

Specifies the event type, either NotificationEvent or SynchronizationEvent.

[in] State

Specifies the initial state of the event. TRUE indicates a signaled state.

Return value

None

Remarks

Storage for an event object must be resident: in the device extension of a driver-created device object, in the controller extension of a driver-created controller object, or in nonpaged pool allocated by the caller. If you allocate the event on the stack, you must specify a KernelMode wait when calling KeWaitForSingleObject, KeWaitForMutexObject, or KeWaitForMultipleObjects. During a KernelMode wait, the stack containing the event will not be paged out.

Drivers typically use a NotificationEvent to wait for an I/O operation to complete. When a notification event is set to the signaled state, all threads that were waiting for the event to be set to the signaled state become eligible for execution. The event remains in the signaled state until a thread calls KeResetEvent or KeClearEvent to set the event in the not-signaled state.

A SynchronizationEvent is also called an autoreset or autoclearing event. When such an event is set, a single waiting thread becomes eligible for execution. The kernel automatically resets the event to the not-signaled state each time a wait is satisfied. A driver might use a synchronization event to protect a shared resource that is used in synchronizing the operations of several threads.

For more information about event objects, see Event Objects.

Requirements

Requirement	Value
Minimum supported client	Available starting with Windows 2000.
Target Platform	Universal
Header	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	Any level
DDI compliance rules	HwStorPortProhibitedDDIs(storport), IoAllocateIrpSignalEventInCompletion(wdm), IoAllocateIrpSignalEventInCompletion2(wdm), IoAllocateIrpSignalEventInCompletion3(wdm), IoAllocateIrpSignalEventInCompletionTimeout(wdm), IoBuildDeviceControlWait(wdm), IoBuildDeviceControlWaitTimeout(wdm), IoBuildDeviceIoControlSetEvent(wdm), IoBuildFsdIrpSignalEventInCompletion(wdm), IoBuildFsdIrpSignalEventInCompletion2(wdm), IoBuildFsdIrpSignalEventInCompletion3(wdm), IoBuildFsdIrpSignalEventInCompletionTimeout(wdm), IoBuildSynchronousFsdRequestWait(wdm), IoBuildSynchronousFsdRequestWaitTimeout(wdm), PendedCompletedRequest(wdm), PendedCompletedRequestEx(wdm), SignalEventInCompletion(wdm), SignalEventInCompletion2(wdm), SignalEventInCompletion3(wdm), StartDeviceWait(wdm), StartDeviceWait2(wdm)