SetWaitableTimer 函数（synchapi.h）

项目
11/18/2024

激活指定的可等待计时器。当到期时间到达时，计时器将发出信号，设置计时器的线程将调用可选的完成例程。

语法

BOOL SetWaitableTimer(
  [in]           HANDLE              hTimer,
  [in]           const LARGE_INTEGER *lpDueTime,
  [in]           LONG                lPeriod,
  [in, optional] PTIMERAPCROUTINE    pfnCompletionRoutine,
  [in, optional] LPVOID              lpArgToCompletionRoutine,
  [in]           BOOL                fResume
);

参数

[in] hTimer

计时器对象的句柄。 CreateWaitableTimer 或 OpenWaitableTimer 函数返回此句柄。

句柄必须具有 TIMER_MODIFY_STATE 访问权限。有关详细信息，请参阅同步对象安全和访问权限。

[in] lpDueTime

计时器状态设置为信号的时间（以 100 纳秒为单位）。使用 FILETIME 结构描述的格式。正值表示绝对时间。请确保使用基于 UTC 的绝对时间，因为系统在内部使用基于 UTC 的时间。负值指示相对时间。实际的计时器准确性取决于硬件的功能。有关基于 UTC 的时间的详细信息，请参阅系统时间。

Windows XP、Windows Server 2003、Windows Vista、Windows 7、Windows Server 2008 和 Windows Server 2008 R2： 如果指定相对时间，计时器包括处于低功率状态的时间。例如，计时器在计算机处于睡眠状态时继续倒计时。

Windows 8 及更新版本、Windows Server 2012 及更新版本： 如果指定相对时间，计时器不包括在低功率状态下花费的时间。例如，当计算机处于睡眠状态时，计时器不会继续倒计时。

[in] lPeriod

计时器的时间段（以毫秒为单位）。如果 lPeriod 为零，计时器将发出一次信号。如果 lPeriod 大于零，则计时器是定期的。定期计时器在时间段过后自动重新激活，直到使用 CancelWaitableTimer 函数取消计时器，或使用 setWaitableTimer 重置。如果 lPeriod 小于零，则函数将失败。

[in, optional] pfnCompletionRoutine

指向可选完成例程的指针。完成例程是 PTIMERAPCROUTINE 类型的应用程序定义函数， 在发出计时器信号时执行。有关计时器回调函数的详细信息，请参阅 TimerAPCProc。有关 APC 和线程池线程的详细信息，请参阅“备注”。

[in, optional] lpArgToCompletionRoutine

指向传递到完成例程的结构的指针。

[in] fResume

如果此参数 TRUE，则当计时器状态设置为信号时，还原处于挂起的节能模式的系统。否则，不会还原系统。如果系统不支持还原，则调用成功，但 GetLastError 返回 ERROR_NOT_SUPPORTED。

返回值

如果函数成功，则返回值为非零。

如果函数失败，则返回值为零。若要获取扩展的错误信息，请调用 GetLastError。

言论

计时器最初处于非活动状态。若要激活计时器，请调用 setWaitableTimer。如果在调用 SetWaitableTimer时计时器已处于活动状态，则会停止计时器，然后重新激活计时器。以这种方式停止计时器不会将计时器状态设置为已发出信号，因此在计时器上的等待操作中阻止的线程仍被阻止。但是，它会取消任何挂起的完成例程。

当指定的到期时间到达时，计时器变为非活动状态，并且可选的 APC 将排队到设置计时器的线程（如果没有尚未完成的 APC 已排队）。计时器的状态设置为信号，计时器使用指定的时间段重新激活计时器，而设置计时器的线程在进入可警报等待状态时将调用完成例程。有关详细信息，请参阅 QueueUserAPC。请注意，APC 不适用于线程池线程的其他信号机制，因为系统控制线程池线程的生存期，因此在传递通知之前，线程可以终止。使用 CreateThreadpoolTimer创建的计时器，而不是使用 pfnCompletionRoutine 参数或其他基于 APC 的信号机制。对于 I/O，请使用通过 CreateThreadpoolIo 创建的 I/O 完成对象或基于 hEvent的 OVERLAPPED 结构，在该结构中可以将事件传递给 SetThreadpoolWait 函数。

如果设置计时器的线程终止并且存在关联的完成例程，则会取消计时器。但是，计时器的状态保持不变。如果没有完成例程，则终止线程对计时器没有影响。

当手动重置计时器设置为信号状态时，它将保持此状态，直到调用 SetWaitableTimer 以重置计时器。因此，在初始到期时间到达时，将定期手动重置计时器设置为信号状态，并在重置之前保持信号状态。当同步计时器设置为信号状态时，它将保持此状态，直到线程完成计时器对象的等待操作。

如果系统时间已调整，则会调整任何未完成的绝对计时器的到期时间。

若要编译使用此函数的应用程序，请将 _WIN32_WINNT 定义为0x0400或更高版本。有关详细信息，请参阅使用 Windows 标头。

若要使用计时器为窗口计划事件，请使用 SetTimer 函数。

处理计时器的 API 使用不同的硬件时钟。这些时钟的分辨率可能与预期的分辨率大相径庭：有些时钟可能以毫秒为单位（对于使用基于 RTC 的计时器芯片的时钟芯片）与以纳秒为单位测量的时钟（对于使用 ACPI 或 TSC 计数器的时钟）。可以通过调用 timeBeginPeriod 和 timeEndPeriod 函数来更改 API 的解析。更改分辨率的精确程度取决于特定 API 使用的硬件时钟。有关详细信息，请查看硬件文档。

例子

有关使用 setWaitableTimer的示例，请参阅使用可等待计时器对象。

要求

要求	价值
最低支持的客户端	Windows XP [桌面应用 \|UWP 应用]
支持的最低服务器	Windows Server 2003 [桌面应用 \|UWP 应用]
目标平台	窗户
标头	synchapi.h （包括 Windows Server 2003、Windows Vista、Windows 7、Windows Server 2008 Windows Server 2008 R2 上的 Windows.h）
库	Kernel32.lib
DLL	Kernel32.dll