CreateWaitableTimerW 函式 (synchapi.h)
建立或開啟可等候的定時器物件。
若要指定物件的存取遮罩,請使用 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 函式時指定定時器物件的名稱。
若要編譯使用此函式的應用程式,請將_WIN32_WINNT定義為 0x0400 或更新版本。 如需詳細資訊,請參閱 使用 Windows 標頭。
若要將定時器與視窗產生關聯,請使用 SetTimer 函 式。
範例
如需使用 CreateWaitableTimer 的範例,請參閱 使用可等候定時器物件。
規格需求
需求 | 值 |
---|---|
最低支援的用戶端 | Windows XP [傳統型應用程式 |UWP 應用程式] |
最低支援的伺服器 | Windows Server 2003 [傳統型應用程式 |UWP 應用程式] |
目標平台 | Windows |
標頭 | synchapi.h (包含 Windows.h) |
程式庫 | Kernel32.lib |
DLL | Kernel32.dll |