SetWaitableTimerEx 函式 (synchapi.h)
啟動指定的可等候計時器,並提供計時器的內容資訊。 當到期時間到達時,計時器會發出訊號,而設定計時器的執行緒會呼叫選擇性完成常式。
語法
BOOL SetWaitableTimerEx(
[in] HANDLE hTimer,
[in] const LARGE_INTEGER *lpDueTime,
[in] LONG lPeriod,
[in] PTIMERAPCROUTINE pfnCompletionRoutine,
[in] LPVOID lpArgToCompletionRoutine,
[in] PREASON_CONTEXT WakeContext,
[in] ULONG TolerableDelay
);
參數
[in] hTimer
計時器物件的控制碼。 CreateWaitableTimer或OpenWaitableTimer函式會傳回此控制碼。
控制碼必須具有 TIMER_MODIFY_STATE 存取權限。 如需詳細資訊,請參閱 同步處理物件安全性和存取權限。
[in] lpDueTime
計時器狀態設定為訊號的時間,間隔為 100 奈秒。 使用 FILETIME 結構所描述的格式。 正值表示絕對時間。 請務必使用以 UTC 為基礎的絕對時間,因為系統會在內部使用 UTC 型時間。 負值表示相對時間。 實際的計時器精確度取決於硬體的功能。 如需 UTC 型時間的詳細資訊,請參閱 系統時間。
[in] lPeriod
計時器的期間,以毫秒為單位。 如果 lPeriod 為零,計時器就會發出一次訊號。 如果 lPeriod 大於零,則計時器是週期性。 定期計時器會在每次經過期間時自動重新啟用,直到計時器使用CancelWaitableTimer 函式取消,或使用 SetWaitableTimerEx重設為止。 如果 lPeriod 小於零,則函式會失敗。
[in] pfnCompletionRoutine
選擇性完成常式的指標。 完成常式是 PTIMERAPCROUTINE 類型的應用程式定義函式,可在計時器發出訊號時執行。 如需計時器回呼函式的詳細資訊,請參閱 TimerAPCProc。 如需 APC 和執行緒集區執行緒的詳細資訊,請參閱。
[in] lpArgToCompletionRoutine
傳遞至完成常式之結構的指標。
[in] WakeContext
包含計時器內容資訊的 REASON_CONTEXT 結構的指標。
[in] TolerableDelay
到期時間的可容忍延遲,以毫秒為單位。
傳回值
如果函式成功,則傳回非零的值。
如果此函式失敗,則傳回值為零。 若要取得擴充的錯誤資訊,請呼叫 GetLastError。
備註
SetWaitableTimerEx函式類似于SetWaitableTimer函式,但SetWaitableTimerEx可用來指定內容字串,以及計時器到期的可容忍延遲。
若要編譯使用此函式的應用程式,請將_WIN32_WINNT定義為 0x0601 或更新版本。 如需詳細資訊,請參閱 使用 Windows 標頭。
計時器一開始為非作用中。 若要啟用計時器,請呼叫 SetWaitableTimerEx。 如果計時器在呼叫 SetWaitableTimerEx時已經作用中,則會停止計時器,則會重新啟用它。 以這種方式停止計時器並不會將計時器狀態設定為已發出訊號,因此在計時器上的等候作業中封鎖的執行緒仍會保持封鎖狀態。 不過,它會取消任何擱置的完成常式。
當指定的到期時間到達時,計時器會變成非使用中狀態,而選擇性 APC 會排入佇列至執行緒,如果尚未排入佇列的 APC,則會將計時器設定為執行緒。 計時器的狀態會設定為已發出訊號、使用指定的期間重新啟用計時器,以及當計時器進入可警示等候狀態時,設定計時器的執行緒會呼叫完成常式。 如需詳細資訊,請參閱 QueueUserAPC。 請注意,APC 不適用於執行緒集區執行緒的其他訊號機制,因為系統控制執行緒集區執行緒的存留期,因此執行緒可以在傳送通知之前終止。 不使用 pfnCompletionRoutine 參數或其他 APC 型訊號機制,而是使用可等候的物件,例如使用 CreateThreadpoolTimer建立的計時器。 針對 I/O,請使用以 CreateThreadpoolIo 或 hEvent為基礎的 OVERLAPPED 結構所建立的 I/O 完成物件,其中事件可以傳遞至 SetThreadpoolWait 函式。
如果設定計時器的執行緒終止且有相關聯的完成常式,則會取消計時器。 不過,計時器的狀態會保持不變。 如果沒有完成常式,則終止執行緒不會影響計時器。
當手動重設計時器設定為訊號狀態時,它會維持在這個狀態,直到呼叫 SetWaitableTimerEx 來重設計時器為止。 因此,定期手動重設計時器會在初始到期時間送達時設定為訊號狀態,並維持訊號直到重設為止。 當同步處理計時器設定為訊號狀態時,它會維持在這個狀態,直到執行緒完成計時器物件的等候作業為止。
如果系統時間已調整,則會調整任何未完成絕對計時器的到期時間。
如果呼叫 SetWaitableTimerEx 的執行緒結束時,就會取消計時器。 這會先停止計時器,再將其設定為訊號狀態,並取消未完成的 APC;它不會變更計時器的訊號狀態。
若要使用計時器來排程視窗的事件,請使用 SetTimer 函式。
規格需求
最低支援的用戶端 | Windows 7 [傳統型應用程式 |UWP 應用程式] |
最低支援的伺服器 | Windows Server 2008 R2 [傳統型應用程式 |UWP 應用程式] |
目標平台 | Windows |
標頭 | synchapi.h (包含 Windows.h) |
程式庫 | Kernel32.lib |
DLL | Kernel32.dll |
另請參閱
意見反應
https://aka.ms/ContentUserFeedback。
即將登場:在 2024 年,我們將逐步淘汰 GitHub 問題作為內容的意見反應機制,並將它取代為新的意見反應系統。 如需詳細資訊,請參閱:提交並檢視相關的意見反應