Функция 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 см. в разделе Системное время.

[in] lPeriod

Период таймера в миллисекундах. Если значение lPeriod равно нулю, таймер получает сигнал один раз. Если значение lPeriod больше нуля, таймер является периодическим. Периодический таймер автоматически активируется повторно каждый раз, когда истекает период, пока таймер не будет отменен с помощью функции CancelWaitableTimer или сброс с помощью SetWaitableTimer. Если значение lPeriod меньше нуля, функция завершается ошибкой.

[in, optional] pfnCompletionRoutine

Указатель на необязательную подпрограмму завершения. Подпрограмма завершения — это определяемая приложением функция типа PTIMERAPCROUTINE , выполняемая при сигнале таймера. Дополнительные сведения о функции обратного вызова таймера см. в разделе TimerAPCProc. Дополнительные сведения о APC и потоках пула потоков см. в разделе Примечания.

[in, optional] lpArgToCompletionRoutine

Указатель на структуру, которая передается в подпрограмму завершения.

[in] fResume

Если этот параметр имеет значение TRUE, восстанавливает систему в режиме приостановленного сохранения питания, когда состояние таймера равно сигнальное. В противном случае система не восстанавливается. Если система не поддерживает восстановление, вызов выполняется успешно, но GetLastError возвращает ERROR_NOT_SUPPORTED.

Возвращаемое значение

Если функция выполняется успешно, возвращается ненулевое значение.

Если функция выполняется неудачно, возвращается нулевое значение. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

Комментарии

Таймеры изначально неактивны. Чтобы активировать таймер, вызовите SetWaitableTimer. Если таймер уже активен при вызове SetWaitableTimer, таймер останавливается, а затем активируется повторно. Остановка таймера таким образом не устанавливает состояние таймера в сигнал, поэтому потоки, заблокированные в операции ожидания таймера, остаются заблокированными. Однако он отменяет все ожидающие процедуры завершения.

По истечении указанного срока таймер становится неактивным, а необязательный APC помещается в очередь в поток, задающий таймер, если еще нет ожидающих APC в очереди. Для таймера задано состояние signaled, таймер повторно активируется с помощью указанного периода, а поток, задающий таймер, вызывает подпрограмму завершения при переходе в состояние ожидания с оповещениями. Дополнительные сведения см. в разделе QueueUserAPC. Обратите внимание, что APC не работают так же, как другие механизмы сигнализации для потоков пула потоков, так как система управляет временем существования потоков пула потоков, поэтому поток можно завершить до доставки уведомления. Вместо использования параметра pfnCompletionRoutine или другого механизма сигнализации на основе APC используйте объект, доступный для ожидания, например таймер, созданный с помощью CreateThreadpoolTimer. Для ввода-вывода используйте объект завершения ввода-вывода, созданный с помощью CreateThreadpoolIo, или структуру OVERLAPPED на основе hEvent, где событие можно передать в функцию SetThreadpoolWait.

Если поток, задал таймер, завершается и имеется связанная подпрограмма завершения, таймер отменяется. Однако состояние таймера остается неизменным. Если подпрограмма завершения отсутствует, завершение потока не влияет на таймер.

Если для таймера сброса вручную задано состояние сигнала, он остается в этом состоянии до вызова SetWaitableTimer для сброса таймера. В результате периодический таймер сброса вручную устанавливается в состояние сигналов при достижении начального срока выполнения и остается сигнальным до сброса. Если для таймера синхронизации задано состояние сигнала, он остается в этом состоянии до тех пор, пока поток не завершит операцию ожидания для объекта таймера.

Если системное время корректируется, корректируется время выполнения любых необработанных абсолютных таймеров.

Чтобы скомпилировать приложение, использующее эту функцию, определите _WIN32_WINNT как 0x0400 или более поздней версии. Дополнительные сведения см. в разделе Использование заголовков Windows.

Чтобы запланировать событие для окна с помощью таймера, используйте функцию SetTimer .

API, которые используют таймеры, используют различные аппаратные часы. Эти часы могут иметь разрешение, значительно отличающееся от ожидаемого: некоторые из них могут измеряться в миллисекундах (для тех, которые используют микросхему таймера на основе RTC) до тех, которые измеряются в наносекундах (для счетчиков ACPI или TSC). Разрешение API можно изменить с помощью вызова функций timeBeginPeriod и timeEndPeriod . Насколько точно можно изменить разрешение, зависит от того, какие аппаратные часы использует конкретный API. Дополнительные сведения проверка документации по оборудованию.

Примеры

Пример использования SetWaitableTimer см. в разделе Использование объектов таймера для ожидания.

Требования

См. также

CancelWaitableTimer

CreateWaitableTimer

OpenWaitableTimer

Функции синхронизации

TimerAPCProc

Объекты таймера, доступные для ожидания