Функция NdisSetCoalescableTimerObject (ndis.h)

Статья
08/07/2023

Функция NdisSetCoalescableTimerObject задает объект таймера, который операционная система координирует с другими таймерами, обычно для снижения энергопотребления, когда точный срок действия таймера не важен для работы драйвера.

Синтаксис

BOOLEAN NdisSetCoalescableTimerObject(
  [in]           NDIS_HANDLE   TimerObject,
  [in]           LARGE_INTEGER DueTime,
  [in, optional] LONG          MillisecondsPeriod,
  [in, optional] PVOID         FunctionContext,
  [in, optional] ULONG         Tolerance
);

Параметры

[in] TimerObject

Дескриптор объекта таймера, который NDIS предоставляет, когда драйвер вызываетФункция NdisAllocateTimerObject.

[in] DueTime

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

[in, optional] MillisecondsPeriod

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

[in, optional] FunctionContext

Указатель на область контекста, предоставленную вызывающим объектом, которую NDIS передает связанной функции NetTimerCallback при срабатывании таймера. Если этот параметр имеет значение NULL, NDIS использует значение по умолчанию, указанное в NDIS_TIMER_CHARACTERISTICS структура.

[in, optional] Tolerance

Отклонение (в миллисекундах) между периодом таймера, заданным параметром MillisecondsPeriod , и начальным интервалом времени, указанным в DueTime . Периодический таймер сначала истечет в интервале времени между ( DueTime - Tolerance ) и ( DueTime + Tolerance ). Интервал времени между двумя более поздними сроками действия периодического таймера будет находиться в диапазоне ( MillisecondsPeriod - Tolerance ) и ( MillisecondsPeriod + Tolerance ).

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

NdisSetCoalescableTimerObject возвращает значение TRUE , если объект таймера уже находился в очереди системного таймера; в противном случае возвращается значение FALSE.

Объект таймера, заданный этой функцией, работает так же, как и таймер, заданный NdisSetTimerObject, с дополнительным значением допуска, добавленным к параметру expiration DueTime . Операционная система использует это дополнительное значение допустимости, чтобы настроить время окончания срока действия таймера так, чтобы оно совпадает с истечением срока действия других программных таймеров. Благодаря этому операционная система может снизить энергопотребление и повысить энергоэффективность.

NdisSetTimerObject работает аналогично NdisSetCoalescableTimerObject , если значение Tolerance равно нулю.

После вызова драйвером NdisSetCoalescableTimerObject объект таймера помещается в очередь до истечения интервала, который находится в диапазоне ( DueTime - Tolerance ) и ( DueTime + Tolerance ). По истечении этого интервала операционная система удаляет объект таймера из очереди, а предоставляемая вызывающим объектом функция NetTimerCallback запускается один раз в IRQL = DISPATCH_LEVEL, как только процессор становится доступным.

Если в параметре MillisecondsPeriod указано ненулевое значение, объект таймера снова помещается в очередь до тех пор, пока не истечет интервал в диапазоне ( MillisecondsPeriod - Tolerance ) и ( MillisecondsPeriod + Tolerance ) . По истечении этого интервала объект таймера повторно отправляется в очередь, а предоставляемая вызывающим объектом функция NetTimerCallback запускается один раз в IRQL = DISPATCH_LEVEL, как только процессор становится доступным.

Чтобы эффективно использовать объединение таймеров, вызывающий объект должен задать значение Tolerance не менее 32 миллисекунда. Это значение равно примерно двум интервалам системных часов по умолчанию в 15,6 миллисекундах. Если это возможно, используйте большее значение Tolerance , например 100 миллисекундах.

Рекомендуется задать значение MillisecondsPeriod и Tolerance , кратное 50 миллисекундам. Типичные значения MillisecondsPeriod — 50, 100, 250, 500 и 1000 миллисекунд. Типичные значения Tolerance : 50, 100, 150 и 250 миллисекунд.

Как правило, таймер с большим значением MillisecondsPeriod может использовать пропорционально большое значение Tolerance . Например, для таймера с значением MillisecondsPeriod = 500 миллисекундам может использоваться значение Tolerance = 50 миллисекундах. Но для таймера с миллисекундамиPeriod = 10 секунд может использоваться значение Tolerance = 1 секунда.

Дополнительные сведения о поведении таймера см. в разделе KeSetTimerEx.

Чтобы отменить таймер, вызовите функцию NdisCancelTimerObject .

Требования

Требование	Значение
Минимальная версия клиента	Поддерживается в NDIS 6.20 и более поздних версиях.
Целевая платформа	Универсальное
Верхняя часть	ndis.h (включая Ndis.h)
Библиотека	Ndis.lib
IRQL	<= DISPATCH_LEVEL