KeInitializeEvent function

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

NTKERNELAPI VOID KeInitializeEvent(
  PRKEVENT   Event,
  EVENT_TYPE Type,
  BOOLEAN    State
);

Parameters

Event

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

Type

Specifies the event type, either NotificationEvent or SynchronizationEvent.

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. Synchronization events are rarely used in a typical driver.

For more information about event objects, see Event Objects.

Requirements

   
Windows version 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 IoAllocateIrpSignalEventInCompletion, IoAllocateIrpSignalEventInCompletion2, IoAllocateIrpSignalEventInCompletion3, IoAllocateIrpSignalEventInCompletionTimeout, IoBuildDeviceControlWait, IoBuildDeviceControlWaitTimeout, IoBuildDeviceIoControlSetEvent, IoBuildFsdIrpSignalEventInCompletion, IoBuildFsdIrpSignalEventInCompletion2, IoBuildFsdIrpSignalEventInCompletion3, IoBuildFsdIrpSignalEventInCompletionTimeout, IoBuildSynchronousFsdRequestWait, IoBuildSynchronousFsdRequestWaitTimeout, PendedCompletedRequest, PendedCompletedRequestEx, SignalEventInCompletion, SignalEventInCompletion2, SignalEventInCompletion3, StartDeviceWait, StartDeviceWait2, HwStorPortProhibitedDDIs

See Also

KeClearEvent

KeReadStateEvent

KeResetEvent

KeSetEvent

KeWaitForMultipleObjects

KeWaitForSingleObject