Функция SetThreadpoolTimerEx (threadpoolapiset.h)

Статья
03/02/2024

Задает объект таймера, заменяя предыдущий таймер, если он есть. Рабочий поток вызывает обратный вызов объекта таймера по истечении указанного времени ожидания.

Синтаксис

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 , задающую абсолютное или относительное время истечения срока действия таймера. Если этот параметр указывает на положительное значение, он указывает абсолютное время с 1 января 1601 года (UTC), измеряемое в 100 единицах наносекунд. Если этот параметр указывает на отрицательное значение, он указывает время ожидания относительно текущего времени. Если этот параметр указывает на ноль, таймер немедленно истечет. Дополнительные сведения о значениях времени см. в разделе File Times.

Если этот параметр имеет значение 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
Header	threadpoolapiset.h
Библиотека	Kernel32.lib
DLL	Kernel32.dll