SetTimer 函数 (winuser.h)

项目
04/06/2023

创建具有指定超时值的计时器。

语法

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

参数

[in, optional] hWnd

类型：HWND

要与计时器关联的窗口的句柄。此窗口必须由调用线程拥有。如果 hWnd 的 NULL 值与现有计时器的 nIDEvent 一起传入，则替换该计时器的方式与现有非 NULL hWnd 计时器相同。

[in] nIDEvent

类型： UINT_PTR

非零计时器标识符。如果 hWnd 参数为 NULL，并且 nIDEvent 与现有计时器不匹配，则忽略它并生成新的计时器 ID。如果 hWnd 参数不为 NULL ，并且 hWnd 指定的窗口已有一个值为 nIDEvent 的计时器，则现有计时器将替换为新的计时器。 当 SetTimer 替换计时器时，计时器将重置。因此，将在当前超时值过后发送消息，但忽略以前设置的超时值。如果调用不打算替换现有计时器，则如果 hWnd 为 NULL，则 nIDEvent 应为 0。

[in] uElapse

类型： UINT

超时值（以毫秒为单位）。

如果 uElapse 小于 USER_TIMER_MINIMUM (0x0000000A) ，则超时设置为 USER_TIMER_MINIMUM。如果 uElapse 大于 USER_TIMER_MAXIMUM (0x7FFFFFFF) ，则超时设置为 USER_TIMER_MAXIMUM。

[in, optional] lpTimerFunc

类型： TIMERPROC

指向在超时值过后要通知的函数的指针。有关函数的详细信息，请参阅 TimerProc。如果 lpTimerFunc 为 NULL，系统会将 WM_TIMER 消息发布到应用程序队列。消息的 MSG 结构的 hwnd 成员包含 hWnd 参数的值。

返回值

类型： UINT_PTR

如果函数成功且 hWnd 参数为 NULL，则返回值为标识新计时器的整数。应用程序可以将此值传递给 KillTimer 函数以销毁计时器。

如果函数成功且 hWnd 参数不为 NULL，则返回值为非零整数。应用程序可以将 nIDEvent 参数的值传递给 KillTimer 函数以销毁计时器。

如果函数无法创建计时器，则返回值为零。要获得更多的错误信息，请调用 GetLastError。

注解

应用程序可以通过在窗口过程中包括WM_TIMER case 语句或在创建计时器时指定 TimerProc 回调函数来处理WM_TIMER消息。指定 TimerProc 回调函数时，DispatchMessage 会在使用非 NULL lParam 处理 WM_TIMER 时调用回调函数，而不是调用窗口过程。因此，即使在使用 TimerProc 而不是处理 WM_TIMER时，也需要在调用线程中调度消息。

WM_TIMER消息的 wParam 参数包含 nIDEvent 参数的值。

计时器标识符 nIDEvent 特定于关联的窗口。另一个窗口可以有自己的计时器，其标识符与另一个窗口拥有的计时器相同。计时器是不同的。

如果 hWnd 为 NULL，SetTimer 可以重复使用计时器 ID。

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

示例

有关示例，请参阅创建计时器。

要求

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