CreateWaitableTimerW 函式 (synchapi.h)

發行項
03/02/2024

建立或開啟可等候的定時器物件。

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

語法

HANDLE CreateWaitableTimerW(
  [in, optional] LPSECURITY_ATTRIBUTES lpTimerAttributes,
  [in]           BOOL                  bManualReset,
  [in, optional] LPCWSTR               lpTimerName
);

參數

[in, optional] lpTimerAttributes

SECURITY_ATTRIBUTES 結構的指標，指定新定時器物件的安全性描述項，並判斷子進程是否可以繼承傳回的句柄。

如果 lpTimerAttributes 為 NULL，定時器物件會取得預設的安全性描述元，而且無法繼承句柄。定時器預設安全性描述元中的 ACL 來自建立者的主要或模擬令牌。

[in] bManualReset

如果此參數為 TRUE，則定時器為手動重設通知定時器。否則，定時器是同步處理定時器。

[in, optional] lpTimerName

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

如果 lpTimerName 為 NULL，則會在沒有名稱的情況下建立定時器物件。

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

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

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

傳回值

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

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

備註

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

呼叫進程的任何線程都可以在呼叫其中一個等候函式中指定定時器物件句柄。

多個進程可以有相同定時器物件的句柄，讓對象能夠用於進程間同步處理。

如果 CreateWaitableTimer 的 lpTimerAttributes 參數啟用繼承，CreateProcess 函式所建立的進程可以繼承定時器物件的句柄。
進程可以在對 DuplicateHandle 函式的呼叫中指定定時器物件句柄。產生的句柄可由另一個進程使用。
進程可以在呼叫 OpenWaitableTimer 或 CreateWaitableTimer 函式時指定定時器物件的名稱。

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

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

若要將定時器與視窗產生關聯，請使用 SetTimer 函式。

範例

如需使用 CreateWaitableTimer 的範例，請參閱使用可等候定時器物件。

規格需求

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