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

Статья
08/08/2023

Подпрограмма ExAllocateTimer выделяет и инициализирует объект таймера.

Синтаксис

PEX_TIMER ExAllocateTimer(
  [in, optional] PEXT_CALLBACK Callback,
  [in, optional] PVOID         CallbackContext,
  [in]           ULONG         Attributes
);

Параметры

[in, optional] Callback

Указатель на процедуру обратного вызова ExTimerCallback , реализованную драйвером. Операционная система вызывает эту подпрограмму по истечении срока действия таймера. Этот параметр является необязательным и может иметь значение NULL , если подпрограмма обратного вызова не требуется.

[in, optional] CallbackContext

Значение контекста для подпрограммы обратного вызова, на которую указывает параметр Callback . Операционная система передает это значение в качестве параметра в подпрограмму обратного вызова ExTimerCallback , если оно указано. Этот параметр обычно является указателем на структуру, определяемую вызывающим объектом, которая содержит сведения о контексте, используемые подпрограммой обратного вызова. Этот параметр является необязательным и может иметь значение NULL , если сведения о контексте не требуются.

[in] Attributes

Атрибуты таймера. Присвойте этому параметру значение ноль или побитовое ИЛИ одного или нескольких следующих битов флага таймера.

Бит флага таймера	Описание
EX_TIMER_HIGH_RESOLUTION	Таймер с высоким разрешением. Сделайте таймер более точным, используя часы с более высоким разрешением для управления таймером.
EX_TIMER_NO_WAKE	Таймер без пробуждения. Установите для таймера задержку пробуждения процессора до тех пор, пока не будет превышено время окончания срока действия таймера и его допустимость задержки.
EX_TIMER_NOTIFICATION	Таймер уведомлений. Сделайте таймер таймером уведомлений вместо таймера синхронизации. Если этот флаг не установлен, таймер является таймером синхронизации.

Бит флага EX_TIMER_NOTIFICATION можно задать независимо от того, какие другие биты флага установлены.

Биты флагов EX_TIMER_HIGH_RESOLUTION и EX_TIMER_NO_WAKE являются взаимоисключающими. Если вызывающий объект задает оба этих бита флага, выполняется обычная проверка ошибок.

Дополнительные сведения об атрибутах таймера см. в разделе Примечания.

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

Эта подпрограмма возвращает указатель на структуру EX_TIMER , если вызов выполнен успешно. Эта структура представляет собой объект таймера, выделенный и инициализированный подпрограммой. Если вызов завершается сбоем, подпрограмма возвращает значение NULL.

Эта подпрограмма возвращает указатель на новый объект таймера. Чтобы использовать таймер, вызывающий драйвер предоставляет этот указатель в последующих вызовах процедур ExSetTimer, ExCancelTimer и ExDeleteTimer . Если драйвер предоставляет указатель на подпрограмму обратного вызова ExTimerCallback в качестве входного параметра для подпрограммы ExAllocateTimer , операционная система передает этот объект таймера в качестве входного параметра в подпрограмму ExTimerCallback .

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

Если бит флага EX_TIMER_HIGH_RESOLUTION задан в разделе Атрибуты, операционная система при необходимости увеличивает разрешение системных часов, чтобы время истечения срока действия таймера точнее соответствовало номинальному времени окончания срока действия, указанному в параметрах DueTime и Period для подпрограммы ExSetTimer . Дополнительные сведения см. в разделе Таймеры высокого разрешения.

Если бит флага EX_TIMER_NO_WAKE задан в разделе Атрибуты, таймер позволяет избежать ненужного пробуждения процессора из состояния с низким энергопотреблением. Дополнительные сведения см. в разделе Таймеры без пробуждения.

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

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

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

Требования

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

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