共用方式為

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

要用於指定物件之呼叫端所提供之物件屬性結構的指標。 例如，這些屬性會包含 ObjectName 和 SECURITY_DESCRIPTOR。 這個參數是藉由呼叫 InitializeObjectAttributes 巨集來初始化。

[in] EventType

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

[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，以等候事件發出訊號。 一個以上的執行線程可以等候指定的通知事件收到訊號。 若要輪詢而不是停止，請指定零 逾時ZwWaitForSingleObject。

  3. 當不再需要存取事件時，請使用 ZwClose 關閉通知事件的句柄。

ZwCreateEvent 函式會在 InitializeObjectAttributes 巨集用於設定物件 OBJECT_ATTRIBUTES 結構中的屬性之後呼叫。

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

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

  • 做為路徑名稱，相對於 input ObjectAttributes中 RootDirectory 成員所表示的目錄。

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

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

注意

如果在使用者模式中呼叫 ZwCreateEvent 例程，您應該使用名稱 “NtCreateEvent” 而不是 “ZwCreateEvent”。

對於內核模式驅動程式的呼叫，NtXxx 和 ZwXxx 版本的 Windows 原生系統服務例程，在處理和解譯輸入參數的方式上可能會有不同的行為。 如需 nt NtXxx 與 ZwXxx 例程之間關聯性的詳細資訊，請參閱 使用 Nt 和 Zw 版本的原生系統服務例程。

要求

要求 價值
最低支援的用戶端 Windows XP。
目標平臺 普遍
標頭 ntifs.h （include 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