共用方式為

CreateEventExA 函式 (synchapi.h)

  • 發行項

建立或開啟具名或未命名的事件物件，並傳回物件的控制碼。

語法

HANDLE CreateEventExA(
  [in, optional] LPSECURITY_ATTRIBUTES lpEventAttributes,
  [in, optional] LPCSTR                lpName,
  [in]           DWORD                 dwFlags,
  [in]           DWORD                 dwDesiredAccess
);

參數

[in, optional] lpEventAttributes

SECURITY_ATTRIBUTES結構的指標。 如果 lpEventAttributes 為 Null，子進程就無法繼承事件控制碼。

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

[in, optional] lpName

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

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

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

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

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

[in] dwFlags

此參數可以是下列一或多個值。

值 意義
CREATE_EVENT_INITIAL_SET
0x00000002
 事件物件的初始狀態會發出訊號;否則，不會進行簽署。
CREATE_EVENT_MANUAL_RESET
0x00000001
 您必須使用 ResetEvent 函式手動重設事件。 當物件的狀態收到訊號時，可以釋放任何數目的等候執行緒，或後續開始等候指定事件物件的等候作業的執行緒。

如果未指定此旗標，系統會在釋放單一等候執行緒之後自動重設事件。

[in] dwDesiredAccess

事件物件的存取遮罩。 如需存取權限的清單，請參閱 同步處理物件安全性和存取權限。

傳回值

如果函式成功，則傳回值是事件物件的控制碼。 如果具名事件物件存在於函式呼叫之前，函式會傳回現有物件的控制碼，而 GetLastError 會傳回 ERROR_ALREADY_EXISTS。

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

備註

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

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

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

多個進程可以擁有相同事件物件的控制碼，讓物件能夠進行進程間同步處理。 下列物件共用機制可供使用：

  • 如果CreateEvent啟用繼承的lpEventAttributes參數，CreateProcess函式所建立的子進程可以繼承事件物件的控制碼。
  • 進程可以在呼叫 DuplicateHandle 函式時指定事件物件控制碼，以建立另一個進程可以使用的重複控制碼。
  • 進程可以在呼叫 OpenEvent 或 CreateEvent 函式時指定事件物件的名稱。
使用 CloseHandle 函式 關閉控制碼。 系統會在進程終止時自動關閉控制碼。 當最後一個控制碼已關閉時，就會終結事件物件。

注意

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

規格需求

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

另請參閱

CloseHandle

事件物件

物件名稱

同步處理函式