SetWaitableTimer 函式 (synchapi.h)
啟動指定的可等候定時器。 當到期時間到達時，定時器會發出訊號，而設定定時器的線程會呼叫選擇性完成例程。
語法
BOOL SetWaitableTimer(
[in] HANDLE hTimer,
[in] const LARGE_INTEGER *lpDueTime,
[in] LONG lPeriod,
[in, optional] PTIMERAPCROUTINE pfnCompletionRoutine,
[in, optional] LPVOID lpArgToCompletionRoutine,
[in] BOOL fResume
);
參數
[in] hTimer
定時器物件的句柄。 CreateWaitableTimer 或 OpenWaitableTimer 函式會傳回此句柄。
句柄必須具有 TIMER_MODIFY_STATE 訪問許可權。 如需詳細資訊，請參閱 同步處理物件安全性和訪問許可權。
[in] lpDueTime
定時器狀態設定為訊號的時間，間隔為 100 奈秒。 使用 FILETIME 結構所描述的格式。 正值表示絕對時間。 請務必使用以UTC為基礎的絕對時間，因為系統會在內部使用UTC型時間。 負值表示相對時間。 實際的定時器精確度取決於硬體的功能。 如需UTC型時間的詳細資訊，請參閱 系統時間。
[in] lPeriod
定時器的期間，以毫秒為單位。 如果 lPeriod 為零，定時器就會發出一次訊號。 如果 lPeriod 大於零，則定時器是定期的。 定期定時器會在每次經過期間時自動重新啟用，直到定時器使用 CancelWaitableTimer 函式取消，或使用 SetWaitableTimer 重設為止。 如果 lPeriod 小於零，則函式會失敗。
[in, optional] pfnCompletionRoutine
選擇性完成例程的指標。 完成例程是 PTIMERAPCROUTINE 類型的應用程式定義函式，可在定時器發出訊號時執行。 如需定時器回呼函式的詳細資訊，請參閱 TimerAPCProc。 如需 APC 和線程集區線程的詳細資訊，請參閱。
[in, optional] lpArgToCompletionRoutine
傳遞至完成例程之結構的指標。
[in] fResume
如果此參數為 TRUE，當定時器狀態設定為已發出訊號時，會以暫停的電源壓縮模式還原系統。 否則，系統不會還原。 如果系統不支援還原，呼叫會成功，但 GetLastError 會傳回 ERROR_NOT_SUPPORTED。
傳回值
如果函式成功，則傳回非零的值。
如果此函式失敗，則傳回值為零。 若要取得擴充的錯誤資訊，請呼叫 GetLastError。
備註
定時器一開始為非作用中。 若要啟用定時器，請呼叫 SetWaitableTimer。 如果您呼叫 SetWaitableTimer 時定時器已經作用中，則會停止定時器，然後重新啟動定時器。 以這種方式停止定時器並不會將定時器狀態設定為已發出訊號，因此在定時器上的等候作業中封鎖的線程仍會保持封鎖狀態。 不過，它會取消任何擱置的完成例程。
當指定的到期時間到達時，定時器會變成非使用中狀態，而選擇性 APC 會排入佇列至線程，如果尚未排入佇列的 APC，則會將定時器設定為線程。 定時器的狀態會設定為已發出訊號、使用指定的期間重新啟用定時器，以及當定時器進入可警示等候狀態時，設定定時器的線程會呼叫完成例程。 如需詳細資訊，請參閱 QueueUserAPC。 請注意，APC 不適用於線程集區線程的其他訊號機制，因為系統控制線程集區線程的存留期，因此線程可以在傳送通知之前終止。 不使用 pfnCompletionRoutine 參數或其他 APC 型訊號機制，而是使用可等候的物件，例如使用 CreateThreadpoolTimer 建立的定時器。 針對 I/O，請使用以 CreateThreadpoolIo 或 hEvent 為基礎的 OVERLAPPED 結構所建立的 I/O 完成物件，其中事件可以傳遞至 SetThreadpoolWait 函式。
如果設定定時器的線程終止且有相關聯的完成例程，則會取消定時器。 不過，定時器的狀態會保持不變。 如果沒有完成例程，則終止線程不會影響定時器。
當手動重設定時器設定為訊號狀態時，它會維持在這個狀態，直到呼叫 SetWaitableTimer 來重設定時器為止。 因此，定期手動重設定時器會在初始到期時間送達時設定為訊號狀態，並維持訊號直到重設為止。 當同步處理定時器設定為訊號狀態時，它會維持在這個狀態，直到線程完成定時器物件的等候作業為止。
如果系統時間已調整，則會調整任何未完成絕對定時器的到期時間。
若要編譯使用此函式的應用程式，請將_WIN32_WINNT定義為 0x0400 或更新版本。 如需詳細資訊，請參閱 使用 Windows 標頭。
若要使用定時器來排程視窗的事件，請使用 SetTimer 函式。
處理定時器的 API 會使用各種不同的硬體時鐘。 這些時鐘的解析度可能與您預期的解析度明顯不同：某些時鐘可能會針對使用 RTC 型定時器晶片) 以 (毫秒為單位來測量，而針對使用 ACPI 或 TSC 計數器) 以 nanoseconds (測量的時鐘。 您可以使用 對 timeBeginPeriod 和 timeEndPeriod 函式的呼叫來變更 API 的解析。 您可以變更解析度的精確度取決於特定 API 所使用的硬體時鐘。 如需詳細資訊，請查看您的硬體檔。
範例
如需使用 SetWaitableTimer 的範例，請參閱 使用可等候的定時器物件。
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | Windows XP [傳統型應用程式 |UWP 應用程式] |
| 最低支援的伺服器 | Windows Server 2003 [傳統型應用程式 |UWP 應用程式] |
| 目標平台 | Windows |
| 標頭 | synchapi.h (Windows Server 2003、Windows Vista、Windows 7、Windows Server 2008 Windows Server 2008 R2) |
| 程式庫 | Kernel32.lib |
| DLL | Kernel32.dll |