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 指定的初始时间间隔之间的容差（以毫秒为单位）。定期计时器将在 ( DueTimeTolerance ) 与 ( DueTime + - Tolerance ) 之间的时间间隔内首次过期。定期计时器的两个稍后过期之间的时间间隔在 ( 毫秒容错 - ) 和 ( 毫秒容错 + ) 范围内 。

返回值

如果计时器对象已在系统计时器队列中，则 NdisSetCoalescableTimerObject 返回 TRUE;否则，它将返回 FALSE。

注解

此函数设置的计时器对象的运行方式与 NdisSetTimerObject 设置的计时器相同，并将额外的容差值添加到过期参数 DueTime 。操作系统使用此额外的容差值来调整计时器的过期时间，以与其他软件计时器的过期时间一致。通过执行此操作，操作系统可以降低能耗并提高能源效率。

当 Tolerance 设置为零时，NdisSetTimerObject 的运行方式与 NdisSetCoalescableTimerObject 类似。

驱动程序调用 NdisSetCoalescableTimerObject 后，计时器对象将排入队列，直到某个间隔过期，该间隔在 ( DueTime - Tolerance ) 范围内， ( DueTime + Tolerance ) 。间隔到期后，操作系统将从队列中删除计时器对象，一旦处理器可用，调用方提供的 NetTimerCallback 函数将在 IRQL = DISPATCH_LEVEL 运行一次。

如果在 MillisecondsPeriod 参数中指定了非零值，计时器对象将再次排队，直到 ( 毫秒 - 容错 ) 范围内的间隔和 ( 毫秒 + 容错 ) 过期 。此间隔到期后，计时器对象将重新提交到队列，一旦处理器可用，调用方提供的 NetTimerCallback 函数将在 IRQL = DISPATCH_LEVEL运行一次。

若要有效地使用计时器合并，调用方应指定至少 32 毫秒的容差值。此值大约等于两个默认系统时钟间隔（15.6 毫秒）。如果可以执行此操作，请使用更大的 “容差 ”值，例如 100 毫秒。

建议将 MillisecondsPeriod 和 Tolerance 设置为 50 毫秒的倍数。典型的 毫秒常 值为 50、100、250、500 和 1000 毫秒。典型的容差值为 50、100、150 和 250 毫秒。

通常，具有较大 MillisecondsPeriod 值的计时器可以使用成比例较大的容差值。例如， MillisecondsPeriod = 500 毫秒的计时器可能使用 Tolerance = 50 毫秒。但是 ，MillisecondsPeriod = 10 秒的计时器可能使用 Tolerance = 1 秒。

有关计时器行为的详细信息，请参阅 KeSetTimerEx。

若要取消计时器，请调用 NdisCancelTimerObject 函数。

要求

要求	值
最低受支持的客户端	在 NDIS 6.20 及更高版本中受支持。
目标平台	通用
标头	ndis.h (包括 Ndis.h)
Library	Ndis.lib
IRQL	<= DISPATCH_LEVEL