共用方式為

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 訪問許可權。 如需詳細資訊，請參閱 Synchronization Object Security and Access Rights。

[in] lpDueTime

定時器狀態在 100 奈秒間隔內設定為訊號的時間。 使用 FILETIME 結構中所述的格式。 正值表示絕對時間。 請務必使用以UTC為基礎的絕對時間，因為系統會在內部使用以UTC為基礎的時間。 負值表示相對時間。 實際的定時器精確度取決於硬體的功能。 如需 UTC 型時間的詳細資訊，請參閱 系統時間。

Windows XP、Windows Server 2003、Windows Vista、Windows 7、Windows Server 2008 和 Windows Server 2008 R2： 如果指定相對時間，定時器會包含花費在低功率狀態的時間。 例如，當計算機處於睡眠狀態時，定時器會繼續倒數。

Windows 8 和更新版本、Windows Server 2012 和更新版本： 如果指定相對時間，定時器不包含花費在低功率狀態的時間。 例如，當計算機處於睡眠狀態時，定時器不會繼續倒數。

[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 應用程式]
目標平臺 窗戶
標頭 synchapi.h （包括 Windows.h）
連結庫 Kernel32.lib
DLL Kernel32.dll

另請參閱

REASON_CONTEXT

SetWaitableTimer