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

Статья
04/06/2023

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

Синтаксис

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

Параметры

[in, optional] hWnd

Тип: HWND

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

[in] nIDEvent

Тип: UINT_PTR

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

[in] uElapse

Тип: UINT

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

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

[in, optional] lpTimerFunc

Тип: TIMERPROC

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

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

Тип: UINT_PTR

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

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

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

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

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

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

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

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

Примеры

Пример см. в разделе Создание таймера.

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	winuser.h (включая Windows.h)
Библиотека	User32.lib
DLL	User32.dll
Набор API	ext-ms-win-ntuser-window-l1-1-2 (появилось в Windows 10 версии 10.0.10240)