KeSetEvent 函式 (wdm.h)

發行項
02/27/2024

如果事件尚未發出訊號， 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 例程在傳回之前，會在 KeSetEvent 呼叫開始時，將 IRQL 還原為其原始值。雖然 IRQL 會停用兩個呼叫之間的內容切換，但這些呼叫無法可靠地當做不可部分完成作業的開始和結束。例如，在這兩個呼叫之間，在另一個處理器上同時執行的線程可能會變更事件物件或等候目標的狀態。

在 IRQL = PASSIVE_LEVEL執行的可分頁線程或可分頁驅動程式例程絕對不應該呼叫 KeSetEvent ，並將 Wait 參數設定為 TRUE。如果呼叫端在 呼叫KeSetEvent 和 KeWaitXxx的呼叫之間發生分頁，這類呼叫會造成嚴重頁面錯誤。

如需事件對象的詳細資訊，請參閱 Event Objects。

如果 Wait 設定為 FALSE，則呼叫端可以在 IRQL <= DISPATCH_LEVEL執行。否則， KeSetEvent 的呼叫端必須在 IRQL <= APC_LEVEL 和非位線程內容中執行。

規格需求

需求	值
最低支援的用戶端	從 Windows 2000 開始提供。
目標平台	Universal
標頭	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)