Функция SetCoalescableTimer (winuser.h)

Создает таймер с указанным значением времени ожидания и задержкой допуска объединения.

Синтаксис

UINT_PTR SetCoalescableTimer(
  [in, optional] HWND      hWnd,
  [in]           UINT_PTR  nIDEvent,
  [in]           UINT      uElapse,
  [in, optional] TIMERPROC lpTimerFunc,
  [in]           ULONG     uToleranceDelay
);

Параметры

[in, optional] hWnd

Тип: HWND

Дескриптор окна, связанного с таймером. Это окно должно принадлежать вызывающей цепочке. Если значение NULL для hWnd передается вместе с nIDEvent существующего таймера, этот таймер будет заменен так же, как существующий таймер hWnd , отличный от NULL.

[in] nIDEvent

Тип: UINT_PTR

Идентификатор таймера. Если параметр hWnd имеет значение NULL и nIDEvent не соответствует существующему таймеру, то nIDEvent игнорируется и создается новый идентификатор таймера. Если параметр hWnd не равен NULL и в окне, указанном в hWnd , уже есть таймер со значением nIDEvent, то существующий таймер заменяется новым таймером. Когда SetCoalescableTimer заменяет таймер, таймер сбрасывается. Таким образом, сообщение будет отправлено по истечении текущего значения времени ожидания, но ранее заданное значение времени ожидания игнорируется. Если вызов не предназначен для замены существующего таймера, nIDEvent должен иметь значение 0, если hWnd имеет значение NULL.

[in] uElapse

Тип: UINT

Значение времени ожидания в миллисекундах.

Если значение uElapse меньше USER_TIMER_MINIMUM (0x0000000A), время ожидания устанавливается в USER_TIMER_MINIMUM. Если uElapse больше USER_TIMER_MAXIMUM (0x7FFFFFFF), время ожидания устанавливается в USER_TIMER_MAXIMUM.

Если сумма значений uElapse и uToleranceDelay превышает USER_TIMER_MAXIMUM, возникает ERROR_INVALID_PARAMETER исключение.

[in, optional] lpTimerFunc

Тип: TIMERPROC

Указатель на функцию, извещаемую по истечении времени ожидания. Дополнительные сведения о функции см. в разделе TimerProc. Если lpTimerFunc имеет значение NULL, система отправляет WM_TIMER сообщение в очередь приложения. Элемент hwnd структуры MSG сообщения содержит значение параметра hWnd .

[in] uToleranceDelay

Тип: ULONG

Может иметь одно из следующих значений.

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

Тип: UINT_PTR

Если функция выполняется успешно и параметр hWnd имеет значение NULL, возвращаемое значение будет целым числом, определяющим новый таймер. Приложение может передать это значение в функцию KillTimer , чтобы уничтожить таймер.

Если функция выполняется успешно и параметр hWnd не равен NULL, то возвращаемое значение является ненулевым целым числом. Приложение может передать значение параметра nIDEvent в функцию KillTimer , чтобы уничтожить таймер.

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

Комментарии

Приложение может обрабатывать WM_TIMER сообщения, включив оператор WM_TIMER case в процедуру окна или указав функцию обратного вызова TimerProc при создании таймера. При указании функции обратного вызова TimerProc процедура окна по умолчанию вызывает функцию обратного вызова при обработке WM_TIMER. Поэтому необходимо отправлять сообщения в вызывающий поток, даже если вместо обработки WM_TIMER используется TimerProc.

Параметр wParamсообщения WM_TIMER содержит значение параметра nIDEvent .

Идентификатор таймера nIDEvent зависит от связанного окна. Другое окно может иметь собственный таймер, который имеет тот же идентификатор, что и таймер, принадлежащий другому окну. Таймеры различаются.

SetTimer может повторно использовать идентификаторы таймера в случае, когда hWnd имеет значение NULL.

Если для uToleranceDelay задано значение 0, используется объединение системного таймера по умолчанию, а SetCoalescableTimer ведет себя так же, как SetTimer.

Перед использованием SetCoalescableTimer или других функций, связанных с таймером, рекомендуется установить для флага UOI_TIMERPROC_EXCEPTION_SUPPRESSION значение false с помощью функции SetUserObjectInformationW , в противном случае приложение может вести себя непредсказуемо и быть уязвимым к эксплойтам безопасности. Дополнительные сведения см. в разделе SetUserObjectInformationW.

Требования

См. также раздел

Пример таймеров объединения

Основные понятия

KeSetCoalescableTimer

KeSetTimer

KillTimer

MSG

Справочные материалы

Образец

SetTimer

TimerProc

Таймеры

Использование таймеров

WM_TIMER