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

另請參閱

REASON_CONTEXT

SetWaitableTimer