SetThreadpoolTimerEx 函式 (threadpoolapiset.h)

設定計時器物件,並取代先前的計時器,如果有的話。 背景工作執行緒會在指定的逾時到期後呼叫計時器物件的回呼。

語法

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。

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

備註

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

在某些情況下,回呼函式可能會在應用程式關閉執行緒集區計時器之後執行。 若要避免此行為,應用程式應遵循 CloseThreadpoolTimer中所述的步驟。

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

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

範例

如需範例,請參閱 使用執行緒集區函式

規格需求

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

另請參閱

CloseThreadpoolTimer

CreateThreadpoolTimer

IsThreadpoolTimerSet

執行緒集區

WaitForThreadpoolTimerCallbacks