CreateEventA 函式 (synchapi.h)

發行項
03/05/2024

建立或開啟具名或未命名的事件物件。

若要指定物件的存取遮罩，請使用 CreateEventEx 函式。

語法

HANDLE CreateEventA(
  [in, optional] LPSECURITY_ATTRIBUTES lpEventAttributes,
  [in]           BOOL                  bManualReset,
  [in]           BOOL                  bInitialState,
  [in, optional] LPCSTR                lpName
);

參數

[in, optional] lpEventAttributes

SECURITY_ATTRIBUTES 結構的指標。如果此參數為 NULL，子進程就無法繼承句柄。

結構的 lpSecurityDescriptor 成員會指定新事件的安全性描述符。如果 lpEventAttributes 為 NULL，事件會取得預設的安全性描述元。事件的預設安全性描述元中的 ACL 來自建立者的主要或模擬令牌。

[in] bManualReset

如果此參數為 TRUE，此函式會建立手動重設事件物件，這需要使用 ResetEvent 函式將事件狀態設定為非ignaled。如果此參數為 FALSE，此函式會建立自動重設事件物件，而且系統會在釋放單一等候線程之後，自動將事件狀態重設為未簽署。

[in] bInitialState

如果此參數為 TRUE，則會發出事件物件的初始狀態訊號;否則，則為非ignaled。

[in, optional] lpName

事件物件的名稱。名稱限制為 MAX_PATH 個字元。名稱比較區分大小寫。

如果 lpName 符合現有具名事件物件的名稱，此函式會要求 EVENT_ALL_ACCESS 訪問許可權。在此情況下， 系統會忽略 bManualReset 和 bInitialState 參數，因為它們已經由建立進程設定。如果 lpEventAttributes 參數不是 NULL，它會判斷是否可以繼承句柄，但會忽略其安全性描述元成員。

如果 lpName 為 NULL，則會建立事件物件，而不需要名稱。

如果 lpName 符合相同命名空間中另一種對象的名稱， (例如現有的號誌、mutex、可等候定時器、作業或檔案對應物件) ，則函式會失敗，而且 GetLastError 函式會傳回 ERROR_INVALID_HANDLE。這是因為這些對象共用相同的命名空間。

名稱可以有「Global」或「Local」前置詞，以在全域或會話命名空間中明確建立物件。名稱的其餘部分可以包含反斜杠字元 (\) 以外的任何字元。如需詳細資訊，請參閱核心物件命名空間。使用終端機服務會話實作快速使用者切換。核心物件名稱必須遵循終端機服務概述的指導方針，讓應用程式可以支援多個使用者。

物件可以在私用命名空間中建立。如需詳細資訊，請參閱物件命名空間。

傳回值

如果函式成功，則傳回值是事件物件的句柄。如果具名事件物件存在於函數調用之前，函式會傳回現有物件的句柄，而 GetLastError 會 傳回ERROR_ALREADY_EXISTS。

如果函式失敗，傳回值為 NULL。若要取得擴充的錯誤資訊，請呼叫 GetLastError。

備註

CreateEvent 傳回的句柄具有EVENT_ALL_ACCESS訪問許可權;它可用於任何需要事件物件句柄的函式，前提是呼叫端已獲得存取權。如果事件是從服務或模擬不同使用者的線程建立，您可以在建立事件時將安全性描述符套用至事件，或藉由變更其預設 DACL 來變更建立進程的預設安全性描述符。如需詳細資訊，請參閱同步處理物件安全性和訪問許可權。

呼叫進程的任何線程都可以在呼叫其中一個等候函式中指定事件物件句柄。當指定物件的狀態收到訊號時，單一物件等候函式會傳回。當有任何物件或發出所有指定物件的訊號時，可以指示多物件等候函式傳回。等候函式傳回時，會釋放等候線程以繼續執行。

事件物件的初始狀態是由 bInitialState 參數所指定。使用 SetEvent 函式，將事件物件的狀態設定為已發出訊號。使用 ResetEvent 函式，將事件物件的狀態重設為非ignaled。

當手動重設事件物件的狀態收到訊號時，它會維持訊號，直到它明確重設為 ResetEvent 函式未簽署為止。當物件的狀態發出訊號時，可以釋放任何數目的等候線程，或後續開始等候指定事件物件的等候作業的線程。

當自動重設事件物件的狀態收到訊號時，它會維持訊號，直到釋放單一等候線程為止;系統接著會自動將狀態重設為非簽署狀態。如果沒有執行緒在等候，事件物件的狀態會維持已收到信號。

多個進程可以有相同事件物件的句柄，讓對象能夠用於進程間同步處理。下列物件共享機制可供使用：

如果 CreateEventAttributes 參數已啟用 CreateEvent 繼承的 lpEventAttributes 參數，CreateProcess 函式所建立的子進程可以繼承事件物件的句柄。
進程可以在呼叫 DuplicateHandle 函式時指定事件物件句柄，以建立另一個進程可以使用的重複句柄。
進程可以在呼叫 OpenEvent 或 CreateEvent 函式時指定事件對象的名稱。

使用 CloseHandle 函式關閉句柄。當進程終止時，系統會自動關閉句柄。當最後一個句柄已關閉時，就會終結事件物件。

範例

如需使用 CreateEvent 的範例，請參閱使用事件物件。

注意

synchapi.h 標頭會將 CreateEvent 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

規格需求

需求	值
最低支援的用戶端	Windows XP [傳統型應用程式 \|UWP 應用程式]
最低支援的伺服器	Windows Server 2003 [傳統型應用程式 \|UWP 應用程式]
目標平台	Windows
標頭	synchapi.h (包含 Windows Server 2003、Windows Vista、Windows 7、Windows Server 2008 Windows Server 2008 R2)
程式庫	Kernel32.lib
DLL	Kernel32.dll