Функция ExSetTimer (wdm.h)

Статья
08/08/2023

Подпрограмма ExSetTimer запускает операцию таймера и устанавливает срок действия таймера в указанное время выполнения.

Синтаксис

BOOLEAN ExSetTimer(
  [in]           PEX_TIMER           Timer,
  [in]           LONGLONG            DueTime,
  [in]           LONGLONG            Period,
  [in, optional] PEXT_SET_PARAMETERS Parameters
);

Параметры

[in] Timer

Указатель на структуру EX_TIMER . Эта структура представляет собой объект таймера, который ранее был выделен подпрограммой ExAllocateTimer .

[in] DueTime

Абсолютное или относительное время, в которое истекает срок действия таймера. Если значение параметра DueTime отрицательное, время истечения срока действия будет относительно текущего системного времени. В противном случае срок действия будет абсолютным. Время истечения срока действия выражается в системных единицах времени (100-наносекундные интервалы). Абсолютное время истечения срока действия отслеживает любые изменения системного времени; Изменения системного времени не влияют на относительный срок действия. Абсолютное время выражается как количество прошедшего времени в единицах системного времени с начала 1601 года.

Параметр DueTime для таймера с высоким разрешением должен быть относительным временем (отрицательное значение) или обычными проверками ошибок.

[in] Period

Необязательный период для таймера в системных единицах времени (100-наносекундные интервалы). Значение должно быть меньше или равно MAXLONG. Для таймера, который является однократным, а не периодическим, установите для параметра Период нулевое значение.

[in, optional] Parameters

Указатель на структуру EXT_SET_PARAMETERS . Вызывающий драйвер ранее называл подпрограмму ExInitializeSetTimerParameters для инициализации этой структуры.

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

Эта подпрограмма возвращает значение TRUE , если она отменяет таймер, ожидающий на момент вызова подпрограммы. В противном случае подпрограмма возвращает значение FALSE. Дополнительные сведения см. в подразделе "Примечания".

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

После вызова ExSetTimer драйвер может вызвать подпрограмму, например KeWaitForSingleObject или KeWaitForMultipleObjects , чтобы дождаться истечения срока действия таймера. По истечении срока действия таймера операционная система сообщает объекту таймера.

В качестве варианта драйвер может реализовать подпрограмму обратного вызова ExTimerCallback и указать указатель на эту подпрограмму в качестве входного параметра для подпрограммы ExAllocateTimer . По истечении срока действия таймера операционная система вызывает подпрограмму ExTimerCallback .

Вызов ExSetTimer неявно отменяет все ранее начатые операции set-timer для объекта таймера, заданного параметром Timer. Если драйвер ранее вызывал ExSetTimer , чтобы задать таймер, использующий таймер, и этот таймер еще не истек при повторном вызове ExSetTimer , второй вызов отменяет таймер из первого вызова, а затем запускает новый таймер. В этом случае второй вызов возвращает значение TRUE. Однако если срок действия таймера, запущенного первым вызовом, истекает до того, как второй вызов может отменить этот таймер, второй вызов запускает новый таймер и возвращает значение FALSE.

Если параметр Period не равен нулю, таймер является периодическим. Для периодического таймера параметр DueTime указывает время истечения срока действия начального таймера, а параметр Period — интервал между последующими сроками действия.

Аппаратный таймер, используемый для системных часов, передает запросы прерываний с одинаковыми интервалами, но обработка этих прерываний может быть отложена из-за обработки прерываний для других устройств. Таким образом, для периодического таймера задержка от периодического срока действия до времени, когда объект таймера получает сигнал или выполнения подпрограммы ExTimerCallback , может варьироваться от одного периода к другому. Дополнительные сведения см. в разделе Точность таймера.

Срок действия периодического таймера может истечь не более одного раза для каждого такта системных часов. Задание периода таймера меньше интервала между тактами системных часов не приводит к истечению срока действия таймера более одного раза для каждого такта системных часов, но может привести к изменению интервалов между последовательными истечениями срока действия при изменении частоты системных часов. Например, операционная система может временно увеличить частоту системных часов в соответствии с требованиями таймера с высоким разрешением. Дополнительные сведения см. в разделе Таймеры с высоким разрешением.

Для периодического таймера, который не является таймером с высоким разрешением, драйвер может достичь относительно равномерного периодического истечения срока действия, задав для параметра Period целое число, кратное интервалу по умолчанию между тактами системных часов.

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

Дополнительные сведения см. в статье Подпрограммы ExXxxTimer и объекты EX_TIMER.

Требования

Требование	Значение
Минимальная версия клиента	Доступно начиная с Windows 8.1.
Целевая платформа	Универсальное
Верхняя часть	wdm.h (включая Wdm.h, Ntddk.h, Ntifs.h)
Библиотека	Ntoskrnl.lib
IRQL	<= DISPATCH_LEVEL