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 并生成新的计时器 ID。如果 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 可以重复使用计时器 ID。

当 uToleranceDelay 设置为 0 时，将使用系统默认计时器合并， SetCoalescableTimer 的行为与 SetTimer 相同。

在使用 SetCoalescableTimer 或其他计时器相关的函数之前，建议通过 SetUserObjectInformationW 函数将UOI_TIMERPROC_EXCEPTION_SUPPRESSION标志设置为 false，否则应用程序的行为可能不可预知，并可能容易受到安全漏洞的攻击。有关详细信息，请参阅 SetUserObjectInformationW。

要求


最低受支持的客户端	Windows 8 [仅限桌面应用]
最低受支持的服务器	Windows Server 2012 [仅限桌面应用]
目标平台	Windows
标头	winuser.h (包括 Windows.h)
Library	User32.lib
DLL	User32.dll
API 集	Windows 10版本 10.0.10 (240 中引入的 ext-ms-win-ntuser-window-l1-1-2)