SetWaitableTimer 函式 (synchapi.h)

發行項
03/09/2024

啟動指定的可等候定時器。當到期時間到達時，定時器會發出訊號，而設定定時器的線程會呼叫選擇性完成例程。

語法

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