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

[in] lPeriod

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

[in] pfnCompletionRoutine

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

[in] lpArgToCompletionRoutine

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

[in] WakeContext

Указатель на структуру REASON_CONTEXT , содержащую сведения о контексте таймера.

[in] TolerableDelay

Допустимое время окончания срока действия в миллисекундах.

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

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

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

Комментарии

Функция SetWaitableTimerExаналогична функции SetWaitableTimer , за исключением того, что SetWaitableTimerEx можно использовать для указания строки контекста и допустимой задержки для истечения срока действия таймера.

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

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

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

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

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

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

Если поток с именем SetWaitableTimerEx завершает работу, таймер отменяется. Это останавливает таймер, прежде чем его можно будет установить в состояние сигнала, и отменяет незавершенные APC; он не изменяет состояние сигнала таймера.

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

Требования

См. также

REASON_CONTEXT

SetWaitableTimer