Функция NdisSetCoalescableTimerObject (ndis.h)
Функция 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 |