SetCoalescableTimer 函式 (winuser.h)

發行項
08/28/2023

建立具有指定逾時值和聯合容錯延遲的計時器。

語法

UINT_PTR SetCoalescableTimer(
  [in, optional] HWND      hWnd,
  [in]           UINT_PTR  nIDEvent,
  [in]           UINT      uElapse,
  [in, optional] TIMERPROC lpTimerFunc,
  [in]           ULONG     uToleranceDelay
);

參數

[in, optional] hWnd

類型： HWND

要與計時器相關聯的視窗控制碼。呼叫執行緒必須擁有此視窗。如果hWnd的Null值與現有計時器的nIDEvent一起傳入，則會以現有的非 Null hWnd計時器相同的方式來取代該計時器。

[in] nIDEvent

類型： UINT_PTR

計時器識別碼。如果 hWnd 參數為 Null，且 nIDEvent 不符合現有的計時器，則會忽略 nIDEvent 並產生新的計時器識別碼。如果 hWnd 參數不是 Null ，且 hWnd 指定的視窗已經有具有 nIDEvent值的計時器，則現有的計時器會由新的計時器取代。 當 SetCoalescableTimer取代計時器時，就會重設計時器。因此，訊息會在目前逾時值經過之後傳送，但會忽略先前設定的逾時值。如果呼叫不適合取代現有的計時器，則如果 hWnd為Null，則 nIDEvent應該是 0。

[in] uElapse

類型： UINT

逾時值 (以毫秒為單位)。

如果 uElapse 小於 USER_TIMER_MINIMUM (0x0000000A) ，則逾時會設定為 USER_TIMER_MINIMUM。如果 uElapse 大於 USER_TIMER_MAXIMUM (0x7FFFFFFF) ，則逾時會設定為 USER_TIMER_MAXIMUM。

如果 uElapse 和 uToleranceDelay 的總和超過 USER_TIMER_MAXIMUM，就會發生ERROR_INVALID_PARAMETER例外狀況。

[in, optional] lpTimerFunc

類型： TIMERPROC

當逾時值經過時，要通知函式的指標。如需函式的詳細資訊，請參閱 TimerProc。如果 lpTimerFunc 為 Null，系統會將 WM_TIMER 訊息張貼至應用程式佇列。訊息MSG結構的hwnd成員包含hWnd參數的值。

[in] uToleranceDelay

類型： ULONG

它可能是下列其中一個值：

值	意義
TIMERV_DEFAULT_COALESCING 0x00000000	使用系統預設計時器聯合。
TIMERV_NO_COALESCING 0xFFFFFFFF	不使用計時器聯合。使用這個值時，不論系統預設計時器聯合為何或應用程式相容性旗標為何，建立的計時器都不會聯合。注意除非您確定計時器不需要聯合，否則請勿使用此值。
0x1 - 0x7FFFFFF5	指定以毫秒為單位的聯合容錯延遲。應用程式應該將此值設定為系統預設 (TIMERV_DEFAULT_COALESCING) 或可能的最大值。如果 uElapse 和 uToleranceDelay 的總和超過 USER_TIMER_MAXIMUM (0x7FFFFFFF) ，就會發生ERROR_INVALID_PARAMETER例外狀況。如需詳細資料和最佳做法，請參閱 Windows 計時器聯合。
任何其他值	無效的值。如果 uToleranceDelay 設定為不正確值，則函式會失敗並傳回零。

傳回值

類型： UINT_PTR

如果函式成功且 hWnd 參數為 Null，則傳回值是識別新計時器的整數。應用程式可以將此值傳遞至 KillTimer 函式，以終結計時器。

如果函式成功且 hWnd 參數不是 Null，則傳回值為非零整數。應用程式可以將 nIDEvent 參數的值傳遞至 KillTimer 函式，以終結計時器。

如果函式無法建立計時器，則傳回值為零。若要取得擴充的錯誤資訊，請呼叫 GetLastError。

備註

應用程式可以在視窗程式中加入WM_TIMER case 語句，或在建立計時器時指定TimerProc回呼函式，來處理WM_TIMER訊息。當您指定 TimerProc 回呼函式時，預設視窗過程會在處理 WM_TIMER時呼叫回呼函式。因此，即使您使用 TimerProc 而不是處理 WM_TIMER，您也需要在呼叫執行緒中分派訊息。

WM_TIMER訊息的wParam參數包含nIDEvent參數的值。

計時器識別碼 nIDEvent專屬於相關聯的視窗。另一個視窗可以有自己的計時器，其識別碼與另一個視窗所擁有的計時器相同。計時器是相異的。

當hWnd為Null時，SetTimer可以重複使用計時器識別碼。

當 uToleranceDelay設定為 0 時，會使用系統預設計時器聯合，而 SetCoalescableTimer的行為與SetTimer相同。

在使用SetCoalescableTimer或其他計時器相關函式之前，建議您透過SetUserObjectInformationW函式將UOI_TIMERPROC_EXCEPTION_SUPPRESSION旗標設定為false，否則應用程式可能會發生無法預期的行為，而且可能會容易受到安全性惡意探索。如需詳細資訊，請參閱 SetUserObjectInformationW。

規格需求


最低支援的用戶端	Windows 8 [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2012 [僅限傳統型應用程式]
目標平台	Windows
標頭	winuser.h (包括 Windows.h)
程式庫	User32.lib
Dll	User32.dll
API 集合	ext-ms-win-ntuser-window-l1-1-2 (于 Windows 10 10.0.10240 版)