OpenMutexW 函式 (synchapi.h)

發行項
03/09/2024

開啟現有的具名 mutex 物件。

語法

HANDLE OpenMutexW(
  [in] DWORD   dwDesiredAccess,
  [in] BOOL    bInheritHandle,
  [in] LPCWSTR lpName
);

參數

[in] dwDesiredAccess

Mutex 物件的存取權。只有 SYNCHRONIZE 訪問許可權才能使用 Mutex;若要變更 mutex 的安全性，請指定 MUTEX_ALL_ACCESS。如果指定對象的安全性描述元不允許呼叫進程的要求存取權，函式就會失敗。如需訪問許可權的清單，請參閱同步處理物件安全性和訪問許可權。

[in] bInheritHandle

如果此值為 TRUE，此進程所建立的進程將會繼承句柄。否則，進程不會繼承這個句柄。

[in] lpName

要開啟的 Mutex 名稱。名稱比較會區分大小寫。

此函式可以在私人命名空間中開啟物件。如需詳細資訊，請參閱物件命名空間。

終端機服務： 名稱可以有「Global」或「Local」前置詞，以在全域或會話命名空間中明確開啟物件。名稱的其餘部分可以包含任何字元，但反斜杠字元 (\) 除外。如需詳細資訊，請參閱核心物件命名空間。

注意使用終端機服務會話實作快速使用者切換。第一個登入的使用者會使用會話 0、下一個登入的使用者會使用會話 1 等等。核心物件名稱必須遵循終端機服務概述的指導方針，讓應用程式可以支援多個使用者。

傳回值

如果函式成功，則傳回值是 mutex 物件的句柄。

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

如果具名 mutex 不存在，則函式會失敗，而且 GetLastError 會傳回 ERROR_FILE_NOT_FOUND。

備註

OpenMutex 函式可讓多個進程開啟相同 mutex 物件的句柄。只有在某些進程已經使用 CreateMutex 函式建立 Mutex 時，函式才會成功。呼叫進程可以在任何需要 mutex 物件的句柄的函式中使用傳回的句柄，例如 wait 函式，受限於 dwDesiredAccess 參數中指定的存取限制。

您可以使用 DuplicateHandle 函式來複製句柄。使用 CloseHandle 函式關閉句柄。系統會在進程終止時自動關閉句柄。當最後一個句柄關閉時，Mutex 物件就會終結。

如果您的多線程應用程式必須重複建立、開啟和關閉具名 mutex 物件，可能會發生競爭狀況。在此情況下，最好使用 CreateMutex 而不是 OpenMutex，因為 CreateMutex 會在不存在時開啟 Mutex 並建立它。

範例

如需使用 OpenMutex 的範例，請參閱使用具名物件。

規格需求

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