IoCreateSynchronizationEvent 函式 (wdm.h)

  • 發行項

IoCreateSynchronizationEvent 例程會建立或開啟具名同步處理事件，以用於串行化兩個不相關的驅動程式之間的硬體存取。

語法

PKEVENT IoCreateSynchronizationEvent(
  [in]  PUNICODE_STRING EventName,
  [out] PHANDLE         EventHandle
);

參數

[in] EventName

緩衝區的指標，其中包含名稱為事件的 Null 終止 Unicode 字串。

[out] EventHandle

要傳回事件物件句柄的位置指標。 在 Windows Server 2003 和更新版本的 Windows 中，傳回的句 柄是核心句柄。

傳回值

IoCreateSynchronizationEvent 會傳回已建立或開啟之事件物件的指標，如果無法建立或開啟事件物件，則為 NULL 。

備註

如果事件物件不存在，就會建立該物件。 IoCreateSynchronizationEvent 會將新同步處理事件的狀態設定為 Signaled。 如果事件對象已經存在，則只會開啟它。 使用同步處理事件呼叫 KeWaitForSingleObject 與這個例程傳回之 PKEVENT 指標的驅動程式配對。

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

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

在使用者模式和核心模式之間共用事件物件需要小心。 共用事件物件有兩個主要方法：

  • 使用者模式應用程式會建立事件物件，並將句柄傳遞至驅動程式，方法是將IOCTL傳送至驅動程式。 驅動程式必須在建立事件對象的進程內容中處理IOCTL，而且必須呼叫 ObReferenceObjectByHandle 來驗證句柄。 此方法是共用使用者與核心模式之間事件對象的建議方法。

  • 驅動程式會在全域 \BaseNamedObjects 對象目錄中建立具名事件物件。 若要從使用者模式存取核心模式事件，請使用名稱 Global\\Xxx。 請注意，安全性設定可防止應用程式開啟事件。 在 Microsoft Win32 子系統初始化之前，不會建立 \BaseNamedObjects 對象目錄，因此在開機時載入的驅動程式無法在其 DriverEntry 例程的 \BaseNamedObjects 目錄中建立事件物件

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

規格需求

需求 值
最低支援的用戶端 從 Windows 2000 開始提供。
目標平台 Universal
標頭 wdm.h (包含 Ntddk.h)
程式庫 NtosKrnl.lib
Dll NtosKrnl.exe
IRQL PASSIVE_LEVEL
DDI 合規性規則 HwStorPortProhibitedDDIs (storport) 、 IrqlIoPassive4 (wdm) 、 PowerIrpDDis (wdm)

另請參閱

IoCreateNotificationEvent

KeWaitForSingleObject

RtlInitUnicodeString

ZwClose