CreateMutexExA 函式 (synchapi.h)

  • 發行項

建立或開啟具名或未命名的 Mutex 物件，並傳回物件的句柄。

語法

HANDLE CreateMutexExA(
  [in, optional] LPSECURITY_ATTRIBUTES lpMutexAttributes,
  [in, optional] LPCSTR                lpName,
  [in]           DWORD                 dwFlags,
  [in]           DWORD                 dwDesiredAccess
);

參數

[in, optional] lpMutexAttributes

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

結構的 lpSecurityDescriptor 成員會指定新 Mutex 的安全性描述元。 如果 lpMutexAttributes 為 NULL，Mutex 會取得預設的安全性描述元。 Mutex 的預設安全性描述元中的 ACL 來自建立者的主要或模擬令牌。 如需詳細資訊，請參閱 同步處理物件安全性和訪問許可權。

[in, optional] lpName

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

如果 lpName 為 NULL，則會在沒有名稱的情況下建立 Mutex 物件。

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

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

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

[in] dwFlags

此參數可以是 0 或下列值。

值 意義
CREATE_MUTEX_INITIAL_OWNER
0x00000001
 物件建立者是 mutex 的初始擁有者。

[in] dwDesiredAccess

Mutex 物件的存取掩碼。 如需訪問許可權的清單，請參閱 同步處理物件安全性和訪問許可權。

傳回值

如果函式成功，則傳回值是新建立 Mutex 物件的句柄。

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

如果 mutex 是具名 mutex，而且物件存在於此函數調用之前，傳回值就是現有物件的句柄，而 GetLastError 函 式會 傳回ERROR_ALREADY_EXISTS。

備註

如果您使用具名 Mutex 將應用程式限制為單一實例，惡意使用者可以先建立此 Mutex，再執行並防止應用程式啟動。 若要避免這種情況，請建立隨機命名的 mutex 並儲存名稱，使其只能由授權的使用者取得。 或者，您可以針對此目的使用檔案。 若要將您的應用程式限制為每個使用者一個實例，請在使用者的配置檔目錄中建立鎖定的檔案。

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

當 Mutex 物件不是由任何線程擁有時，就會發出訊號。 建立線程可以使用 dwFlags 參數來要求 mutex 的立即擁有權。 否則，線程必須使用其中一個等候函式來要求擁有權。 當 mutex 的狀態發出訊號時，會授與一個等候線程擁有權、mutex 的狀態變更為非簽署，而 wait 函式會傳回。 在任何指定時間，只有一個線程可以擁有 Mutex。 擁有線程會使用 ReleaseMutex 函式來釋放其擁有權。

擁有 mutex 的線程可以在重複的等候函式呼叫中指定相同的 mutex，而不會封鎖其執行。 一般而言，您不會重複等候相同的 Mutex，但此機制會防止線程在等候已經擁有的 mutex 時自行死結。 不過，若要釋放其擁有權，線程必須在每次 mutex 滿足等候時呼叫 ReleaseMutex 一次。

兩個或多個進程可以呼叫 CreateMutex 來建立相同的具名 mutex。 第一個程序實際上會建立 mutex，而後續具有足夠訪問許可權的進程只會開啟現有 Mutex 的句柄。 這可讓多個進程取得相同 Mutex 的句柄，同時減輕使用者負責確保先啟動建立程式的責任。 使用這項技術時，您不應該使用 CREATE_MUTEX_INITIAL_OWNER 旗標;否則，很難確定哪些程式具有初始擁有權。

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

  • 如果 CreateMutexAttributes 參數已啟用 CreateMutex 繼承的 lpMutexAttributes 參數，CreateProcess 函式所建立的子進程可以繼承 mutex 物件的句柄。 此機制適用於具名和未命名的 Mutex。
  • 進程可以在呼叫 DuplicateHandle 函式時指定 mutex 物件的句柄，以建立另一個進程可以使用的重複句柄。 此機制適用於具名和未命名的 Mutex。
  • 進程可以在呼叫 [OpenMutex] (./nf-synchapi-openmutexw.md) 或 CreateMutex 函式中指定具名 mutex，以擷取 mutex 物件的句柄。
使用 CloseHandle 函式關閉句柄。 當進程終止時，系統會自動關閉句柄。 當最後一個句柄已關閉時，Mutex 物件就會終結。

注意

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

規格需求

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

另請參閱

CloseHandle

Mutex 物件

同步處理函式