OpenWaitableTimerW 函式 (synchapi.h)

發行項
03/02/2024

開啟現有的具名可等候定時器物件。

語法

HANDLE OpenWaitableTimerW(
  [in] DWORD   dwDesiredAccess,
  [in] BOOL    bInheritHandle,
  [in] LPCWSTR lpTimerName
);

參數

[in] dwDesiredAccess

定時器物件的存取權。如果指定對象的安全性描述元不允許呼叫進程的要求存取權，函式就會失敗。如需訪問許可權的清單，請參閱同步處理物件安全性和訪問許可權。

[in] bInheritHandle

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

[in] lpTimerName

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

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

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

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

傳回值

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

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

備註

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

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

若要編譯使用此函式的應用程式，請將_WIN32_WINNT定義為 0x0400 或更新版本。如需詳細資訊，請參閱使用 Windows 標頭。

規格需求

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