Функция 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
Дескриптор объекта таймера. Функция 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 или сброса с помощью SetWaitableTimerEx. Если lPeriod меньше нуля, функция завершается ошибкой.
[in] pfnCompletionRoutine
Указатель на необязательную подпрограмму завершения. Подпрограмма завершения — это определяемая приложением функция типа PTIMERAPCROUTINE выполняться при сигнале таймера. Дополнительные сведения о функции обратного вызова таймера см. в разделе TimerAPCProc. Дополнительные сведения об API и потоках пула потоков см. в примечаниях.
[in] lpArgToCompletionRoutine
Указатель на структуру, передаваемую в подпрограмму завершения.
[in] WakeContext
Указатель на структуру REASON_CONTEXT, содержащую сведения о контексте таймера.
[in] TolerableDelay
Допускаемая задержка для срока действия в миллисекундах.
Возвращаемое значение
Если функция выполнена успешно, возвращаемое значение ненулевое.
Если функция завершается ошибкой, возвращаемое значение равно нулю. Чтобы получить расширенные сведения об ошибке, вызовите GetLastError.
Замечания
Функция SetWaitableTimerEx аналогична функции SetWaitableTimer, за исключением SetWaitableTimerEx можно использовать для указания строки контекста и допустимой задержки для истечения срока действия таймера.
Чтобы скомпилировать приложение, использующее эту функцию, определите _WIN32_WINNT как 0x0601 или более поздней версии. Дополнительные сведения см. в разделе Использование заголовков Windows.
Таймеры изначально неактивны. Чтобы активировать таймер, вызовите SetWaitableTimerEx. Если таймер уже активен при вызове SetWaitableTimerEx, таймер остановлен, то он активируется повторно. Остановка таймера таким образом не задает состояние таймера для сигнала, поэтому потоки, заблокированные в операции ожидания таймера, остаются заблокированными. Однако он отменяет все ожидающие подпрограммы завершения.
При поступлении указанного времени ожидания таймер становится неактивным, а необязательный APC помещается в поток, задающий таймер, если выдающийся APC уже не указан. Состояние таймера задано для сигнала, таймер повторно активируется с помощью указанного периода, и поток, задающий таймер, вызывает подпрограмму завершения при входе в оповещенное состояние ожидания. Дополнительные сведения см. в разделе QueueUserAPC. Обратите внимание, что API-интерфейсы не работают, а также другие механизмы сигнализации для потоков пула потоков, так как система управляет временем существования потоков пула потоков, поэтому перед доставкой уведомления можно завершить поток. Вместо использования параметра pfnCompletionRoutine или другого механизма сигнализации на основе APC используйте ожидающий объект, например таймер, созданный с помощью CreateThreadpoolTimer. Для ввода-вывода используйте объект завершения ввода-вывода, созданный с помощью CreateThreadpoolIo или hEventна основе OVERLAPPED структуры, в которой событие можно передать в функцию SetThreadpoolWait.
Если поток, устанавливающий таймер, завершается и существует связанная подпрограмма завершения, таймер отменяется. Однако состояние таймера остается неизменным. Если подпрограмма завершения отсутствует, то завершение потока не влияет на таймер.
Если таймер сброса вручную устанавливается в сигнальное состояние, он остается в этом состоянии, пока не будет вызываться SetWaitableTimerEx для сброса таймера. В результате периодический таймер сброса вручную устанавливается в сигнальное состояние, когда начальное время выполнения прибывает и остается сигналом до сброса. Если таймер синхронизации установлен в сигнальном состоянии, он остается в этом состоянии, пока поток не завершит операцию ожидания в объекте таймера.
Если системное время корректируется, то время выполнения любых выдающихся абсолютных таймеров корректируется.
Если поток, который вызывается SetWaitableTimerEx, то таймер отменяется. Это останавливает таймер, прежде чем его можно установить в сигнальное состояние и отменяет невыполненные API; Он не изменяет сигнальное состояние таймера.
Чтобы использовать таймер для планирования события для окна, используйте функцию SetTimer.
Требования
| Требование | Ценность |
|---|---|
| минимальные поддерживаемые клиентские | Windows 7 [классические приложения | Приложения UWP] |
| минимальный поддерживаемый сервер | Windows Server 2008 R2 [классические приложения | Приложения UWP] |
| целевая платформа | Виндоус |
| заголовка | synchapi.h (включая Windows.h) |
| библиотеки |
Kernel32.lib |
| DLL | Kernel32.dll |