ZwCreateEvent 函式 (ntifs.h)

發行項
02/26/2024

ZwCreateEvent 例程會建立事件物件、將事件的初始狀態設定為指定的值，並開啟具有指定所需存取權之物件的句柄。

語法

NTSYSAPI NTSTATUS ZwCreateEvent(
  [out]          PHANDLE            EventHandle,
  [in]           ACCESS_MASK        DesiredAccess,
  [in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
  [in]           EVENT_TYPE         EventType,
  [in]           BOOLEAN            InitialState
);

參數

[out] EventHandle

將接收事件物件句柄之變數的指標。句柄包含簿記資訊，例如參考計數和安全性內容。

[in] DesiredAccess

ACCESS_MASK值，表示事件物件所需的存取類型。下表包含事件特定的ACCESS_MASK值。

值	所需的存取權
EVENT_QUERY_STATE	查詢事件物件的狀態。
EVENT_MODIFY_STATE	修改事件物件的狀態。
EVENT_ALL_ACCESS	事件物件的所有可能訪問許可權。

[in, optional] ObjectAttributes

對象屬性結構的指標，由呼叫端提供給指定的物件使用。例如，這些屬性會包含 ObjectName 和 SECURITY_DESCRIPTOR。這個參數是藉由呼叫 InitializeObjectAttributes 宏來初始化。

[in] EventType

事件的類型，可以是 SynchronizationEvent 或 NotificationEvent。這些值屬於 ntdef.h 頭檔中定義的EVENT_TYPE列舉。

[in] InitialState

事件物件的初始狀態。設定為 TRUE ，將事件物件初始化為 Signaled 狀態。設定為 FALSE ，將事件物件初始化為 not-Signaled 狀態。

傳回值

ZwCreateEvent 會傳回STATUS_SUCCESS或適當的錯誤狀態。可能的錯誤狀態代碼包括：

傳回碼	Description
STATUS_INSUFFICIENT_RESOURCES	無法設定此函式所需的資源。
STATUS_INVALID_PARAMETER	提供的 ObjectAttributes 結構包含無效的參數值。
STATUS_INVALID_PARAMETER_4	指定的 EventType 參數無效。
STATUS_OBJECT_NAME_INVALID	ObjectAttributes 參數在無效的OBJECT_ATTRIBUTES結構中包含 ObjectName。
STATUS_OBJECT_PATH_SYNTAX_BAD	ObjectAttributes 參數不包含 RootDirectory 成員，但OBJECT_ATTRIBUTES結構中的 ObjectName 成員是空字串，或不包含OBJECT_NAME_PATH_SEPARATOR字元。這表示對象路徑的語法不正確。
STATUS_PRIVILEGE_NOT_HELD	呼叫端沒有建立具有 DesiredAccess 參數中所指定存取權的必要許可權。

備註

ZwCreateEvent 會建立事件物件、將其初始狀態設定為指定的值，並使用指定的所需存取開啟物件的句柄。

事件是用來協調執行。文件系統驅動程式可以使用事件，以允許呼叫端等候要求作業完成，直到指定的事件設定為 Signaled 狀態為止。

ZwCreateEvent 可以建立通知或同步處理事件：

通知事件可用來通知一或多個線程執行已發生事件。
同步處理事件可用於串行化存取兩個其他不相關的驅動程式之間的硬體。

同步處理事件會自動重設。當同步處理事件設定為 Signaled 狀態時，會釋放等候事件發出訊號的單一執行線程，而且事件會自動重設為 Not-Signaled 狀態。

不同於同步處理事件，通知事件不會自動重設。一旦通知事件處於 Signaled 狀態，它就會維持在該狀態，直到明確重設為止。

若要同步處理通知事件：

使用 ZwCreateEvent 建立通知事件，並將 EventType 參數設定為 NotificationEvent。
使用 ZwCreateEvent 傳回的 EventHandle 呼叫 ZwWaitForSingleObject，等候事件發出訊號。一個以上的執行線程可以等候指定的通知事件收到訊號。若要輪詢而不是停止，請指定零到 ZwWaitForSingleObject 的逾時。
當不再需要存取事件時，請使用 ZwClose 關閉通知事件的句柄。

在 InitializeObjectAttributes 宏用來設定物件的OBJECT_ATTRIBUTES結構中的屬性之後，就會呼叫 ZwCreateEvent 函式。

有兩種替代方式可以指定傳遞至 ZwCreateEvent 的物件名稱：

作為完整路徑名稱，提供於輸入 ObjectAttributes 的 ObjectName 成員中。
路徑名稱，相對於輸入 ObjectAttributes之 RootDirectory 成員中句柄所代表的目錄。

若要釋放事件，驅動程式會使用事件句柄呼叫 ZwClose 。

如需事件的詳細資訊，請參閱 事件物件。

注意

如果使用者模式中發生 ZwCreateEvent 例程的呼叫，您應該使用名稱「NtCreateEvent」而不是「ZwCreateEvent」。。

針對來自內核模式驅動程式的呼叫，Windows 原生系統服務例程的 NtXxx 和 ZwXxx 版本會以處理和解譯輸入參數的方式，以不同的方式運作。如需 例程 NtXxx 和 ZwXxx 版本之間關聯性的詳細資訊，請參閱使用原生系統服務例程的 Nt 和 Zw 版本。

規格需求

需求	值
最低支援的用戶端	Windowsxp。
目標平台	Universal
標頭	ntifs.h (包含 Ntifs.h)
程式庫	NtosKrnl.lib
Dll	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI 合規性規則	HwStorPortProhibitedDIS (storport) 、 PowerIrpDDis (wdm)