SetThreadpoolTimerEx 函数 (threadpoolapiset.h)

项目
08/26/2023

设置计时器对象，替换上一个计时器（如果有）。工作线程在指定的超时到期后调用计时器对象的回调。

语法

BOOL SetThreadpoolTimerEx(
  [in, out]      PTP_TIMER pti,
  [in, optional] PFILETIME pftDueTime,
  [in]           DWORD     msPeriod,
  [in, optional] DWORD     msWindowLength
);

参数

[in, out] pti

指向 TP_TIMER 结构的指针，该结构定义要设置的计时器对象。 CreateThreadpoolTimer 函数返回此指针。

[in, optional] pftDueTime

指向 FILETIME 结构的指针，该结构指定计时器应过期的绝对时间或相对时间。如果此参数指向正值，则表示自 1601 年 1 月 1 日 (UTC) 以来的绝对时间，以 100 纳秒为单位。如果此参数指向负值，则指示相对于当前时间等待的时间量。如果此参数指向零，则计时器将立即过期。有关时间值的详细信息，请参阅文件时间。

如果此参数为 NULL，则计时器对象将停止对新回调 (排队，但已排队的回调仍将) 发生。

如果 pftDueTime 参数为非 NULL，则设置计时器。

[in] msPeriod

计时器周期，以毫秒为单位。如果此参数为零，则会向计时器发出一次信号。如果此参数大于零，则计时器是定期的。定期计时器会在每次经过该时间段时自动重新激活，直到计时器被取消。

[in, optional] msWindowLength

在调用计时器回调之前，系统可以延迟的最长时间。如果设置了此参数，则系统可以批量调用以节省电源。

返回值

如果之前设置了计时器并已取消，则返回 TRUE。否则返回 FALSE。

如果计时器的上一状态为“设置”，并且函数返回 FALSE，则回调正在进行或即将开始。有关进一步讨论，请参阅备注。

注解

设置计时器会取消上一个计时器（如果有）。

在某些情况下，回调函数可能会在应用程序关闭线程池计时器后运行。若要防止此行为，应用程序应遵循 CloseThreadpoolTimer 中所述的步骤。

如果 pftDueTime 指定的到期时间是相对的，则系统处于睡眠或休眠状态的时间不计入计时器的过期时间。当系统处于唤醒状态的累积已用时间量等于计时器的相对到期时间或时间段时，计时器将发出信号。如果 pftDueTime 指定的到期时间是绝对的，则系统处于睡眠或休眠状态的时间将计入计时器的过期时间。如果在系统处于睡眠状态时计时器过期，则会在系统唤醒时立即发出该计时器的信号。

若要编译使用此函数的应用程序，请将_WIN32_WINNT定义为 0x0600 或更高版本。

示例

有关示例，请参阅使用线程池函数。

要求

要求	值
最低受支持的客户端	Windows 8 [桌面应用 \|UWP 应用]
最低受支持的服务器	Windows Server 2012 [桌面应用 \|UWP 应用]
目标平台	Windows
标头	threadpoolapiset.h
Library	Kernel32.lib
DLL	Kernel32.dll