SetWaitableTimerEx 函数 (synchapi.h)

激活指定的可等待计时器并为计时器提供上下文信息。 当到期时间到达时,计时器将发出信号,设置计时器的线程将调用可选的完成例程。

语法

BOOL SetWaitableTimerEx(
  [in] HANDLE              hTimer,
  [in] const LARGE_INTEGER *lpDueTime,
  [in] LONG                lPeriod,
  [in] PTIMERAPCROUTINE    pfnCompletionRoutine,
  [in] LPVOID              lpArgToCompletionRoutine,
  [in] PREASON_CONTEXT     WakeContext,
  [in] ULONG               TolerableDelay
);

参数

[in] hTimer

计时器对象的句柄。 CreateWaitableTimerOpenWaitableTimer 函数返回此句柄。

句柄必须具有 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 函数取消计时器,或使用 setWaitableTimerEx重置计时器。 如果 lPeriod 小于零,则函数将失败。

[in] pfnCompletionRoutine

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

[in] lpArgToCompletionRoutine

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

[in] WakeContext

指向包含计时器上下文信息的 REASON_CONTEXT 结构的指针。

[in] TolerableDelay

过期时间的可容忍延迟(以毫秒为单位)。

返回值

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

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

言论

SetWaitableTimerEx 函数类似于 setWaitableTimer 函数 ,但 SetWaitableTimerEx 可用于指定上下文字符串和计时器过期的可容忍延迟。

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

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

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

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

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

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

如果调用 SetWaitableTimerEx 的线程 退出,则会取消计时器。 这会停止计时器,然后才能将其设置为信号状态并取消未完成的 APC;它不会更改计时器的信号状态。

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

要求

要求 价值
最低支持的客户端 Windows 7 [桌面应用 |UWP 应用]
支持的最低服务器 Windows Server 2008 R2 [桌面应用 |UWP 应用]
目标平台 窗户
标头 synchapi.h (包括 Windows.h)
Kernel32.lib
DLL Kernel32.dll

另请参阅

REASON_CONTEXT

SetWaitableTimer