ZwOpenEvent 函式 (wdm.h)

發行項
02/27/2024

ZwOpenEvent 例程會開啟具有指定所需存取權的現有具名事件物件的句柄。

語法

NTSYSCALLAPI NTSTATUS ZwOpenEvent(
  [out] PHANDLE            EventHandle,
  [in]  ACCESS_MASK        DesiredAccess,
  [in]  POBJECT_ATTRIBUTES ObjectAttributes
);

參數

[out] EventHandle

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

[in] DesiredAccess

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

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

[in] ObjectAttributes

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

傳回值

ZwOpenEvent 會傳回STATUS_SUCCESS或適當的錯誤狀態。此例程可能會傳回下列其中一個錯誤狀態代碼：

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

備註

ZwOpenEvent 會開啟現有的具名事件物件，並建立具有指定所需存取權之物件的句柄。

ZwOpenEvent 可以開啟通知或同步處理事件。

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

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

如果使用者模式中發生 ZwOpenEvent 函式的呼叫，您應該使用名稱「NtOpenEvent」，而不是「ZwOpenEvent」。

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

規格需求

需求	值
目標平台	Universal
標頭	wdm.h (包含 Wdm.h)
程式庫	NtosKrnl.lib
Dll	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI 合規性規則	HwStorPortProhibitedDIS (storport) 、 PowerIrpDDis (wdm)