CreateEventW 函式 (synchapi.h)
建立或開啟具名或未命名的事件物件。
若要指定物件的存取遮罩,請使用 createEventEx 函式
語法
HANDLE CreateEventW(
[in, optional] LPSECURITY_ATTRIBUTES lpEventAttributes,
[in] BOOL bManualReset,
[in] BOOL bInitialState,
[in, optional] LPCWSTR lpName
);
參數
[in, optional] lpEventAttributes
SECURITY_ATTRIBUTES 結構的指標。 如果此參數 NULL,則子進程無法繼承句柄。
lpSecurityDescriptor 結構的成員會為新事件指定 安全性描述元。 如果 lpEventAttributesNULL,則事件會取得預設的安全性描述元。 事件的預設安全性描述元中的 ACL 來自建立者的主要或模擬令牌。
[in] bManualReset
如果此參數 TRUE,此函式會建立手動重設事件物件,因此需要使用 ResetEvent 函式,將事件狀態設定為非ignaled。 如果此參數 FALSE,則函式會建立自動重設事件物件,而且系統會在釋放單一等候線程之後,自動將事件狀態重設為未簽署。
[in] bInitialState
如果此參數 TRUE,則會發出事件物件的初始狀態;否則為非對齊。
[in, optional] lpName
事件物件的名稱。 名稱限制為 MAX_PATH 個字元。 名稱比較區分大小寫。
如果 lpName 符合現有具名事件對象的名稱,則此函式會要求 EVENT_ALL_ACCESS 訪問許可權。 在此情況下,bManualReset 和 bInitialState 參數會被忽略,因為它們已經由建立程序設定。 如果 lpEventAttributes 參數不是 NULL,它會判斷是否可以繼承句柄,但忽略其安全性描述元成員。
如果 lpNameNULL,則會建立事件物件,而沒有名稱。
如果
名稱可以有 「Global」 或 「Local」 前置詞,以明確在全域或會話命名空間中建立物件。 名稱的其餘部分可以包含反斜杠字元 (\) 以外的任何字元。 如需詳細資訊,請參閱 Kernel Object Namespaces。 使用終端機服務會話實作快速使用者切換。 核心物件名稱必須遵循終端機服務概述的指導方針,應用程式才能支援多個使用者。
物件可以在私人命名空間中建立。 如需詳細資訊,請參閱 物件命名空間。
傳回值
如果函式成功,傳回值就是事件物件的句柄。 如果具名事件物件存在於函數呼叫之前,函式會傳回現有物件的句柄,GetLastError 傳回 ERROR_ALREADY_EXISTS。
如果函式失敗,則傳回值 NULL。 若要取得擴充的錯誤資訊,請呼叫 GetLastError。
言論
CreateEvent 所傳回的句柄具有 EVENT_ALL_ACCESS 訪問許可權;它可以用於任何需要事件物件的句柄的函式中,前提是呼叫端已獲得存取權。 如果事件是從服務或模擬不同使用者的線程建立,您可以在建立事件時將安全性描述元套用至事件,或變更建立進程的預設安全性描述元,方法是變更其預設 DACL。 如需詳細資訊,請參閱 Synchronization Object Security and Access Rights。
呼叫行程的任何線程都可以在呼叫其中一個 等候函式時指定事件物件句柄,。 當指定物件的狀態發出訊號時,單一物件等候函式會傳回。 當任一物件或發出所有指定物件的訊號時,可以指示多物件等候函式傳回。 當等候函式傳回時,等候線程會釋放以繼續執行。
事件物件的初始狀態是由 bInitialState 參數
當手動重設事件物件的狀態收到訊號時,它會保持訊號,直到它明確重設為由 ResetEvent 函式所明確重設為非信號為止。 當物件的狀態發出訊號時,可以釋放任何數目的等候線程,或後續開始等候指定事件物件的等候作業的線程。
當自動重設事件物件的狀態收到訊號時,它會保持訊號,直到釋放單一等候線程為止;系統接著會自動將狀態重設為未簽署狀態。 如果沒有線程正在等候,事件對象的狀態會維持訊號。
多個進程可以有相同事件物件的句柄,讓對象能夠進行進程間同步處理。 下列物件共享機制可供使用:
CreateProcess 函式所建立的子進程,如果lpEventAttributes CreateEvent 啟用繼承的lpEventAttributes 參數,就可以繼承事件物件的句柄。 - 進程可以在呼叫 DuplicateHandle 函式中指定事件物件句柄,以建立另一個進程可以使用的重複句柄。
- 進程可以在呼叫 OpenEvent 或 CreateEvent 函式中指定事件對象的名稱。
例子
如需使用 createEvent
注意
synchapi.h 標頭會將 CreateEvent 定義為別名,根據 UNICODE 預處理器常數的定義,自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程序代碼,可能會導致編譯或運行時間錯誤不符。 如需詳細資訊,請參閱函式原型的
要求
要求 | 價值 |
---|---|
最低支援的用戶端 | Windows XP [傳統型應用程式 |UWP 應用程式] |
支援的最低伺服器 | Windows Server 2003 [傳統型應用程式 |UWP 應用程式] |
目標平臺 | 窗戶 |
標頭 | synchapi.h (包括 Windows Server 2003、Windows Vista、Windows 7、Windows Server 2008 Windows Server 2008 R2 上的 Windows.h) |
連結庫 | Kernel32.lib |
DLL | Kernel32.dll |