SetThreadpoolTimerEx 函式 (threadpoolapiset.h)

發行項
03/02/2024

設定定時器物件，如果有的話，取代先前的定時器。背景工作線程會在指定的逾時到期之後呼叫定時器物件的回呼。

語法

BOOL SetThreadpoolTimerEx(
  [in, out]      PTP_TIMER pti,
  [in, optional] PFILETIME pftDueTime,
  [in]           DWORD     msPeriod,
  [in, optional] DWORD     msWindowLength
);

參數

[in, out] pti

定義要設定之定時器物件的 TP_TIMER 結構的指標。 CreateThreadpoolTimer 函式會傳回此指標。

[in, optional] pftDueTime

FILETIME 結構的指標，指定定時器到期的絕對或相對時間。如果此參數指向正值，則表示自1601年1月1日起的絕對時間 (UTC) ，以100奈秒單位測量。如果此參數指向負值，則表示相對於目前時間等候的時間量。如果此參數指向零，則定時器會立即到期。如需時間值的詳細資訊，請參閱檔案時間。

如果此參數為 NULL，定時器物件會停止將新的回呼排入佇列 (但已排入佇列的回呼仍會發生) 。

如果 pftDueTime 參數不是 NULL，就會設定定時器。

[in] msPeriod

定時器週期，以毫秒為單位。如果此參數為零，定時器就會發出一次訊號。如果此參數大於零，定時器會定期執行。定期定時器會在每次經過期間時自動重新啟用，直到定時器取消為止。

[in, optional] msWindowLength

系統在呼叫定時器回呼之前可能會延遲的時間上限。如果已設定此參數，系統就可以批次呼叫以節省電源。

傳回值

如果先前已設定定時器且已取消，則會傳回 TRUE。否則傳回 FALSE。

如果定時器的先前狀態為「設定」，而函式會傳回 FALSE，則回呼正在進行中或即將開始。如需進一步的討論，請參閱備註。

備註

設定定時器會取消先前的定時器，如果有的話。

在某些情況下，在應用程式關閉線程緩衝池定時器之後，可能會執行回呼函式。若要避免此行為，應用程式應遵循 CloseThreadpoolTimer 中所述的步驟。

如果 pftDueTime 指定的到期時間相對，系統花費在睡眠或休眠的時間不會計入定時器的到期日。當系統花費在喚醒狀態的累計時間量等於定時器的相對到期時間或期間時，定時器就會發出訊號。如果 pftDueTime 指定的到期時間是絕對的，系統花費在睡眠或休眠的時間會計入定時器的到期日。如果定時器在系統睡眠時到期，定時器會在系統喚醒時立即發出訊號。

若要編譯使用此函式的應用程式，請將_WIN32_WINNT定義為0x0600或更高版本。

範例

如需範例，請參閱使用線程集區函式。

規格需求

需求	值
最低支援的用戶端	Windows 8 [傳統型應用程式 \|UWP 應用程式]
最低支援的伺服器	Windows Server 2012 [傳統型應用程式 \|UWP 應用程式]
目標平台	Windows
標頭	threadpoolapiset.h
程式庫	Kernel32.lib
DLL	Kernel32.dll