Share via

createTimerQueueTimer 函式 (threadpoollegacyapiset.h)

  • 發行項

建立定時器佇列定時器。 此定時器會在指定的到期時間到期，然後在每個指定的期間之後到期。 定時器到期時，會呼叫回呼函式。

語法

BOOL CreateTimerQueueTimer(
  [out]          PHANDLE             phNewTimer,
  [in, optional] HANDLE              TimerQueue,
  [in]           WAITORTIMERCALLBACK Callback,
  [in, optional] PVOID               Parameter,
  [in]           DWORD               DueTime,
  [in]           DWORD               Period,
  [in]           ULONG               Flags
);

參數

[out] phNewTimer

緩衝區的指標，接收傳回定時器佇列定時器的句柄。 當此句柄已過期且不再需要時，請呼叫 DeleteTimerQueueTimer 加以釋放。

[in, optional] TimerQueue

定時器佇列的句柄。 CreateTimerQueue 函式會傳回此句柄。

如果此參數為 NULL，則定時器會與預設定時器佇列相關聯。

[in] Callback

在定時器到期時要執行 之 WAITORTIMERCALLBACK 類型的應用程式定義函式指標。 如需詳細資訊，請參閱 WaitOrTimerCallback。

[in, optional] Parameter

將傳遞至回調函式的單一參數值。

[in] DueTime

相對於第一次發出定時器訊號之前必須經過的目前時間，以毫秒為單位的時間量。

[in] Period

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

[in] Flags

此參數可以是 WinNT.h 的下列一或多個值。

值 意義
WT_EXECUTEDEFAULT
0x00000000
 根據預設，回呼函式會排入佇列至非 I/O 背景工作線程。
WT_EXECUTEINTIMERTHREAD
0x00000020
 定時器線程本身會叫用回呼函式。 此旗標只應用於簡短工作，或可能會影響其他定時器作業。

回呼函式會排入隊列為 APC。 它不應該執行可警示的等候作業。
WT_EXECUTEINIOTHREAD
0x00000001
 未使用這個旗標。

Windows Server 2003 和 Windows XP： 回呼函式會排入佇列至 I/O 背景工作線程。 如果函式應在等候處於可警示狀態的線程中執行，則應該使用此旗標。

從 Windows Vista 和 Windows Server 2008 開始，已移除 I/O 背景工作線程。
WT_EXECUTEINPERSISTENTTHREAD
0x00000080
 回呼函式會排入永遠不會終止的線程。 它不保證每次都使用相同的線程。 此旗標只應用於簡短工作，或可能會影響其他定時器作業。

如果線程呼叫使用 APC 的函式，就必須設定此旗標。 如需詳細資訊，請參閱 異步過程調用。

請注意，目前沒有任何背景工作線程真正持續存在，不過沒有任何背景工作線程會在有任何擱置的 I/O 要求時終止。
WT_EXECUTELONGFUNCTION
0x00000010
 回呼函式可以執行長時間等候。 此旗標可協助系統決定是否應該建立新的線程。
WT_EXECUTEONLYONCE
0x00000008
 定時器只會設定為發出訊號的狀態一次。 如果設定此旗標， Period 參數必須是零。
WT_TRANSFER_IMPERSONATION
0x00000100
 回呼函式會使用目前的存取令牌，無論是進程或模擬令牌。 如果未指定此旗標，回呼函式只會以進程令牌執行。

Windowsxp： 在 Windows XP SP2 和 Windows Server 2003 之前，不支援此旗標。

傳回值

如果函式成功，則傳回非零的值。

如果此函式失敗，則傳回值為零。 若要取得擴充的錯誤資訊，請呼叫 GetLastError。

備註

如果 DueTime 和 Period 參數都是非零的，定時器會先在到期時間發出訊號，然後定期發出訊號。 每次期間經過時都會呼叫回呼，不論先前的回呼是否已完成執行。 回呼函式會排入佇列至線程集區。 這些線程受限於排程延遲，因此時間可能會因應用程式或系統發生的情況而有所不同。

系統花費在睡眠或休眠的時間不會計入定時器的到期時間。 當系統花費在喚醒狀態的累計時間量符合定時器到期時間或期間時，就會發出定時器訊號。

Windows Server 2003 和 Windows XP： 系統在睡眠或休眠中花費的時間會計入定時器的到期時間。 如果定時器在系統睡眠時到期，定時器會在系統喚醒時立即發出訊號。

若要取消定時器，請呼叫 DeleteTimerQueueTimer 函 式。 若要取消定時器佇列中的所有定時器，請呼叫 DeleteTimerQueueEx 函 式。

根據預設，線程集區最多有500個線程。 若要提高此限制，請使用 WinNT.h 中定義的 WT_SET_MAX_THREADPOOL_THREAD 宏。

#define WT_SET_MAX_THREADPOOL_THREADS(Flags,Limit) \
    ((Flags)|=(Limit)<<16)

指定 Flags 參數時，請使用這個宏。 宏參數是所需的旗標，而新的限制 (最多 (2<<16 個) -1 個線程) 。 不過，請注意，您的應用程式可以藉由讓背景工作線程數目保持低，以改善其效能。

若要編譯使用此函式的應用程式，請將 _WIN32_WINNT 定義為0x0500或更新版本。 如需詳細資訊，請參閱 使用 Windows 標頭。

範例

如需使用 CreateTimerQueueTimer 的範例，請參閱 使用定時器佇列。

規格需求

需求 值
最低支援的用戶端 Windows XP [僅限傳統型應用程式]
最低支援的伺服器 Windows Server 2003 [僅限桌面應用程式]
目標平台 Windows
標頭 threadpoollegacyapiset.h
程式庫 Kernel32.lib
DLL Kernel32.dll

另請參閱

CreateTimerQueue

DeleteTimerQueueEx

DeleteTimerQueueTimer

同步處理函式

執行緒共用

定時器佇列