SetWaitableTimer 函数 (synchapi.h)
激活指定的可等待计时器。 当到期时间到来时，计时器会发出信号，设置计时器的线程调用可选的完成例程。
语法
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 的时间的详细信息，请参阅 系统时间。
[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 应用] |
| 目标平台 | Windows |
| 标头 | synchapi.h (包括 Windows Server 2003 上的 Windows.h、Windows Vista、Windows 7、Windows Server 2008 Windows Server 2008 R2) |
| Library | Kernel32.lib |
| DLL | Kernel32.dll |