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