ZwCreateEvent 函式 (ntifs.h)

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

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

[in] EventType

事件的類型,可以是 SynchronizationEventNotificationEvent。 這些值屬於ntdef.h標頭檔中定義的EVENT_TYPE列舉。

[in] InitialState

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

傳回值

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

傳回碼 描述
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 狀態,它就會維持在該狀態,直到明確重設為止。

若要同步處理通知事件:

  1. 使用 ZwCreateEvent 建立通知事件,並將 EventType 參數設定為 NotificationEvent

  2. 使用ZwCreateEvent傳回的EventHandle呼叫ZwWaitForSingleObject,等候事件發出訊號。 一個以上的執行執行緒可以等候指定的通知事件收到訊號。 若要輪詢而不是停止,請指定零到ZwWaitForSingleObject時。

  3. 當不再需要存取事件時,請使用 ZwClose 關閉通知事件的控制碼。

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

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

  • 作為完整路徑名稱,提供于輸入ObjectAttributesObjectName成員中。

  • 路徑名稱,相對於輸入ObjectAttributes之 RootDirectory成員中控制碼所代表的目錄。

若要釋放事件,驅動程式會使用事件控制碼呼叫 ZwClose

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

注意

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

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

規格需求

   
最低支援的用戶端 從 Windows XP 開始提供。
目標平臺 環球
標頭 ntifs.h (包含 Ntifs.h)
程式庫 NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL
DDI 合規性規則 HwStorPortProhibitedDIS (storport) PowerIrpDDis (wdm)

另請參閱

ACCESS_MASK

InitializeObjectAttributes

IoCreateNotificationEvent

IoCreateSynchronizationEvent

KeClearEvent

KeResetEvent

KeSetEvent

KeWaitForSingleObject

使用 Nt 和 Zw 版本的原生系統服務常式

ZwClose

ZwSetEvent

ZwWaitForSingleObject